Quickstart

This guide gets AgentOS installed, configured, and running locally. It assumes you want the standard product experience: terminal commands, local Web UI, Pilot Router, memory/search support, and safe local defaults.

Requirements#

• Python 3.12 or newer for terminal installs.
• uv for the recommended terminal install.
• Git, Git LFS, and Node.js 22 or newer only when installing from source.
• A provider API key unless you use a local provider such as Ollama.

Recommended Install#

Install the current release (recommended extras included) by following the Installation section of the README. The newest release assets are always on the Releases page.

The recommended extra includes Pilot Router dependencies and memory/search support used by the default product experience.

If agentos is not found after install, open a new shell or run:

uv tool update-shell

First-Run Setup#

Interactive setup:

agentos onboard

Script-friendly setup:

export OPENROUTER_API_KEY="sk-..."
agentos onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

Useful variants:

agentos onboard --if-needed
agentos onboard --minimal
agentos onboard --provider openai --api-key-env OPENAI_API_KEY
agentos onboard --provider ollama --model llama3.1

--if-needed is safe for install scripts because it avoids rewriting an already-ready setup. --minimal configures the provider path and skips optional channels/search/image-generation sections.

Check onboarding state:

agentos onboard status

Run the Gateway#

Foreground gateway:

agentos gateway run

Background gateway with readiness wait:

agentos gateway start --json
agentos gateway status

Default address:

http://127.0.0.1:18791/control/

The gateway defaults to loopback for safety. To bind elsewhere, opt in:

agentos gateway run --listen 0.0.0.0 --port 18791

Only expose a non-loopback gateway behind appropriate auth and network controls.

First Useful Run#

Open the Web UI:

http://127.0.0.1:18791/control/

Start terminal chat:

agentos chat

Run one automation turn:

agentos agent -m "Inspect this workspace and suggest a test plan"

Run a one-shot task in a specific workspace:

agentos agent \
  --workspace /path/to/project \
  --workspace-strict \
  -m "Review the current diff and list the highest-risk changes"

Use the Web UI for browser-based chat, approvals, setup, channels, usage, and logs. Use agentos chat when you want a terminal conversation. Use agentos agent for one-shot automation.

Resume Work#

Resume a terminal chat session:

agentos chat --session <session-key>

Inspect sessions:

agentos sessions list
agentos sessions show <session-key>
agentos sessions export <session-key>

Export a session when exact history matters for debugging or handoff.

Check Readiness#

Run these after setup:

agentos doctor
agentos providers list
agentos search list
agentos channels types --json

If the gateway is running, inspect runtime status:

agentos gateway status
agentos providers status
agentos channels status
agentos memory status

For provider/model selection details, see Providers and Models. For search setup, see Web Search.

For gateway lifecycle, host/port, and exposure guidance, see Gateway.

Stop or Restart#

Foreground gateway:

Ctrl+C

Managed background gateway:

agentos gateway stop
agentos gateway restart

Upgrade#

Upgrade to the latest release. agentos upgrade also restarts the gateway and verifies it reports the new version, so it is preferred over calling uv tool yourself:

agentos upgrade

It installs the published release of use-agent-os[recommended] — the same extras profile install_source.sh uses — pinned to the Python version already running AgentOS. Your configuration and data in ~/.agentos/ are not touched. To check the installed version, run uv tool list.

agentos upgrade never installs from a local checkout: only bash scripts/install_source.sh rebuilds the React control UI before installing. If you installed from source, re-run that script. See the README upgrade section.

Next Steps#

After the first run:

1. Configure search if you want web research: Web Search.
2. Enable channels if you want Slack, Telegram, Discord, or another messaging surface: Channels.
3. Review memory behavior if you want durable recall: Memory.
4. Review tool permissions before unattended automation: Tools, Approvals, and Sandbox.
5. Learn Pilot Router if you want cost-aware model routing: Pilot Router.
6. Use the glossary if product terms are unfamiliar: Glossary.

Install From Source#

Use source install when you want a checkout-backed install:

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/**"
git lfs pull --include="src/agentos/agentos_router/models/**"
bash scripts/install_source.sh

For development, use the repository virtual environment:

uv sync --extra recommended --extra dev
uv run agentos --help
uv run agentos gateway run

When developing from source, prefix commands with uv run so they use the checkout you are editing.