Set up AgentOS in
four steps.

What is AgentOS? #

AgentOS is a microkernel Python agent runtime. A local model router (AgentOS Router) sends each turn to the cheapest model that can handle it, while persistent memory, a layered sandbox, built-in web search, and on-device embeddings round out a single shared turn loop. Every entry point (Web UI, CLI, and chat channels) runs through that same loop.

Prerequisites #

Before you start, make sure your machine has the following. The install scripts handle the Python toolchain for you, but you will need these baseline pieces.

• 01

  Python 3.12 or newer

  AgentOS targets requires-python = ">=3.12". The Windows portable build bundles its own CPython, so you can skip this there.

• 02

  An API key for one model provider

  Cloud providers need a key. Local providers (Ollama, LM Studio) need no key, just a running model server. See step 3.

• 03

  Git with LFS (source install only)

  The AgentOS Router model files ship via Git LFS. Run git lfs install before cloning if you build from source.

Install AgentOS #

Three supported paths. The uv tool install route is recommended for most people. Pick the tab that matches your situation.

# 1 - install uv (macOS / Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2 - install AgentOS with the recommended extras (AgentOS Router)
uv tool install --python 3.12 \
  "use-agent-os[recommended] @ https://github.com/use-agent-os/agent-os/releases/download/v0.0.1/use_agent_os-0.0.1-py3-none-any.whl"

# 3 - verify
agentos --help

git lfs install
git clone https://github.com/use-agent-os/agent-os.git
cd agent-os
git lfs pull --include="src/agentos/memory/models/**"

# macOS / Linux
bash scripts/install_source.sh

# Windows (PowerShell)
# powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1

docker build -t agentos:local .

# macOS / Linux
./start.sh
# Windows
# ./start.ps1   →  runs: docker compose up -d

Run the onboarding wizard #

The interactive wizard walks you through six sections in order. Provider and Router are the fast path; the rest are skippable and can be configured later from the Web UI.

# full interactive wizard
agentos onboard

# provider only - skip channels, search, image-gen
agentos onboard --minimal

# inspect every section without writing anything
agentos onboard status

export OPENROUTER_API_KEY="sk-..."
agentos onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
agentos onboard --if-needed   # safe to re-run

Pick a model provider #

These twelve providers appear in the first-run wizard. OpenRouter is the default and sorts first. Each cloud provider reads its key from the listed environment variable; local providers need no key at all.

Beyond these twelve, the registry also knows Mistral, Groq, SiliconFlow, MiniMax, Azure OpenAI, LM Studio, vLLM and more. Set any of them by hand with agentos configure provider.

Run the gateway #

The gateway is the heart of AgentOS. By default it binds to loopback only - 127.0.0.1:18791 - so nothing is exposed to your network.

agentos gateway run

agentos gateway start --json
agentos gateway status

Once it reports ready, open the console in your browser:

http://127.0.0.1:18791/control/

agentos gateway run --listen 0.0.0.0 --port 18791

Prefer the terminal? Two no-browser entry points share the same loop:

# interactive REPL
agentos chat

# one-shot, scriptable
agentos agent -m "summarize today's commits"

Inside the Web console #

The console at /control/ is a single-page app. The views below are client-side routes. For example /control/setup and /control/chat.

Configuration #

Config is TOML. AgentOS resolves it in this order. Environment variables for individual secrets always win over file values.

1. 1AGENTOS_GATEWAY_CONFIG_PATHexplicit path
2. 2./agentos.tomlcurrent directory
3. 3~/.agentos/config.tomlglobal user config
4. 4built-in defaults

A minimal agentos.toml looks like this:

[llm]
provider  = "openrouter"
model     = "deepseek/deepseek-v4-flash"
base_url  = "https://openrouter.ai/api/v1"
# api_key is read from OPENROUTER_API_KEY

[agentos_router]
enabled        = true
auto_thinking  = true
default_tier   = "c1"

[agentos_router.tiers.c1]
provider = "openrouter"
model    = "deepseek/deepseek-v4-pro"

[memory]
source = "workspace"        # MEMORY.md + memory/*.md under the workspace

[permissions]
default_mode = "bypass"     # off | on | bypass | full

# [auth]
# mode  = "token"           # none | token | password - enable before binding 0.0.0.0
# token = "your-long-random-token"

agentos configure provider
agentos configure router
agentos configure channels
agentos configure search

Command reference #

The commands you will reach for most. Run agentos --help for the full set.

Troubleshooting #