octo-agent
An open-source, single-binary, self-hosted AI agent.
A coding agent on par with Claude Code; as a personal assistant, lighter than OpenClaw — one MIT-licensed Go binary, no Node / Python / Ruby, running on any model (DeepSeek, Kimi, Anthropic, OpenAI, or anything compatible), with the server and your data staying on your own machine.
Website · 简体中文 · Install Guide · Documentation · Community
If you find octo useful, give it a ⭐ on GitHub!
Why octo
octo isn't another agent framework you have to "raise." Projects like OpenClaw or Hermes often need environment tuning, rule writing, and skill configuration before the agent runs smoothly. octo sits closer to Codex or WorkBuddy: download and use, user-friendly, while keeping model choice, data ownership, and the runtime firmly in your hands.
curl -fsSL https://octo-agent.dev/install.sh | sh # single binary — no Node / Ruby / Python
octo "Add a --json flag to 'octo config show' and run the tests" # one prompt → full agentic loop
📱 On your phone: download the Android app (built with every release), then scan the QR in Settings → Mobile to connect — setup guide.
octo is built around that positioning:
- Works out of the box: shell, file read/write/edit, search, MCP servers, skills, and sub-agents are all on by default — one message after install is enough for it to actually do work.
- Model choice stays yours: any OpenAI / Anthropic protocol-compatible endpoint is supported natively; no vendor lock-in.
- Data stays on your machine: self-hosted, zero telemetry — no analytics, no crash reporting, no usage pings, no CDN. Exactly one request is made without you asking: a version check against GitHub, carrying no data. Set
update_check: false and octo makes none at all — what leaves the machine is then only the model API calls you configured and the tool calls you asked for.
- Everywhere you are: the same binary serves eight entry points — TUI, CLI, web, desktop, IM, editor extensions, and mobile.
- Safe defaults: catastrophic commands are hard-coded denies, and deletes and overwrites are backed up to a recycle bin first — the agent won't edit itself dead and won't go rogue on your data.
If you already have reliable access to a Codex or Claude subscription, keep using it — they remain the best agent harnesses on the planet. Otherwise, octo is worth a serious look.
Highlights
- A single ~40 MB Go binary: one command to download, copy to any server, and run. No Node / Python / Ruby dependency tree; no npm mirror, node-gyp build failure, or version conflict headaches.
- No cache degradation: prompt caching is tuned per provider; measured hit rates for Kimi, DeepSeek, and Qwen are all 99%+, keeping your token bill predictable.
- Eight interfaces: TUI, CLI, Web UI, desktop app, IM bridge, VS Code, Obsidian, and mobile — few other agent projects cover this many entry points at once.
- Zero telemetry: no IP, device model, model choice, or usage behavior is collected — no telemetry hooks at all. The Web UI ships every asset it needs — icons are bundled, text uses system fonts — so opening it touches no CDN. The only thing octo asks the network about itself is whether a newer release exists, and that is one config switch away from silent.
- Desktop installer around 100 MB: compare that to Codex desktop and WorkBuddy, which often weigh in around 1 GB. A thin agent harness shouldn't need that much space.
- Stable and safe: self-protection, graceful restarts, and a recycle-bin safety net (see Core Features).
Any one of these points might be covered by some other product. But only octo combines out-of-the-box usability, native multi-model support, eight interfaces, a single binary, zero telemetry, a small footprint, high stability, and strong safety.
One Binary, Eight Interfaces
octo (single binary)
-> TUI interactive terminal session
-> CLI octo "prompt" or piped stdin: one headless agentic turn, then exit — script it from cron, CI, or your own programs
-> Web UI octo serve local dashboard
-> Desktop app native window + system tray on macOS / Windows / Linux
-> IM bridge WeChat iLink, Feishu, DingTalk, WeCom, Discord, Telegram
-> VS Code extension open-octo/octo-vscode
-> Obsidian plugin open-octo/octo-obsidian
-> Mobile iOS + Android developer preview
Stable (1.0) already covers TUI, CLI, Web UI, Desktop, IM bridge, and the VS Code / Obsidian extensions. The eighth — a mobile app (iOS + Android) — is implemented and in developer preview: connecting straight to your own octo serve over your LAN, Tailscale or any tunnel. Android: download the APK from each release; iOS builds from source (see mobile/). App-store builds are next.
Core Features
Works out of the box — no "raising" required
Built-in tools (shell, file read/write/edit, search), MCP servers, skills, and sub-agents are on by default. No environment tuning, rule writing, or skill configuration first — one message after install is enough for it to actually do work.
Native model support, without cache degradation
DeepSeek, Kimi, Qwen, Anthropic, OpenAI, or any OpenAI / Anthropic-compatible endpoint — octo supports them natively. Prompt caching is tuned per provider, with hit rates of 99%+. Unlike setups that front Claude Code with a third-party model and see cache hit rates collapse from misconfiguration, octo keeps your token bill predictable.
Stable and safe — won't edit itself dead, won't go rogue
- The terminal tool refuses any
kill / pkill / killall aimed at octo's own process, including detours like kill $(pgrep octo).
- restart_server is hard-wired to ask permission first — a browser modal on the web, an explicit reply on IM. Even after approval, the restart is graceful: the current turn drains so your reply reaches you before the supervisor respawns the server and clients reconnect.
- Every delete is validated. Catastrophic commands like
rm -rf / and rm -rf ~ are hard-coded denies that custom permission rules cannot override. Ordinary file deletes and write_file / edit_file overwrites are first backed up to a recycle bin (default 14 days / 10 GiB), so nothing is ever truly gone.
- On top of that, opt into OS-enforced sandboxing (macOS Seatbelt / Linux Landlock) when you want it.
Skills: Claude Code-compatible
The SKILL.md format is compatible with Claude Code — symlink ~/.claude/skills and reuse what you have.
MCP servers
stdio + HTTP transports, OAuth, and Tool Search for large tool sets.
Memory, sub-agents, and workflows
Cross-session memory, parallel sub-agents, and multi-agent workflow orchestration.
Browser automation
Go-native CDP record / replay / self-heal.
IM channels
Hook octo up to your chat apps and put it to work from WeChat, Feishu, or Telegram.
Quick Start
Install
- Linux / macOS —
curl -fsSL https://octo-agent.dev/install.sh | sh
- Windows —
irm https://octo-agent.dev/install.ps1 | iex
- Restricted networks — if github.com is unreachable, use the download mirror (installs and
octo upgrade also fall back to it automatically):
curl -fsSL https://dl.octo-agent.dev/install.sh | sh (Windows: irm https://dl.octo-agent.dev/install.ps1 | iex)
- Desktop app — grab the installer from the latest release:
octo-setup.pkg (macOS), octo-setup.exe (Windows), Octo-x86_64.AppImage (Linux)
- Go —
go install github.com/open-octo/octo-agent/cmd/octo@latest
Upgrade any time with octo upgrade. Platform details — Gatekeeper / SmartScreen warnings, uninstall, building from source — are in the install guide. The installers aren't code-signed yet; the full policy and how to verify releases by hash are in SECURITY.md.
First run
octo serve -d # start the local server (Web UI + IM bridge)
Open http://127.0.0.1:8088 and the setup panel walks you through it: pick a language, connect a
model, then a short chat that learns your name, the assistant's personality, and how you want it to
behave. Loopback needs no access key. The desktop app is the same server with a native window — run
it instead and skip straight to the browser step.
Prefer the terminal? Same agent, no extra setup once a provider is connected:
octo "explain this repo" # headless one-shot: prompt → agentic tool loop → exit
octo # interactive TUI in a terminal; octo -c resumes a session
octo config # provider setup without touching the browser
Next steps: quickstart · choose a provider · CLI reference.
First Journey
- Install with one command:
curl -fsSL https://octo-agent.dev/install.sh | sh.
- Start the server —
octo serve -d — or launch the desktop app, which is the same server.
- Open
http://127.0.0.1:8088 and follow the setup: language, model, then the onboarding chat that
writes who the assistant is and who you are.
- Give it a real task from the composer — one that needs shell, files or the web, not just an answer.
- Run
octo "explain this repo" for a headless one-shot, or octo for the terminal TUI — same
agent, same config.
- Configure an IM channel and keep the conversation going from WeChat / Feishu / Telegram.
- Add skills, MCP servers, and sub-agents as you need them.
Architecture
┌────────────────────────────────┐
│ Eight interfaces │
│ TUI · CLI · Web UI · IM │
│ Desktop · VS Code · Obsidian │
│ Mobile │
└───────────────┬────────────────┘
│
┌───────────────▼────────────────┐
│ App bootstrap │
│ provider wiring · permission │
│ gate · sub-agent spawner │
└───────────────┬────────────────┘
│
┌───────────────▼────────────────┐
│ Agent core │
│ tool loop · history · session │
│ persistence │
└───────────────┬────────────────┘
│
┌───────────────▼────────────────┐
│ Provider adapters │
│ Anthropic / OpenAI protocols │
│ and compatible endpoints │
└───────────────┬────────────────┘
│
┌───────────────▼────────────────┐
│ Tools │
│ shell · files · search · MCP · │
│ skills · browser automation │
└────────────────────────────────┘
For the layered design, provider protocols, and how to extend it, see the architecture docs.
Further Reading
The full documentation lives at octo-agent.dev/docs:
Community
- Bugs / feature requests — GitHub Issues
- WeChat group (Chinese-speaking users) — scan the QR code below, add the personal account, and mention
octo to be invited into the group:
Development
make build # ./octo
make test # go test -race ./...
Project conventions live in CLAUDE.md and .octorules; the PR workflow in CONTRIBUTING.md.
Current Status
octo has shipped 1.0 stable — TUI, CLI, Web UI, desktop, IM bridge, and editor extensions are all safe to rely on; mobile is in developer preview. What you can build on is declared in COMPATIBILITY.md; the security boundary in SECURITY.md.
Prior Art & Acknowledgements
octo stands on the shoulders of two projects and doesn't pretend otherwise: Claude Code, whose agent loop, tool set, SKILL.md format, and harness behavior shaped octo's internal design; and OpenClacky, which inspired much of the UI and interaction design. Any bugs or bad decisions are octo's own.
Contributors
Thanks to everyone who has contributed to octo:
The full record lives in the contributors graph.
License
MIT. See LICENSE.txt.
