SECURE MULTI-AGENT EXECUTION RUNTIME

Octopal is a local AI agent runtime designed for safe, autonomous execution.

It runs as a persistent operator that plans tasks, delegates work, and executes actions through isolated workers — keeping your system protected by design.

At the core is the Octo: a long-running coordinator that holds memory, reasons about tasks, selects tools, and orchestrates execution.

Instead of acting directly, Octo delegates all side effects to Workers — short-lived, sandboxed agents with limited context and strict permissions.

This creates a hard separation between thinking and doing: the system that decides never touches the outside world, and the system that acts is fully controlled.

Table of contents

• 🪛 What it can do
• 🚀 Quick start
• ✨ Key features

🔒 Secure by Default Execution

Octopal is designed with a strict isolation model for all workers.

• Workers run in ephemeral Docker containers by default
• No access to your system or workspace unless explicitly granted
• Filesystem access is restricted via allowlisted paths
• Environment variables and secrets are never exposed to workers
• Each execution is sandboxed and fully disposable

Even when interacting with untrusted content (web pages, scripts, external tools), workers operate in a controlled environment that prevents system compromise.

Why this matters

Modern AI agents frequently interact with untrusted data (web pages, APIs, generated code). Without isolation, a simple tool call (e.g. shell execution or remote fetch) can expose your system.

Octopal prevents this by design: workers cannot access your system, secrets, or filesystem unless explicitly allowed.

🪛 What It Can Do

• Run as a persistent AI operator over Telegram or WhatsApp
• Plan work and delegate tasks to specialized workers
• Execute filesystem, web, browser, shell, and MCP tools under policy controls
• Create and reuse worker templates, MCP server connections, and SKILL.md-based skills
• Maintain persistent memory, canon, and user/system identity files
• Monitor context health and trigger structured context resets when needed
• Schedule recurring tasks and background routines
• Expose a private gateway and dashboard for status, workers, and system visibility
• A set of canonical memory files shapes the system environment

User
   │
Channels (Telegram / WhatsApp / WS)
   │
 Octo
   │
 Worker Pool
   │
 Tools / MCP / Skills
   │
 External Systems

Example workflow:

User: "Research the latest Gemini model and write a summary."

Octo:

1. Spawns Web Researcher
2. Researcher fetches sources
3. Writer worker generates a summary
4. Octo stores canon entry
5. Result returned to the user

🚀 Quick Start

Install with one line

macOS/Linux:

curl -fsSL https://octopal.ca/octopal.sh | bash

Windows:

irm https://octopal.ca/octopal.ps1 | iex

Complete configuration in CLI. You can always change the configuration using uv run octopal configure command.

Optional: WhatsApp setup

After you configure your WhatsApp number in the config link Octopal as a new device

uv run octopal whatsapp link

Open the web dashboard

After bootstrap, start Octopal and then open the dashboard in your browser:

uv run octopal start

Open http://127.0.0.1:8001/dashboard (change to Tailscale IP for remote access)

If you enabled dashboard protection during octopal configure, use the gateway.dashboard_token value from config.json when the dashboard or dashboard API asks for it.

If the page says the dashboard is unavailable, build and enable the web app first:

cd webapp
npm run build

Then enable the dashboard bundle in config.json by setting "gateway": { "webapp_enabled": true } and start Octopal again.

⚒️ Manual setup

If you do not want the bootstrap script, use the manual path below.

git clone https://github.com/pmbstyle/Octopal.git
cd Octopal
uv sync
uv run octopal configure

Alternative without uv:

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -e .

Then run:

uv run octopal configure

configure creates or updates config.json and bootstraps workspace files if missing.

Configuration model

config.json is the configuration file.

• uv run octopal configure writes the structured config there.

Start

# background mode
uv run octopal start

# foreground mode
uv run octopal start --foreground

Core Commands

uv run octopal start
uv run octopal stop
uv run octopal restart
uv run octopal status
uv run octopal logs --f

Docker Worker Launcher

Docker workers are the default and recommended runtime. You can build the worker image up front:

uv run octopal build-worker-image --tag octopal-worker:latest

Then set in config.json:

{
  "workers": {
    "launcher": "docker",
    "docker_image": "octopal-worker:latest"
  }
}

Restart Octopal after config changes.

uv run octopal restart

If Docker CLI and the Docker daemon are available but the configured worker image is missing, Octopal will try to build it automatically on startup. If Docker is unavailable or the automatic build fails, Octopal will temporarily fall back to same_env and surface the reason in octopal status and the dashboard.

Workers keep their own scratch workspace by default. To share files from Octo's main workspace with a worker, pass explicit allowed_paths; if allowed_paths is omitted, the worker does not get broad workspace access.

✨ Key Features

💻 Local and Cloud deployment

Octopal can work from any environment that supports Python execution. Fast and simple bootstrap onboarding helps you to start using Octopal right away.

• deploy on your local PC (Linux, Windows, MacOS)
• deploy on a VPS
• deploy in Docker

Octopal works from a specified directory and has no access to your system components.

🧠 Delegation-driven architecture

Octo, which holds all system context and sensitive data, never communicates with the outside world on its own. Instead, the Octo delegates tasks to workers with limited context and predefined tool/skill sets. Workers can spawn subworkers for multi-step tasks. Workers can only return response of their tasks or question/error responses.

• Octo delegates external operations to workers, which ensures context isolation, enhances security, and provides async task execution
• workers execute in an isolated environment, which gets deleted after each execution
• workers can act as orchestrators and create sub-workers for multi-tasking
• workers operate with a predefined set of tools, MCP, and skills in their config as well as max_thinking_steps and execution_timeout
• the Octo can create new workers for a specific task (ex. use a skill to work with an external resource)
• Prebuilt worker templates include:
  • Web Researcher
  • Web Fetcher
  • Data Analyst
  • Code Worker
  • Writer
  • DevOps / Release Manager
  • Security Auditor
  • Test Runner
  • System Self-Controller
  • DB Maintainer
  • Repo Researcher
  • Bug Investigator

📃 Multilayer memory system

Octo operates with a local vector database to store communication history and file-based context:

• MEMORY.md – working memory and durable context; important facts, current state, and notes the system may need across sessions
• memory/canon/ – curated long-term knowledge that has been reviewed and promoted into trusted reference material
• USER.md – user profile, preferences, habits, and interaction style
• SOUL.md – system identity, values, tone, and core behavioral principles
• HEARTBEAT.md – recurring duties, monitoring loops, schedules, and background obligations

See docs/memory.md.

🤖 Multi-channel user communication

Octopal supports:

• Telegram (Botfather)
• WhatsApp (Dedicated or personal numbers)
• WS API gateway (Build or bring your own client)

Communication channels, by default, provide full support of functions like:

• text communication

• image attachments

• message reactions

• 5s grace window for user messages:

  You can send a followback message before the Octo executes it - this helps to prevent typos, wrong commands, etc.

⚙️ Web dashboard

The Dashboard provides a real-time, comprehensive view of the system's state, active workers, and communication logs. It is built as a modern Vite + React web application.

• Secure by default: Built-in token-based authentication and optional Tailscale integration.
• Real-time updates: Uses WebSockets for live streaming of agent thoughts and tool executions.
• Terminal mode: Access a live view directly from your CLI via octopal dashboard --watch.

🔒 Remote Access & Security (Tailscale)

Octopal features first-class integration with Tailscale to provide secure remote access without opening ports or configuring complex firewalls:

• Automatic Tunneling: If Tailscale is installed, Octopal can automatically run tailscale serve to expose the gateway to your private tailnet.
• IP-Based Authorization: The WebSocket and Dashboard APIs automatically verify that incoming connections originate from trusted Tailscale nodes or your local machine.
• Easy Configuration: Managed via config.json in the gateway section.

{
  "gateway": {
    "tailscale_auto_serve": true,
    "tailscale_ips": "100.x.y.z,100.a.b.c"
  }
}

🧩 Skills and skill bundles

Octopal supports workspace-local skill bundles under workspace/skills/<skill-id>/.

• auto-discovers SKILL.md bundles
• keeps skills/registry.json as a compatibility layer
• supports optional scripts/, references/, and assets/
• exposes readiness checks for required binaries and env vars
• runs bundled scripts through a dedicated safe runner instead of raw shell
• can install external skills with ClawHub-style commands like uv run octopal skill install <publisher>/<skill-pack>
• also accepts direct SKILL.md URLs and local bundle paths
• supports installer lifecycle commands: skill install, skill list, skill update, skill trust, skill untrust, skill remove
• shows both local workspace skills and installer-managed skills in skill list
• requires isolated per-skill runtime envs for Python and JS/TS script-backed skills
• auto-verifies imported scripts and auto-prepares isolated envs during install/update when possible

See docs/skills.md for the current format and behavior.

🛜 Connectors (experimental)

Connectors are the integration layer between Octopal and external services. Octopal will operate with selected services on your behalf.

• Google Connector

  

  Gmail | Google Calendar | Google Drive

• GitHub Connector

  

See docs/connectors.md for more info.

Troubleshooting

Telegram bot starts but does not reply

• Verify telegram.bot_token in config.json
• Verify your chat ID is listed in telegram.allowed_chat_ids
• Check uv run octopal status and uv run octopal logs --follow

WhatsApp is selected, but not receiving messages

• Verify user_channel is set to whatsapp in config.json
• Verify your phone number is listed in whatsapp.allowed_numbers
• Run uv run octopal whatsapp install-bridge
• Run uv run octopal whatsapp link
• Start Octopal again and check uv run octopal whatsapp status

LLM errors

• Run uv run octopal configure and pick the provider you want to use.
• In your config file, check llm.provider_id, llm.model, and llm.api_key in config.json.

Web search/fetch issues

Add the preferred search engine API key in your config.json

"search": {
    "brave_api_key": null,
    "firecrawl_api_key": null
},