Octomind manual
Documentation
Install Octomind, configure your agents, and put them to work.
Start in three commands
curl -fsSL https://octomind.run/install.sh | bash
octomind login
octomindGetting Started
- Installation Install Octomind for terminal use, sign in to the default OctoHub gateway, and set up shell completions.
- Quickstart Start an interactive Octomind session through OctoHub, then learn the commands you need day-to-day.
- Configuration Configure Octomind's models, tools, and runtime limits. This guide covers file locations, merge order, and overrides for
- AI Providers Choose and authenticate models using provider:model. This guide is for users configuring OctoHub, direct providers,
- Sessions Start, resume, and inspect Octomind conversations from the terminal. This guide also covers piped runs, background
- Roles and Permissions Configure roles to select system prompts, model settings, and tool grants. This guide is for users creating local roles
- MCP Tools Reference Use this reference to inspect and configure the tools available to your Octomind session. It covers built-in controls,
- Context Compression Use this guide to configure and inspect context compression in long-running sessions. It explains automatic folds,
- Workflows Use workflows to run repeatable multi-step tasks from local TOML files or installed taps. This guide covers sequential,
- Commands and Layers Use this guide to add reusable commands, ACP sub-agents, and prompt templates to your sessions. It also explains the
- Structured Output Use this guide to consume Octomind activity as JSONL and request schema-shaped model answers. It is for scripts and
- Editor Integration Use this guide to connect an ACP-capable editor or client to Octomind. It covers the launch command, session setup, MCP
- Cross-Session Learning Use cross-session learning to carry your rules and grounded project knowledge into later sessions. This guide covers
- Supervisor The supervisor checks progress and completion, manages plans, and narrows large tool results around your session. Use
- Skills Use skills to load reusable instructions and supporting resources into a session. This guide covers using skills,
- Token Efficiency Use this guide to keep tool schemas focused with on-demand capabilities and to inspect the context your session sends.
- Local Tools Use local tools to expose project scripts as MCP actions without adding server configuration. This guide covers the
- Guardrails Use .agents/guardrails.toml to transform session input, deny matching tool calls, and run feedback scripts. This guide
Integration
- WebSocket Server Use Octomind's WebSocket server to create remote AI sessions from web clients, bots, and automation tools. This guide
- ACP Protocol ACP lets Octomind run as a JSON-RPC sub-agent over stdio for editor integration and agent-to-agent delegation.
- Daemon Mode and Webhook Hooks Run Octomind as a persistent session that reacts to external events. This guide is for automation authors using
- Tap System Use taps to install and author reusable Octomind agents, skills, capabilities, workflows, and plugins. This guide covers
Reference
- CLI Reference Use this reference to launch sessions, configure Octomind, and automate workflows from your shell. It covers every CLI
- Session Commands Reference Use this reference while operating a CLI session or implementing an ACP/WebSocket client. It lists every registered
- Configuration Reference Use this reference when editing Octomind’s TOML configuration or diagnosing a load error. It covers the complete shipped
- Environment Variables Use this reference when configuring credentials, relocating state, or diagnosing startup and script behavior. It
Use Cases
- Automated Code Review in CI/CD Use this guide to add Octomind reviews to a CI pipeline. It covers stdin prompts, structured review results, and a shell
- Event-Driven Webhooks Use this guide to connect external HTTP events to a persistent Octomind session. It covers webhook scripts, daemon
- Custom Development Workflow Use this guide to build a development pipeline that refines a request, researches the checkout, and implements a fix. It
- Web Dashboard Integration Use this guide to connect a browser dashboard to Octomind's WebSocket server. It covers session setup, request
- Multi-Agent Task Delegation Use this guide to delegate development tasks to local, tap-provided, or runtime-created specialists. It covers working
- Dynamic MCP Servers Use the built-in mcp tool to connect and manage tool servers during a live session. This guide is for users who need
- Scheduled Tasks Use the built-in schedule tool or /schedule command for reminders, periodic checks, and follow-up work in a running
- Long-Running Development Use named sessions and resume to continue development across multiple sittings. This guide covers saving work,
- Custom Hooks Use script-backed HTTP listeners to turn external events into messages for a running Octomind session. This guide is for
- Block destructive commands and check the agent's work Set up sandbox boundaries, command guardrails, and verification so an autonomous agent cannot damage files or skip checks.
- Put spending checkpoints around each task Set request and session spending checkpoints so every agent task has a visible, predictable cost.
- Check the result before accepting “done” Set up completion review and executable checks so done means the requested change actually works.
- Apply project conventions without repeating them each session Package project conventions as standing instructions, reusable skills, and executable checks that apply in every relevant session.
- Carry project corrections into the next session Store project corrections as durable memories that automatically guide related work in future sessions.
- Let the agent run your project checks correctly Expose project scripts as typed tools so agents run the right builds, tests, and release commands.
- Give your team a reusable release-review specialist Package a release-review specialist your whole team can install and use consistently across projects.
- Build a source-backed map of an unfamiliar codebase Build a source-backed map of an unfamiliar codebase, from entry points and state ownership to tests and one execution path.
- Keep private code in local model sessions Configure local model sessions that keep private code on your machine and make any cloud switch explicit.
- Get a second opinion before accepting a risky change Run independent model reviews in parallel and combine them into a comparison that keeps disagreements visible.
- Split a broad research question into focused investigations Build a research workflow that plans focused investigations, runs them in parallel, and synthesizes an evidence-backed report.
- Keep fixing a change until it passes review Build a finite implementation, independent review, and correction loop that keeps working until the change passes.
- Turn Git history into reviewable release notes Create a repeatable command that turns Git history into reviewable release notes with commit references and structured output.
Development
- Building from Source Build Octomind from source and prepare the local checks used when contributing Rust changes. This guide is for
- Architecture Use this contributor guide to trace a request from CLI configuration through sessions, MCP tools, and supervision. It
- MCP Server Development Add a built-in MCP server when you are extending Octomind itself. This contributor guide covers tool definitions,
- Learning Benchmark Use these live contract benchmarks when changing learning retrieval or consolidation. They compare ranking and merge
Troubleshooting