Octopal
A local personal AI operator that delegates real work to isolated, disposable workers.
- Source repo
- pmbstyle/Octopal
- Stars
- ★ 10
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 61/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A privacy-conscious individual who wants a personal operator on a laptop or server can send work through Telegram, WhatsApp, or the desktop app.
- Not a fit if
- Users who cannot install or run Docker and its daemon
- Users wanting zero-config Telegram or WhatsApp channel setup
- Source review
- 61/100 · Some gaps
What does this agent do, and when should you use it?
Octopal is a local autonomous-agent platform for a computer or server, built around a long-lived Octo coordinator and short-lived workers. Users can interact through Telegram, WhatsApp, the desktop app, or a private WebSocket/dashboard client, with the dashboard served locally on port 8000. Octo owns conversation, policy, routing, and layered memory, while workers browse, run shell commands, access files, call MCP servers, use skills and connectors, and return structured results, questions, or errors. Docker is the default worker launcher, giving workers a scratch workspace and explicitly granted allowed_paths; trusted local-development work can instead use same_env when selected explicitly. The runtime also documents multi-provider models, scheduled tasks, private A2A collaboration, and connectors for Google services and GitHub-oriented workflows.
A user message reaches the Octo coordinator, which applies policy and memory before creating or selecting workers for the task. Workers can browse and fetch the web, use browser tooling, run shell commands, touch permitted files, call MCP servers, use skills and connectors, then return structured results, questions, or errors; supplied templates include Web Researcher, Code Worker, Test Runner, Security Auditor, Repo Researcher, and DevOps / Release Manager. Durable MCP operations are managed through mcp_task_get, mcp_task_update, and mcp_task_cancel. The octopal CLI configures and runs the service, while scheduled tasks can execute recurring work and deliver reports through the selected channel.
- A privacy-conscious individual who wants a personal operator on a laptop or server can send work through Telegram, WhatsApp, or the desktop app.
- A researcher preparing a source-heavy technology brief can delegate browsing, fetching, and synthesis to a Web Researcher worker and retain durable findings in memory.
- A repository maintainer investigating changes can use the Code Worker, Repo Researcher, Test Runner, or Bug Investigator templates for code-focused tasks.
- An engineering lead who wants a weekly repository-history review and README-drift alert can schedule the routine and inspect it in the dashboard.
- An operator with trusted agent instances can use the private bearer-token A2A HTTP+JSON interface to exchange text and explicitly allowed structured JSON or file data.
How do you install or deploy this agent?
For a server installation, run:
uv sync
uv run octopal configure
uv run octopal startWithout uv:
python -m venv .venv
source .venv/bin/activatepip install -e .
octopal configure
octopal startDuring configure, choose a model provider and supply the applicable llm.provider_id, llm.model, llm.api_key, and llm.api_base. The default Docker worker mode requires a working Docker CLI, daemon, and worker image; build one when needed with uv run octopal build-worker-image --tag octopal-worker:latest. Desktop builds are listed for Windows, macOS on Apple Silicon and Intel, and Linux.
How do you use this agent?
After starting, open http://127.0.0.1:8000/dashboard. If dashboard protection is enabled, authenticate with gateway.dashboard_token from config.json. Check service health with uv run octopal status and follow output with uv run octopal logs --follow. For Telegram, configure telegram.bot_token and telegram.allowed_chat_ids; for WhatsApp, configure whatsapp.allowed_numbers, then run uv run octopal whatsapp install-bridge and uv run octopal whatsapp link. Install supplied worker templates with uv run octopal sync-worker-templates --overwrite and use uv run octopal dashboard --watch for the live dashboard.
What are this agent's strengths and limitations?
- The long-lived coordinator is separated from disposable workers, with Docker and per-worker scratch workspaces as the default boundary for risky inputs and side effects.
- Docker mode fails closed when the CLI, daemon, or worker image is unavailable; it does not silently fall back to host execution.
- It combines channels, a dashboard, schedules, MCP, skills, connectors, A2A, and named worker templates in one persistent runtime.
- Octo and its workers can use different model providers, including OpenAI, Anthropic, Gemini, Mistral, Ollama, and custom OpenAI-compatible routes.
- Its default isolation model depends on Docker; Docker-mode work will not run if the CLI, daemon, or image is unavailable.
- Local semantic retrieval downloads and verifies a pinned multilingual-e5-small ONNX bundle on first runtime start, adding a network and local-runtime dependency.
- Channel setup is not zero-config: Telegram requires a bot token and allowed chat IDs, while WhatsApp requires a bridge installation and linking.
- The automatic browser path depends on PinchTab, Docker, and a health check before it can fall back to Playwright; PinchTab is not intended for exposure to the public internet.
How does this agent compare with similar options?
Octopal explicitly places itself alongside OpenClaw, Hermes Agent, NanoClaw, OpenHands, and other autonomous runtimes. Compared with OpenClaw-style assistants, it makes Docker workers and scoped execution the default model; compared with Hermes-style systems, it emphasizes separating the reasoning loop from the side-effect loop; compared with NanoClaw, it chooses a broader integrated runtime over a smallest-possible codebase. Its stated target is a persistent personal/operator runtime rather than an IDE-adjacent coding sandbox alone.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Octopal This agent | 61 · Some gaps | Desktop appFree + model costs | ★ 10 | 2mo ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| OpenFang | 56 · Major gaps | CLIFree + model costs | ★ 18k | 5mo ago | Rust | OpenAI API · Claude API |
| Atomic Agent | 56 · Major gaps | CLIFree + model costs | ★ 3.4k | 1d ago | TypeScript | — |
| Brigade — Enterprise-grade personal intelligence | 59 · Major gaps | CLIFree + model costs | ★ 11k | 3d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes coordinator/worker split, Docker default isolation, workers have scratch workspace, access to main workspace requires explicit allowed_paths, Docker mode fails closed, no automatic isolation downgrade. These support least_privilege score 2. User confirmation: --yes flag for promote etc., but not all dangerous actions require confirmation, so score 1. Data flow transparency: README describes data flow (user->channels->Octo->workers->external systems), but not detailed data handling, score 2. Sensitive data handling: memory layers and local ONNX embeddings mentioned, but no encryption or redaction details, score 2. Dependency security: dependencies listed, npm audit in CI, but no Python vulnerability scan evidence, score 2. External effects: external system interactions described, but not all side effects, score 2. Rollback: adaptation tests show rollback support, but no system-level rollback, score 2. Source attribution: license and author present, but publisher unverified, score 1.
Self-consistency: README and tests consistent, architecture matches A2A and adaptation features, score 2. Dependency availability: dependency list complete, but no lock files or version pinning evidence, score 2. Failure messages: tests check error responses like 401, 403, 400, but user-facing failure message quality not assessed, score 2.
Audience and scenarios: README describes multiple use cases (personal operator, research, coding, etc.), score 2. Capability boundaries: worker templates and tools described, but not all boundaries, score 2. Trigger precision: scheduled tasks and channels described, but trigger mechanism not detailed, score 2. Environment fit: supports multiple platforms and model providers, score 2.
Information architecture: README well-structured with TOC and doc links, score 2. Install notes: multiple installation methods provided, score 2. Naming stability: version format clear, score 2. Examples and FAQ: examples and troubleshooting provided, score 2. Known limitations: not explicitly listed, score 1. License: MIT, score 2. Versioning and changelog: version number present, but no changelog, score 2. Maintenance responsibility: author info present, but maintenance responsibility not explicit, score 1.
Output usability: output formats described (e.g., structured results), but no actual output examples, score 2. Marginal value: comparison with similar projects emphasizes security boundary, score 2. Cost-benefit: no performance or cost data, score 2.
Claim traceability: README claims have doc links, score 2. Cross-source corroboration: tests support some claims, but not independently verified, score 1. Fact-inference separation: README distinguishes architecture description and design intent, score 2.
- Publisher identity unverified; exercise caution.
- Dependency security relies only on npm audit; Python dependencies not scanned.
- User confirmation mechanism not comprehensive; dangerous actions may not all require confirmation.
- Known limitations not explicitly listed.
- Changelog missing.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/octopal)<a href="https://followagents.com/en/agents/octopal"><img src="https://followagents.com/badge/octopal.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2026.08.16 Octopal 2026.08.16
Release notes excerpt
What's Changed * harden worker dependency isolation by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/221 * persist provider threads per conversation by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/222 * scope worker image rebuild inputs by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/223 * preserve container worker import path by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/224 * harden persistent provider sessions by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/225 …View on GitHub ↗ -
v2026.07.25.1 Octopal 2026.07.25.1
Release notes excerpt
What's Changed * Improve prompt guidance by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/198 * Harden worker result contract by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/199 * Harden worker isolation fallback by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/200 * Preserve configuration migration precedence by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/201 * Make pending-turn delivery reliable by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/202 …View on GitHub ↗ -
v2026.07.04 Octopal 2026.07.04
Release notes excerpt
What's Changed * Handle uppercase worker follow-ups by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/193 * Update AGENTS workflow docs by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/194 * suppress stale turn replies by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/195 * Harden worker thinking step budgets by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/196 * Handle image tool fallback errors by @pmbstyle in https://github.com/pmbstyle/Octopal/pull/197 Full Changelog: https://github.com/pmbstyle/Octopal/compare/v2026.07.02...v2026.07.04View on GitHub ↗