octo-agent

A single-binary, self-hosted AI agent that keeps your models and data on your own machine, with eight interfaces behind one Go binary.

Stars
★ 141
Last updated
1d ago
License
MIT
Primary language
Go

At a glance

How it runs
CLISelf-hosted serviceDesktop app
Works with
Universal · cross-platformOpenAI API · Claude APIClaude Code (Partial support)
Cost
Free software; you pay for model usage
Setup effort
Low · running in minutes
You'll need
Go >= 1.25 (only for source/`go install` builds)Shell / CLINetwork accessLocal filesystemMCP Server
Typical use
Developers who want a coding agent on their own laptop or server without handing the codebase to a vendor cloud.
Not a fit if
  • Users happy with a Codex or Claude subscription who don't want to supply model API keys
  • Teams that need an App Store mobile build rather than a developer preview
  • Organizations requiring code-signed installers for compliance

What does this agent do, and when should you use it?

octo-agent is an MIT-licensed AI agent shipped as a single ~40 MB Go binary with no Node, Python or Ruby dependency tree. It comes with built-in shell, file read/write/edit and search tools, plus MCP servers, SKILL.md skills and sub-agents enabled by default. Running octo serve -d starts a local server on 127.0.0.1:8088 that backs both the Web UI and the IM bridge, while the same binary also exposes a TUI, a headless one-shot CLI, a desktop app, VS Code and Obsidian extensions, and a mobile developer preview. On the model side it speaks the Anthropic and OpenAI protocols natively, so DeepSeek, Kimi, Qwen, Anthropic, OpenAI or any compatible endpoint all work, with prompt caching tuned per provider (the project reports 99%+ hit rates). It advertises zero telemetry; the only unsolicited network call is a version check against GitHub, which update_check: false disables entirely.

At its core is a tool-looping agent: it takes a prompt, loads session history and persisted state, then calls built-in tools (a terminal, file read/write/edit, search), MCP servers (stdio and HTTP transports with OAuth and Tool Search), skills and sub-agents, and finally produces code changes, file operations or an answer. octo "..." runs one headless agentic turn and exits, suitable for cron or CI; bare octo opens the interactive TUI and octo -c resumes a session. octo serve -d starts the local server, the Web UI runs on the same agent core, and the IM bridge connects the conversation to WeChat iLink, Feishu, DingTalk, WeCom, Discord and Telegram. Safety is concrete: catastrophic commands such as rm -rf / and rm -rf ~ are hard-coded denies that custom permission rules cannot override, kill / pkill / killall aimed at octo's own process are refused, restart_server always asks permission first, and deletes plus write_file / edit_file overwrites are backed up to a recycle bin (default 14 days / 10 GiB). Browser automation is Go-native CDP with record, replay and self-heal.

  1. Developers who want a coding agent on their own laptop or server without handing the codebase to a vendor cloud.
  2. Teams already pointing at DeepSeek, Kimi, Qwen or another OpenAI-compatible endpoint who need prompt caching that doesn't collapse and a predictable token bill.
  3. Engineers who want headless one-shot runs in CI or cron, e.g. octo "explain this repo".
  4. Individuals or small teams who want to dispatch tasks straight from WeChat, Feishu or Telegram.
  5. Claude Code users with an existing ~/.claude/skills tree who want to symlink and reuse it.
  6. Knowledge workers who want the same assistant inside VS Code, Obsidian or on their phone.

How do you install or deploy this agent?

One script on Linux and macOS; PowerShell on Windows; a download mirror when github.com is unreachable.

curl -fsSL https://octo-agent.dev/install.sh | sh
irm https://octo-agent.dev/install.ps1 | iex
# restricted networks: mirror install; `octo upgrade` falls back automatically too
curl -fsSL https://dl.octo-agent.dev/install.sh | sh

Desktop installers come from the latest release: octo-setup.pkg (macOS), octo-setup.exe (Windows), Octo-x86_64.AppImage (Linux). With Go >= 1.25 already installed:

go install github.com/open-octo/octo-agent/cmd/octo@latest

Android users can grab octo-android.apk from each release; iOS must be built from source under mobile/. Installers are not code-signed yet, so expect Gatekeeper and SmartScreen warnings; see SECURITY.md for the signing policy and release hash verification.

How do you use this agent?

Start the local server, then open http://127.0.0.1:8088 and follow the setup panel: pick a language, connect a model, then a short onboarding chat that learns your name, the assistant's personality and how you want it to behave. Loopback needs no access key.

octo serve -d              # local server (Web UI + IM bridge)

Prefer the terminal? Once a provider is connected, everything runs from the same command:

octo "explain this repo"   # headless one-shot: prompt -> tool loop -> exit
octo                       # interactive TUI
octo -c                    # resume a session
octo config                # provider setup without the browser
octo upgrade               # upgrade

For mobile, scan the QR code in Settings -> Mobile; the app connects directly to your own octo serve over LAN, Tailscale or any tunnel. The CLI reference, config-file and permissions docs live at octo-agent.dev/docs.

What are this agent's strengths and limitations?

Pros
  • One ~40 MB Go binary with no Node/Python/Ruby dependency tree, sidestepping npm mirrors and node-gyp build failures.
  • Native Anthropic and OpenAI protocol support plus compatible endpoints, with prompt caching tuned per provider — no vendor lock-in.
  • Eight interfaces share one agent core and one config: TUI, CLI, Web, desktop, IM bridge, VS Code, Obsidian and mobile.
  • Safety defaults are checkable rather than vague: hard-coded catastrophic denies that rules cannot override, self-process protection, permission-gated restarts, recycle-bin backups.
  • Zero telemetry and a Web UI that bundles every asset (no CDN); the only self-initiated request is a version check that one config switch silences.
  • Skill format is Claude Code-compatible, so an existing ~/.claude/skills tree can be symlinked and reused.
Limitations
  • The software is free but you must supply paid model API keys; there is no built-in free tier or hosted option.
  • Installers are not code-signed yet, so Gatekeeper and SmartScreen will warn and enterprise distribution needs extra work.
  • Mobile is a developer preview; iOS has to be built from source and app-store builds are not out yet.
  • When github.com is blocked you must explicitly switch to the dl.octo-agent.dev mirror or install and upgrade fail.
  • The desktop installer is around 100 MB; supporting eight interfaces means a heavier delivery surface than a pure CLI agent.
  • Cache hit-rate and stability numbers come from the project's own README rather than independent benchmarks.

How does this agent compare with similar options?

The README names its reference points directly. Against OpenClaw and Hermes, octo positions itself as download-and-use rather than something you must "raise" through environment tuning, rule writing and skill configuration. Against Codex and WorkBuddy it concedes they remain the best agent harnesses on the planet, but notes their desktop installers often approach 1 GB versus roughly 100 MB here. The project also credits Claude Code as the source of its agent loop, tool set and SKILL.md format, and OpenClacky for much of its UI and interaction design. Notably, the README tells readers with reliable Codex or Claude subscriptions to keep using them.

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
octo-agent This agent 51 · Major gaps CLIFree + model costs ★ 141 1d ago Go OpenAI API · Claude API
bbarit-oss 42 · Major gaps CLIFree + model costs ★ 150 3mo ago Rust ChatGPT · Codex · Claude Code · OpenAI API · Claude API
Aster 77 · Good CLIFree + model costs ★ 137 5d ago Rust OpenAI API
iPolloWork 44 · Major gaps Desktop appFree + model costs ★ 7.4k today TypeScript —

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
51/ 100 5-point scale 2.6 / 5
Trust 14/29
Reliability 6/14
Adaptability 10/18
Convention 10/18
Effectiveness 7/13
Verifiability 4/8
Why each dimension lost points
Trust14 / 29 · 2.4/5

SECURITY.md gives an unusually explicit single-user threat model: loopback exemption, 256-bit access key with constant-time compare, Origin/Host checks, SameSite=Strict cookie. However the default posture enables shell, file, MCP and sub-agents out of the box, with least privilege resting on an optional sandbox and a hard-coded deny list, so least_privilege is only 1. restart_server requires explicit confirmation, catastrophic commands are hard-coded denies, and deletes/overwrites go to a recycle bin first, supporting user_confirmation=2 and rollback=2. Data-flow transparency claims zero telemetry with a single opt-out version check, but this is README self-assertion without code corroboration, hence 2. Sensitive data handling is deducted: SECURITY.md itself states agent-written HTML shares the app origin and can read the access key, and public Light Apps plus /_artifacts/ token URLs are reachable without the key, a real risk, hence 1. Dependency security shows only a go.mod version list with no vulnerability scanning or SBOM evidence, hence 1. External effects include curl|sh install, self-upgrade (SHA-256 verified but unsigned) and outbound IM channels, hence 1. Source attribution is explicit in the Prior Art section crediting Claude Code and OpenClacky, hence 2.

Reliability6 / 14 · 2.1/5

The layered architecture, eight-interface description and CI workflows (go vet/gofmt/build/test -race plus a separate desktop build) are mutually consistent, self_consistency=2. Dependency availability has pinned versions and a go mod tidy check in CI, but no go.sum or vendor evidence is supplied, so supply-chain reproducibility cannot be statically confirmed, hence 1. Failure messages are only visible as CI comments and SECURITY.md troubleshooting notes; runtime error messaging has no evidence, hence 1.

Adaptability10 / 18 · 2.8/5

Audience and scenarios are well covered: coding agent plus personal assistant, eight entry points, multi-provider protocols, hence 2. Capability boundaries are clearly stated in SECURITY.md's 'not defended' list (hostile local processes, plaintext transport, same-origin pages), hence 2. Trigger precision is thin: CLI one-shot, TUI, IM channels and cron coexist, but there is no precise rule set for when tools or sub-agents fire, hence 1. Environment fit covers Linux/macOS/Windows, mirror fallback, Go install and multi-arch desktop CI, hence 2.

Convention10 / 18 · 2.8/5

README is well structured with layered navigation to external docs, information_architecture=2. Install notes cover multiple platforms, mirrors, desktop installers and Go install, install_notes=2. Naming stability is deducted for inconsistent octo/octo-agent/Octo usage and a version claim of '1.0 stable' without a versioning policy, hence 1. Examples and FAQ are limited to a few command snippets with no FAQ, hence 1. Known limitations are disclosed well (unsigned installers, mobile preview, Linux AppImage not run-tested), hence 2. LICENSE.txt is the full MIT text, license=3. Versioning/changelog is absent beyond the 1.0 mention, hence 1. Maintenance responsibility is thin: the publisher is unverified and only a personal email and GitHub advisory channel are given, hence 1.

Effectiveness7 / 13 · 2.7/5

Output usability is adequate for ordinary use via TUI/CLI/Web/IM and single-binary distribution, hence 2. Marginal value comes from single binary, multi-model support, zero telemetry and the recycle-bin safety net, which differentiates it, but 'on par with Claude Code' claims lack benchmark evidence, hence 2. Cost benefit rests on self-reported 99%+ cache hit rates and ~40MB size with no measurements, and the desktop app adds GTK4/WebKitGTK deployment cost, hence 1.

Verifiability4 / 8 · 2.5/5

claim_traceability is 1: performance, cache hit rates and size comparisons have no in-repo data or benchmarks. cross_source_corroboration is 1: README and SECURITY.md corroborate the security boundary, but CI and code files provide no cross-evidence for functional claims. fact_inference_separation is 2: SECURITY.md explicitly separates defended from undefended areas and README labels mobile as developer preview, keeping fact and inference reasonably distinct.

Risks and how to mitigate them
  • SECURITY.md itself states agent-written HTML shares the app origin and can read the access key and call the API as the user; public Light Apps and /_artifacts/ token URLs are reachable without the key, so treat prompt injection seriously when deploying.
  • Shell, file writes, MCP and sub-agents are enabled by default; least privilege depends on the optional sandbox, so enable Seatbelt/Landlock and tighten permission rules.
  • Install is curl|sh, installers are not code-signed, and upgrades verify only SHA-256 with no signature layer; verify hashes yourself.
  • Key claims such as cache hit rates, size comparisons and parity with Claude Code are self-asserted with no in-repo benchmarks or measurements.
  • The publisher is unverified by FollowAgents; maintenance responsibility and update path rest on personal channels, so long-term maintenance is unclear.
Evidence confidence: Low Reviewed Nov 05, 2026 Reviewed revision cfb92f7646ea
See the full review method →

FAQ

Does it cost anything?
The code is MIT-licensed and free to use and self-host. Model inference is not free: you connect your own endpoint (DeepSeek, Kimi, Qwen, Anthropic, OpenAI or any compatible one) and pay that provider per use. The project sells no hosted service.
Does my data leave the machine?
The project reports zero telemetry — no IP, device model, model choice or usage behavior collected. The only request it makes unasked is a version check against GitHub carrying no data, and update_check: false turns even that off. After that, what leaves the machine is the model API calls you configured and the tool calls you triggered.
Can the agent delete my files or kill its own process?
Several layers are documented. rm -rf / and rm -rf ~ are hard-coded denies that custom rules cannot override; ordinary deletes and write_file / edit_file overwrites are backed up to a recycle bin (default 14 days / 10 GiB); the terminal tool refuses kill / pkill / killall aimed at octo's own process, including indirect forms like kill $(pgrep octo); restart_server requires approval and restarts gracefully. OS-enforced sandboxing (macOS Seatbelt, Linux Landlock) can be enabled on top.
Will using a third-party model wreck prompt caching and blow up my bill?
That is one of the project's stated differentiators: caching is tuned per provider, and the README reports 99%+ measured hit rates on Kimi, DeepSeek and Qwen. Real results depend on your endpoint and call patterns, so watch the bill on a small task first.
Can I use it on my phone?
Yes, as a developer preview. Every release ships an Android APK; after installing, scan the QR in Settings -> Mobile to connect straight to your own octo serve over LAN, Tailscale or any tunnel. iOS still requires building from source under mobile/, and app-store builds are planned but not shipped.
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related agents