Octopal is a local autonomous AI agent platform whose core agent is named Octo, and it can reside on your computer or server. You can communicate with Octo via Telegram, WhatsApp, or a dedicated desktop application. Octopal's design goal is to execute any task, run scheduled activities, host automated pipelines, conduct web research, and work with APIs, MCP, A2A, skills, and more. Its core philosophy is to build an AI agent you can trust.
[Architecture and Security Model] Octo acts as the main reasoning agent, running inside the system for the long term, responsible for conversation, memory, strategy, routing, and high-level decisions. Communication with the outside world is delegated to specialized workers (sub-agents). Workers are short-lived, one-off agents generated solely to accomplish a specific task objective, running in isolated Docker environments, holding no system or private context, and the instance is deleted once the task is complete. This coordinator/worker separation architecture can prevent context contamination, prompt injection, and malicious environment manipulation. Even if a worker installs and runs malicious code, it will only remain within its container and will not harm the main system. Docker is the default worker launcher, workers have independent temporary workspaces, and access to Octo's main workspace requires explicit authorization via allowed_paths. Docker mode fails closed when the CLI or daemon is unavailable, or when the worker image cannot be built. To run trusted local development tasks without Docker, same_env must be explicitly selected; Octopal will not automatically downgrade isolation. The dashboard and gateway API can be protected by tokens, and Tailscale integration can privately expose the dashboard without opening public ports.
[Model Providers] Octopal allows selecting one model provider for Octo, and a different provider for workers when needed. The supported provider catalog includes: frontier APIs (OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, Together AI, Groq), subscription and plan-based routes (Codex, Z.ai, Minimax), local and custom routes (Ollama, custom OpenAI-compatible).
[Agent-to-Agent Collaboration (A2A)] Octo can communicate with other Octopal instances or other agents via A2A, turning standaloneAI agents form work teams. Multiple Octopal instances can collaborate as a private agent network; other agents and coding runtimes (such as Codex, Claude Code, Gemini, etc.) can connect as trusted peers; an agent can request Octopal to use its memory, workers, tools, or local context. The current A2A integration is private by default, peers must be explicitly configured, authentication uses bearer tokens, Octopal is discovered through an agent card, and text and explicitly permitted structured JSON, file URLs, and raw file parts are exchanged over the A2A HTTP+JSON interface.
[Memory System] Octopal stores memory in layers: MEMORY.md holds working memory and persistent notes; memory/canon/ stores reviewed long-term knowledge; USER.md stores user preferences and interaction style; SOUL.md stores the assistant's identity, tone, and behavioral principles; HEARTBEAT.md stores periodic responsibilities, monitoring loops, and background obligations. Semantic retrieval uses a mandatory local, CPU-only ONNX runtime and does not depend on PyTorch. On Linux, Windows, and macOS, the first run startup downloads and verifies a pinned intfloat/multilingual-e5-small package.
[Channels and Dashboard] Octopal can communicate via Telegram, WhatsApp, or a dedicated desktop app. Channels support text, image/file attachments, supported reactions, and a brief grace window so that subsequent messages are merged into the same turn before Octo begins execution. The dashboard provides a real-time operations interface, including Octo status and gateway health, active workers and work history, communication logs, dashboard actions, token-based access protection, and optional Tailscale-aware private access.
[Skills and Connectors] Octopal supports workspace-local skill packages located at workspace/skills/<skill-id>/. Skills can include SKILL.md instructions, readiness checks, isolated Python or JS/TS runtime environments, and can be easily installed through the desktop app. Connectors are the integration layer for external services; the current connector surface includes Google services and GitHub-oriented workflows.
[Multilingual and Themes] The Octopal desktop UI supportsEnglish, French, Spanish, and Chinese (Mandarin), and supports light and dark themes.
[Core Commands and Troubleshooting] The project provides commands for WhatsApp setup, worker templates, memory maintenance, manual dashboard builds, and more. GitHub releases use date-based versions located in src/octopal/_version.py, with tags in the form vYYYY.MM.DD or vYYYY.MM.DD.N. Troubleshooting covers the Telegram bot starting but not replying, WhatsApp messages not arriving, model provider configuration, web search or scraping issues, and more. The browser tool defaults to auto, starts a pinned PinchTab container on an idle loopback port at startup, creates a private server token under data/managed-web, and automatically derives separate host and Docker worker URLs. If Docker, PinchTab, or their health checks are unavailable, Octopal continues running on Playwright.
[License] MIT, see LICENSE for details.
