Skip to main content

​
Overview

This guide will take you from zero to chatting with an agent in just a few steps. You’ll initialize a project, configure an API key, start the engine, and interact with your first agent.
Before starting, make sure you have installed AgentOS.

​
Quick Start (2 Commands)

The fastest way to get started:
1

Initialize and configure

Initialize your project and set your API key:
agentos init --quick
agentos config set-key anthropic $ANTHROPIC_API_KEY
The --quick flag scaffolds a minimal project with default configuration.
2

Start and chat

Start the engine and chat with the default agent:
agentos start
agentos chat default
This starts all workers and opens an interactive chat session.

​
Detailed Walkthrough

For a deeper understanding of what’s happening, follow these detailed steps:
1

Initialize Your Project

Create a new AgentOS project:
agentos init --quick
This command creates:
  • config.yaml - iii-engine configuration
  • data/ - State, streams, and KV store directories
  • Default agent templates
  • System identity files
The configuration file sets up the iii-engine with essential modules:
port: 49134  # WebSocket port for worker connections

modules:
  - class: modules::api::RestApiModule
    config:
      port: 3111  # HTTP API port
      host: 0.0.0.0
  
  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::KvStore
        config:
          store_method: file_based
          file_path: ./data/state
  
  - class: modules::queue::QueueModule
  - class: modules::pubsub::PubSubModule
  - class: modules::cron::CronModule
  - class: modules::kv_server::KvServer
  - class: modules::observability::OtelModule
2

Configure Your API Key

AgentOS supports 25 LLM providers. Set your preferred provider’s API key:
agentos config set-key anthropic $ANTHROPIC_API_KEY
You can configure multiple providers. The LLM router will automatically select the best model based on task complexity.
View all configured keys:
agentos config keys
3

Start the Engine

Launch all AgentOS workers:
agentos start
This command starts:
  • iii-engine (WebSocket server on port 49134)
  • Rust workers: agent-core, security, memory, llm-router, wasm-sandbox
  • Control plane: realm, hierarchy, directive, mission, ledger, council, pulse, bridge
  • TypeScript workers: api, tools, workflow, and 36 more
  • Python worker: embedding service
The system is ready when you see:
✓ iii-engine started (port 49134)
✓ 18 Rust workers connected
✓ 39 TypeScript workers connected
✓ 1 Python worker connected
✓ AgentOS ready
4

Chat with an Agent

Start an interactive chat session with the default agent:
agentos chat default
You’ll enter an interactive prompt:
Connected to agent: default
Type your message (or 'exit' to quit)

You>
Try asking:
You> What can you do?
You> Search the web for the latest AI news
You> Help me write a Python function to parse JSON
5

Send Single Messages

For one-off queries without entering chat mode:
agentos message default "What's the weather like today?"
This sends a single message and returns the response.

​
Alternative: Development Mode

For development or debugging, you can start components manually:
1

Start iii-engine

iii --config config.yaml
2

Start Rust workers (in separate terminals)

cargo run --release -p agentos-core &
cargo run --release -p agentos-security &
cargo run --release -p agentos-memory &
cargo run --release -p agentos-llm-router &
cargo run --release -p agentos-wasm-sandbox &
3

Start control plane workers

cargo run --release -p agentos-realm &
cargo run --release -p agentos-hierarchy &
cargo run --release -p agentos-directive &
cargo run --release -p agentos-mission &
cargo run --release -p agentos-ledger &
cargo run --release -p agentos-council &
cargo run --release -p agentos-pulse &
cargo run --release -p agentos-bridge &
4

Start TypeScript workers

npx tsx src/api.ts &
npx tsx src/agent-core.ts &
npx tsx src/tools.ts &
npx tsx src/workflow.ts &
5

Start Python embedding worker (optional)

python workers/embedding/main.py &
6

Chat with the agent

cargo run -p agentos-cli -- chat default

​
System Status

Check the status of your AgentOS installation: 
# View system status
agentos status

# Health check
agentos health

# Diagnose issues
agentos doctor

# Repair common issues
agentos doctor --repair

​
What’s Next?

Now that you have AgentOS running, explore these features:

Create Custom Agents

Build agents tailored to your specific needs

Install Skills

Extend capabilities with 15,000+ skills from SkillKit

Configure Channels

Connect to Slack, Discord, Telegram, and 37 more platforms

Terminal UI

Explore the CLI and terminal dashboard

​
Common Commands

Here are the most frequently used commands: 
# Agent operations
agentos agent list              # List all agents
agentos agent new coder         # Create agent from template
agentos agent spawn researcher  # Spawn background agent

# Configuration
agentos config show            # View all configuration
agentos config get <key>       # Get specific value
agentos config set <k> <v>     # Set configuration value

# System control
agentos start                  # Start all workers
agentos stop                   # Stop all workers
agentos status                 # View system status

# Terminal UI
agentos tui                    # Launch interactive dashboard

​
Launch Terminal UI

For a visual interface, launch the terminal dashboard: 
agentos tui
This opens a full-featured dashboard with 21 screens:
  • Dashboard - System overview
  • Agents - Manage and monitor agents
  • Chat - Interactive chat interface
  • Channels - Configure integrations
  • Skills - Browse and install skills
  • Memory - View agent memory
  • Audit - Security audit log
  • And 14 more…
Navigate with number keys (1-0), letters (m, a, s, etc.), and Tab/Shift-Tab.

​
Troubleshooting

​
Port Already in Use

If port 49134 or 3111 is already in use, edit config.yaml: 
port: 49135  # Change WebSocket port

modules:
  - class: modules::api::RestApiModule
    config:
      port: 3112  # Change HTTP API port

​
Workers Not Connecting

Check if iii-engine is running: 
iii --version
ps aux | grep iii
Restart the engine: 
agentos stop
agentos start

​
API Key Not Working

Verify your API key is set: 
agentos config keys
If missing, set it again: 
agentos config set-key <provider> <your-api-key>

​
Getting Help

Need assistance? You’re now ready to build with AgentOS!

Build docs developers (and LLMs) love

Get started for freeTalk to us