Docker Reference

The Compose services are agentos-api (the app) and agentos-db (Postgres with pgvector). Production runs the same files plus the compose.prod.yaml override; the full flow is on the deploy page.

Manage

Task	Command
Deploy code changes	`git pull`, then `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`
Tail production logs	`docker compose -f compose.yaml -f compose.prod.yaml logs -f agentos-api`
Stop the platform	`docker compose down` (keeps the `pgdata` volume)
Tear down	`docker compose down -v` (deletes the `pgdata` volume and all platform data)

Production auth

Token-Based Authorization is on by default. Production startup requires JWT_VERIFICATION_KEY or a readable JWKS file at the container path in JWT_JWKS_FILE; otherwise the process exits. Token-Based Auth gives you three things:

Protected application routes. AgentOS routes require a valid token. The operational and documentation routes /, /health, /info, /docs, /redoc, /openapi.json, and /docs/oauth2-redirect remain public.
Per-request identity. Middleware validates the token and exposes its user_id, optional session_id, scopes, and claims to the request.
Scope-based permissions. Token scopes control access to AgentOS routes and resources.

The templates do not enable per-user data isolation. To scope non-admin session, memory, trace, and run access to the JWT subject, pass authorization_config=AuthorizationConfig(user_isolation=True) to AgentOS. See User Isolation. To opt out (not recommended), set authorization=False in app/main.py and restart. Use this only inside a private network behind another auth layer. Without it, anyone who finds your public URL can access your platform.

Customize

Add an agent

Ask your coding agent to run /create-new-agent, or do it by hand. Create agents/my_agent.py:

from agno.agent import Agent

from app.settings import default_model
from db import get_postgres_db

INSTRUCTIONS = """\
What the agent does, which tools it uses, the rules to follow when answering.
"""

my_agent = Agent(
    id="my-agent",
    name="My Agent",
    model=default_model(),
    db=get_postgres_db(),
    instructions=INSTRUCTIONS,
    enable_agentic_memory=True,
    add_datetime_to_context=True,
    add_history_to_context=True,
    num_history_runs=5,
)

from agents.my_agent import my_agent

agent_os = AgentOS(
    ...,
    agents=[agent_builder, platform_manager, web_search, my_agent],
)

Local containers hot-reload on save. For production, rebuild with docker compose -f compose.yaml -f compose.prod.yaml up -d --build.

Change the model

app/settings.py defines default_model(), used by every agent. Change it in one place:

from agno.models.anthropic import Claude

def default_model():
    return Claude(id="claude-sonnet-5")

Add anthropic to pyproject.toml, set the provider key in your env, and regenerate pins:

./scripts/generate_requirements.sh

Rebuild locally with docker compose up -d --build. For production:

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

Add tools

Agno ships 100+ toolkits. See Toolkits.

from agno.tools.slack import SlackTools

my_agent = Agent(
    ...,
    tools=[SlackTools()],
)

Add dependencies

Edit pyproject.toml.
Regenerate pins: ./scripts/generate_requirements.sh (add upgrade to refresh every pin).
Rebuild locally with docker compose up -d --build, or in production with docker compose -f compose.yaml -f compose.prod.yaml up -d --build.

Enable Slack

Set both variables in .env:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...

Apply with docker compose up -d (in production, docker compose -f compose.yaml -f compose.prod.yaml up -d). The interface activates automatically and routes messages to Agent Builder; change the agent= argument in app/main.py to point at another agent. See Slack setup.

Toggle scheduled workflows

The deployment check runs daily by default (ENABLE_DEPLOY_CHECK=True); it is deterministic and free. Scheduled evals are off by default (ENABLE_SCHEDULED_EVALS=False) because they use model calls. Both workflows stay runnable on demand regardless.

Format, validate, and run evals

The format, validate, and eval scripts run on the host and need a venv. Set it up once:

./scripts/venv_setup.sh
source .venv/bin/activate

Task	Command
Format	`./scripts/format.sh`
Lint and type-check	`./scripts/validate.sh`
Run smoke evals	`python -m evals --tag smoke`

./scripts/mcp_check.sh runs inside the container, so it needs no venv.

Environment variables

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes	-	Models and embeddings.
`RUNTIME_ENV`	No	`prd`	`dev` disables JWT. `compose.yaml` sets `dev` for local; `compose.prod.yaml` sets `prd`. Never hand-set `dev` on a production host, or the platform serves unauthenticated.
`JWT_VERIFICATION_KEY`	Production	-	Public key from os.agno.com. Quote the value so the multi-line PEM parses as one variable.
`JWT_JWKS_FILE`	Production	-	Path inside the container to a JWKS file. Production Compose does not mount this file. Add a read-only bind mount, or bake the file into the image and rebuild.
`MCP_CONNECT_SECRET`	No	-	OAuth consent secret (16+ chars) for connecting claude.ai and ChatGPT to `/mcp`. Set it yourself in `.env`, e.g. `openssl rand -base64 32`. Dev reads the same file, so it gates the local `/mcp` too.
`AGENTOS_MCP_SIGNING_KEY`	No	generated	Optional high-entropy signing-key material (32+ chars) for OAuth tokens. Unset, a strong key is generated and persisted in the database. Rotating it invalidates outstanding tokens.
`AGENTOS_URL`	No	`http://127.0.0.1:8000`	Scheduler base URL. Set it in `.env` to your public URL; `compose.prod.yaml` passes it through. Left at the default in production, the daily deployment check flags the platform as misconfigured. When `MCP_CONNECT_SECRET` is set, OAuth metadata also derives its public origin from this URL.
`ENABLE_DEPLOY_CHECK`	No	`True`	Daily deployment-check cron.
`ENABLE_SCHEDULED_EVALS`	No	`False`	Daily run-evals cron. Uses model calls.
`EVALS_TAG`	No	`smoke`	Eval tag the run-evals workflow runs.
`EVALS_CASE_TIMEOUT_SECONDS`	No	`90`	Per-case timeout for run-evals runs.
`EVALS_SUITE_TIMEOUT_SECONDS`	No	`900`	Whole-suite timeout for run-evals runs.
`PARALLEL_API_KEY`	No	-	WebSearch uses the Parallel SDK when set, keyless MCP otherwise.
`SLACK_BOT_TOKEN`	No	-	Set with the signing secret to enable Slack.
`SLACK_SIGNING_SECRET`	No	-	Set with the bot token to enable Slack.
`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_DATABASE`	No	matches compose	Postgres connection. Set a strong `DB_PASS` in production.
`DB_DRIVER`	No	`postgresql+psycopg`	SQLAlchemy driver.
`AGNO_DEBUG`	No	`False`	Verbose Agno logs. Compose sets it for dev.
`WAIT_FOR_DB`	No	`False`	If `True`, the entrypoint blocks on the database before starting. Compose sets it.

Troubleshooting

The API never comes up after docker compose up

The first build takes a few minutes. Read docker compose logs agentos-api and fix what you find.

Compose errors on !reset or !override

The production override uses Compose merge tags that need Docker Compose v2.24.4 or newer. Upgrade Docker Compose and rerun.

App fails to start in production

JWT auth is on whenever RUNTIME_ENV is not dev. Set JWT_VERIFICATION_KEY in .env and recreate the container. For JWT_JWKS_FILE, first add a read-only production bind mount and point the variable at its container path, or bake the file into the image and recreate with --build. To opt out inside a private network behind another auth layer, set authorization=False in app/main.py.

Changing DB_PASS has no effect

Postgres reads the password only when the pgdata volume is first initialized. On a host that already ran the dev Compose, the database keeps the old password and the API blocks waiting for it. Change the password in place and set .env to match:

docker compose exec agentos-db psql -U ai -c "ALTER USER ai WITH PASSWORD '<new>';"

Or reinitialize with docker compose down -v, which deletes all platform data.

Deployment check flags a misconfigured URL

AGENTOS_URL is still the localhost default. Set it in .env to your public URL and recreate the container with docker compose -f compose.yaml -f compose.prod.yaml up -d. Hosted chat apps also need this URL for their /mcp connector.

Get Started

Starters

Apps

Agno CLI

Docker Reference

Manage

Production auth

Customize

Format, validate, and run evals

Environment variables

Troubleshooting

​Manage

​Production auth

​Customize

​Format, validate, and run evals

​Environment variables

​Troubleshooting

Manage

Production auth

Customize

Format, validate, and run evals

Environment variables

Troubleshooting