Octomind Documentation: Open-Source AI Coding Agent CLI

Octomind is an open-source AI coding agent and agent runtime for the terminal: one Rust binary, any model, MCP-native. Use these guides to install, configure, and operate Octomind's CLI agent runtime, or to contribute to its Rust code. Start with a terminal session, then follow the guides for automation, integrations, and development.

Start Here

Install the binary and sign in to an Octomind account to use the shipped OctoHub model default:

curl -fsSL https://octomind.run/install.sh | bash
octomind login
octomind

octomind login asks you to confirm a code in the browser and CLI, then stores the hub key in the user-scope config/.env and account credentials in config/auth.json. It does not change your model selection. New configs use assistant:concierge as the default tag and octohub:auto as the model name. See Installation and Quickstart for the complete setup.

Configure

Inspect and validate your configuration before adding roles or tools:

octomind config --show
octomind config --validate

The default config is under ~/.local/share/octomind/config/ on Linux/macOS and %LOCALAPPDATA%/octomind/config/ on Windows. OCTOMIND_DATA_DIR relocates Octomind state; for example:

OCTOMIND_DATA_DIR="$PWD/.octomind-data" octomind config --show

Use Configuration for file merging and overrides, or AI Providers to supply provider credentials yourself.

Operate

Create or resume a named interactive session:

octomind run --name project-review
# After exiting, continue the same session:
octomind run --resume project-review

Inside a session, discover commands and inspect active tools:

/help
/mcp
/exit

For automation, pipe the prompt through stdin and choose plain or jsonl output:

printf '%s\n' 'Summarize the responsibilities of an MCP server in three sentences.' | octomind run --format plain

run takes a role/tag positional argument, not a message argument. See Daemon & Hooks for persistent workers and Workflows for multi-step runs.

Usage Guide

Integration Guide

Use Cases

Development Guide

Common Questions

If the shell cannot find the binary after the default installation, add the installer directory to your current shell's path:

export PATH="$HOME/.local/bin:$PATH"
octomind --version

If login cannot open a local browser, print the URL instead:

octomind login --no-browser

If a piped command hangs, ensure its producer closes stdin; Octomind reads the complete prompt before starting. For configuration and credential errors, start with octomind config --validate above and the guides below.

Troubleshooting and Reference

See also

• Architecture
• CLI Reference
• Common Issues
• GitHub Repository
• Issues
• Discussions
• Provider Library
• OctoHub Gateway