Get up and running with Octo in under 2 minutes. This guide walks you through installation, setup, and your first conversation.
Prerequisites
Required
Python 3.11+ — the runtime for Octo itself
Node.js 18+ — required for MCP servers (most use npx)
At least one LLM provider — Anthropic, AWS Bedrock, OpenAI, Azure, or GitHub Models
Optional
Claude Code — enables project workers that delegate tasks via
claude -p. Without it, Octo still works with standard and deep research agents.
skills.sh — the open skills ecosystem. Install the CLI with
npm install -g skills to use
/skills import and
/skills find from chat. Local skills (
.octo/skills/) work without it.
Installation
Do not install Octo globally. It has many dependencies that can conflict with
other packages. Always use a virtual environment.
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install octo-agent
uv venv
source .venv/bin/activate
uv pip install octo-agent
git clone https://github.com/onetest-ai/Octo.git
cd Octo
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
The PyPI package is called octo-agent, but the CLI command and Python import are just octo.
Run the setup wizard
The wizard walks you through:
- Provider selection (Anthropic, Bedrock, OpenAI, Azure, GitHub Models)
- Credential entry and validation
- Workspace scaffolding (creates
.octo/ directory)
For a faster setup, use QuickStart mode — just 3 prompts (pick provider, paste key, done): Non-Interactive Setup
For CI/CD or Docker environments:
ANTHROPIC_API_KEY=sk-ant-... octo init --quick --provider anthropic --no-validate --force
Health Check
After setup, verify everything is working:
This runs 8 checks with PASS/FAIL output. Fix issues with:
octo doctor --fix # re-runs setup wizard on failures
octo doctor --json # machine-readable output
What’s Next?
