AgentOS on self-hosted Docker

AgentOS is a secure, scalable platform for running agents. The agentos-docker codebase runs AgentOS locally using Docker and deploys to production on self-hosted Docker. It comes with:

2 platform agents that build and run the platform for you. Agent Builder creates agents, teams, and workflows. Platform Manager monitors and manages the platform.
5 skills that let coding agents build, test, and improve the platform for you.

Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically. Production is the same Docker Compose you run locally plus one override file, on any host you control: a VPS, a home server, an office box, this laptop.

Get started

The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it’ll take you from zero to a running platform.

Help me set up AgentOS on this machine. Work step by step. When a step needs me (an API key, a Docker install, a sign-in), stop, tell me exactly what to do, and wait for my input. Never read or print secrets.

1. Clone https://github.com/agno-agi/agentos-docker.git into a folder called agent-platform and cd in. Then read AGENTS.md end to end — it is the source of truth for how this platform works and answers most questions you'll hit along the way.
2. Run `cp example.env .env`, open .env in my favorite editor, and ask me to set the OPENAI_API_KEY.
3. Confirm docker is installed, running and `docker info` succeeds. If Docker is missing, ask me to install Docker Desktop and wait until it's running.
4. Start the platform with `docker compose up -d --build`, then poll http://localhost:8000/docs until it returns 200 (first build takes a few minutes). If it never comes up, read `docker compose logs agentos-api` and fix what you find.
5. Prove it end to end with ./scripts/mcp_check.sh — it should print "MCP OK" and a real agent answer. Show me that answer: it's my platform talking.
6. Ask me which frontends I want connected, then set up the ones I pick:
   - Coding agents (including you): run `uvx agno connect` — it registers http://localhost:8000/mcp in Claude Code, Claude Desktop, Codex, and Cursor, and verifies with a real handshake.
   - The AgentOS web UI: walk me through os.agno.com → Connect OS → http://localhost:8000, named "Local AgentOS".
   - Claude and ChatGPT apps (web or desktop): their sessions run in the cloud and can't reach localhost, so work with me on getting a public URL first, following the "Run in production" section of README.md — a tunnel (cloudflared, ngrok, or `tailscale funnel`) in front of this machine, then production mode with a JWT key I mint at os.agno.com and the MCP_CONNECT_SECRET (the OAuth consent secret, openssl rand -base64 32) saved in .env. Then I add https://<public-url>/mcp as a custom connector in the chat app's connector settings and approve the consent page with that secret.
7. Finish with a short summary of what's running and where, plus a few first prompts to try — start with asking Agent Builder to "Build an agent that tracks AI news and writes a daily brief".

Prefer to drive yourself? Follow the manual steps below.

Manual setup

Prerequisites: Docker installed and running. An OpenAI API key.

Clone and configure

git clone https://github.com/agno-agi/agentos-docker.git agentos
cd agentos

cp example.env .env

Edit .env and set OPENAI_API_KEY.

Start the platform

docker compose up -d --build

The first build takes a few minutes. Confirm the API is available at localhost:8000/docs.

Verify end to end

./scripts/mcp_check.sh

Prints MCP OK with the tool count and a real agent answer through the MCP endpoint.

Connect the AgentOS UI

Open os.agno.com and sign in.
Click Connect OS, enter http://localhost:8000, and name it Local AgentOS.

Build your first agent

Chat with Agent Builder: “Build an agent that tracks AI news and writes a daily brief”. Go through the agent development process.
Once created, click Refresh on the top right, pick the new agent from the Agents dropdown, and ask: “What’s new with Anthropic?”
Ask Platform Manager: “How healthy is the platform?” It answers from eval history, deployment checks, schedules, and the agent you just built.

At this point, your AgentOS is running locally.

Connect your frontends

Frontend	How
MCP clients on your machine	`uvx agno connect` auto-detects Claude Code, Claude Desktop, Codex, and Cursor and registers `http://localhost:8000/mcp`. Verify from the app: “can you access my agentos mcp?”
AgentOS UI	os.agno.com → Connect OS → `http://localhost:8000`.
claude.ai and ChatGPT	Hosted sessions can’t reach localhost. Run in production first, then add `https://<your-public-url>/mcp` as a custom connector and approve the consent page with the `MCP_CONNECT_SECRET` you set in `.env`.
Slack	Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET`. See Slack setup.
Your product	Call the AgentOS REST API with 80+ endpoints. Browse them at `/docs`.

Run in production

Prerequisites: a host with Docker Compose v2.24.4 or newer (the prod override uses the !reset and !override merge tags), and a way for the internet to reach port 8000 on it: a domain with a reverse proxy, or a tunnel.

Get a public URL

The platform needs a public HTTPS URL for two things: hosted chat apps reaching /mcp, and AGENTOS_URL, the address the platform advertises as its own. Any of these work:

# Cloudflare Tunnel: free; quick tunnels get a random URL, named tunnels a stable one
cloudflared tunnel --url http://localhost:8000

# ngrok: reserved domains on paid plans
ngrok http 8000

# Tailscale Funnel: stable HTTPS URL on your tailnet's domain
tailscale funnel 8000

For a first run, an ephemeral cloudflared or ngrok URL is fine. For a real deployment, use something stable: a named Cloudflare tunnel, a reserved ngrok domain, or your own domain in front of a reverse proxy (Caddy, nginx) that forwards to port 8000.

Set up your production env

Production values live in .env on the host, the same file Compose already reads:

OPENAI_API_KEY=sk-...
AGENTOS_URL=https://<your-public-url>
MCP_CONNECT_SECRET=<generate with: openssl rand -base64 32>
DB_PASS=<generate a strong one>

AGENTOS_URL is the address the platform advertises as its own. Left unset, the daily deployment check flags the platform as misconfigured, and chat-app connectors have nothing to point at. MCP_CONNECT_SECRET turns /mcp into its own OAuth 2.1 authorization server so claude.ai and ChatGPT on the web can connect; connecting asks for this secret once, on a consent page. It needs AGENTOS_URL for a stable public origin, and because dev reads the same .env, it gates the local /mcp too. PAT and JWT bearers keep working alongside. DB_PASS replaces the dev default (ai).

On a host that already ran the dev Compose, changing DB_PASS in .env does not change the database password. See troubleshooting.

Mint your JWT key

Token-Based Authorization is on by default and without a verification key or a JWT_JWKS_FILE, the platform refuses to serve production traffic.

Open os.agno.com, click Connect OS → Live, enter your public URL, and name it Live AgentOS.
Go to Settings → OS & Security and turn on Token-Based Authorization (JWT).
Copy the public key and paste the full PEM into .env with quotes, so Docker Compose reads the multi-line value as one variable:

JWT_VERIFICATION_KEY="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkq...
-----END PUBLIC KEY-----"

Live AgentOS connections are a paid feature. Use code PLATFORM30 for one month off.

Start in production mode

docker compose -f compose.yaml -f compose.prod.yaml up -d --build

The override switches RUNTIME_ENV to prd (JWT auth on), drops the dev bind mount and hot reload so the container runs the code baked into the image, passes your AGENTOS_URL (and MCP_CONNECT_SECRET, if set) through, and rebinds Postgres to loopback so only this host can reach it. Both services carry restart: unless-stopped, so the platform survives reboots as long as Docker starts on boot.

Connect your MCP clients

Re-run uvx agno connect, this time pointed at your public URL:

uvx agno connect --url https://<your-public-url>

For claude.ai and ChatGPT on the web: add https://<your-public-url>/mcp as a custom connector in the chat app’s connector settings. Leave the form’s optional OAuth fields (client ID / client secret) empty. Click Connect and, on the consent page, enter the MCP_CONNECT_SECRET you set in .env.

Confirm it's live

curl https://<your-public-url>/health   # 200: /health and /docs stay public
curl https://<your-public-url>/agents   # 401: everything else wants a token

Logs, when something looks off:

docker compose -f compose.yaml -f compose.prod.yaml logs -f agentos-api

Your AgentOS is live on self-hosted Docker.

Redeploy after code changes

git pull   # or edit in place
docker compose -f compose.yaml -f compose.prod.yaml up -d --build

Apply env changes

docker compose -f compose.yaml -f compose.prod.yaml up -d

Env changes are the same command without --build. Compose recreates the container with the new .env values.

Tear down

docker compose down -v

Removes the containers and deletes the pgdata volume with all platform data: sessions, memory, knowledge, and eval history. Run docker compose down without -v to stop the platform and keep the data.

AgentOS on self-hosted Docker

Get started

Manual setup

Connect your frontends

Run in production

Redeploy after code changes

Apply env changes

Tear down

Next steps

Build with coding agents

Docker reference

​Get started

​Manual setup

​Connect your frontends

​Run in production

​Redeploy after code changes

​Apply env changes

​Tear down

​Next steps

Build with coding agents

Docker reference

Get started

Manual setup

Connect your frontends

Run in production

Redeploy after code changes

Apply env changes

Tear down

Next steps