Skip to main content
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[cli]"
The PyPI package is called octo-agent, but the CLI command and Python import are just octo.Installation extras:
ExtraWhat it adds
cliRich terminal UI, Click, prompt_toolkit (recommended)
telegramTelegram bot transport
s3S3-compatible storage backend
postgresPostgreSQL checkpointing
allEverything above
Bare pip install octo-agent installs the core engine only — use [cli] for the terminal experience, or [all] for everything.
1

Run the setup wizard

octo init
The wizard walks you through:
  • Provider selection (Anthropic, Bedrock, OpenAI, Azure, GitHub Models)
  • Credential entry and validation
  • Workspace scaffolding (creates .octo/ directory)
2

Start chatting

octo
For a faster setup, use QuickStart mode — just 3 prompts (pick provider, paste key, done):
octo init --quick

​
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: 
octo doctor
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?

Configuration Deep Dive

Model tiers, profiles, and all environment variables

Set Up Telegram

Chat with Octo from your phone

Explore Features

Multi-agent supervisor, proactive AI, and more

Create Your First Agent

Build a custom specialist agent