Octopal
Octopal is a local autonomous AI agent that runs on your computer or server and communicates via Telegram, WhatsApp, or a desktop app. It solves the problem of trusting an AI agent with real work by using a coordinator/worker architecture where workers run in isolated Docker containers, preventing context poisoning and hostile actions. It is for developers and power users who want a safe, always-reachable personal AI operator.
✨ Key features
- Coordinator/worker split with Docker isolation for safe execution
- Communicate via Telegram, WhatsApp, or desktop app
- Supports multiple model providers including OpenAI, Anthropic, Google Gemini, and local Ollama
- Built-in worker templates for research, coding, DevOps, and more
- Memory layers for durable notes, user preferences, and identity
- Agent-to-agent collaboration via A2A protocol
🎯 Use cases
- Personal operator for daily tasks via chat
- Automated research with web browsing and synthesis
- Scheduled recurring routines like weekly repo summaries
- Coding and repository management with isolated workers
- Private agent network with other Octopal instances
📦 Installation
🧰 Requirements: Requires Python, uv (or pip), and Docker for worker isolation. No API keys required for local models, but cloud providers need their own keys.
Desktop App
Download from releases page.
Server Install
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/pmbstyle/Octopal/main/scripts/octopal.sh | bash
Windows PowerShell:
irm https://raw.githubusercontent.com/pmbstyle/Octopal/main/scripts/octopal.ps1 | iex
Then configure and start:
uv run octopal configure
uv run octopal start
Manual Install
git clone https://github.com/pmbstyle/Octopal.git
cd Octopal
uv sync
uv run octopal configure
uv run octopal start
Without uv:
python -m venv .venv.venv\Scripts\activatesource .venv/bin/activate
pip install -e .
octopal configure
octopal start🚀 Usage
After installation, configure and start:
uv run octopal configure
uv run octopal start
Open the dashboard:
http://127.0.0.1:8000/dashboard
If dashboard protection is enabled, use the gateway.dashboard_token from config.json.
⚠️ Good to know
Docker is required for worker isolation and fails closed if unavailable; the project is under active development with a truncated README.
❓ FAQ
How does Octopal ensure safety?
Octopal uses a coordinator/worker split where workers run in isolated Docker containers, preventing context poisoning and limiting damage from malicious code.
What model providers are supported?
It supports OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, Together AI, Groq, Codex, Z.ai, Minimax, Ollama, and custom OpenAI-compatible endpoints.
Can I run Octopal without Docker?
Yes, you can select same_env launcher explicitly for trusted local tasks, but Octopal never downgrades isolation automatically.
How do I set up WhatsApp?
Use commands: uv run octopal whatsapp install-bridge, uv run octopal whatsapp link, and uv run octopal whatsapp status.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.