AgentOS is a durable agent runtime that serves agents over API, MCP, and chat interfaces like Slack. Build customer-facing agents and serve them to your users from your product, through AI apps like Claude and ChatGPT, or interfaces like Slack. AgentOS gives you one agent backend for every frontend.

Three ways to build agents.

1. Coding agent. Point a coding agent at the skills in .agents/skills/ and it can create, improve and evaluate your agents for you.
2. Natural language. Ask the built-in Platform Builder to build agents for you.
3. No-code Studio. Build agents visually using the AgentOS Studio.

Three ways to serve your agents to your users.

1. Your product. Call the AgentOS REST API from your product.
2. AI apps. Connect your agents to Claude and ChatGPT using the AgentOS MCP server.
3. Chat interfaces. Distribute your agents through Slack, WhatsApp (and more) using AgentOS Interfaces.

Monitor and govern your agents.

The AgentOS Control Plane gives you a unified view of your agent platform. Trace every action. Enforce agent- and tool-level permissions.

Everything runs in your cloud, your data lives in your database.

Copy this prompt into your favorite coding agent. It sets up the platform and builds your first agent for you:

Help me set up my agent platform and build my first agent.

Clone https://github.com/agno-agi/agentos-modal into a folder called agent-platform, cd in, and run the setup-platform skill (in .agents/skills/).

Your coding agent checks Docker, sets up .env, boots the platform, verifies the MCP endpoint, connects to the AgentOS UI, then builds your first agent. Prefer to drive yourself? See Manual Setup.

Prerequisite: Docker installed and running.

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

# Configure credentials
cp example.env .env
# Open .env and set OPENAI_API_KEY

# Run the platform on docker
docker compose up -d --build

Confirm your AgentOS is running at http://localhost:8000/docs.

1. Open os.agno.com and sign in.
2. Click Connect OS, enter http://localhost:8000 as the URL, name it Local AgentOS, and connect.

1. Click Chat under the Agno team and tell it what you're working on: "Help me build an agent for my product".
2. Give it the docs URL for your product, or for a product you like — docs.agno.com, say.
3. Click the Refresh button on the top right. You should now see your new agent in the Agents dropdown. Chat with it directly, or just ask Agno to run it for you.

Your cloned repo points at this public template. Create your own GitHub repo and point your platform at it:

git remote rename origin upstream    # keep the template connected for updates
git remote add origin <your-private-repo-url>
git push -u origin main

Heads up. Create the private repo first (github.com/new, or gh repo create <name> --private). Keep upstream connected, so that git pull upstream main brings in template updates in the future.

You can run the platform anywhere that supports containerized images. This template deploys the container to Modal (always-warm, single container) paired with Neon serverless Postgres for pgvector persistence (Modal has no managed Postgres of its own) — and a coding-agent skill, /deploy-platform, that will help you deploy it.

Prerequisites: the modal CLI (pip install modal + modal token new), neonctl (npm i -g neonctl or brew install neonctl, then neonctl auth), Python 3, and OpenSSL.

Create a new .env.production file for production credentials.

cp .env .env.production          # or cp example.env .env.production
# Edit .env.production with production values

Keeping a separate .env.production lets us use different values for local and production: different OpenAI keys, production-only credentials, a different Slack workspace.

./scripts/modal/up.sh

This creates a Neon Postgres project (pgvector included; connection facts persist to your env file), writes the agentos-secrets Modal secret, and modal deploys the app from modal_app.py — the image is built from this repo's own Dockerfile, kept always-warm with min_containers=1 and capped at max_containers=1 (the in-process scheduler must not run twice). The script then pins AGENTOS_URL to the stable https://<workspace>--agentos.modal.run URL, generates MCP_CONNECT_SECRET (the chat-app OAuth consent secret, printed in the closing summary) when your env file doesn't have one, and pauses for a JWT verification key (see next section).

Neon project & organizations. up.sh creates the Neon project with neonctl. Neon projects are org-scoped, so neonctl projects create needs an organization — set NEON_ORG_ID (find it with neonctl orgs list) in .env.production so the deploy runs unattended instead of stopping at an interactive org prompt. Alternatively, create the project yourself at console.neon.tech and fill DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_DATABASE in .env.production; up.sh detects those and skips creation. In that case NEON_PROJECT_ID won't be set, so down.sh can't delete the database — remove it by hand in the Neon console.

Token-Based Authorization is on by default. Without a JWT_VERIFICATION_KEY or JWT_JWKS_FILE, the app refuses to serve traffic in production. The platform's job is to keep your data private, so the safe default is "refuse to start" without an authentication token.

Token-Based Auth gives you three things:

1. No public access. The server rejects requests without a valid token.
2. Per-request identity. Middleware parses the token and extracts the user_id, session_id, and custom claims. Each request is tied to a user and session, giving you auditability and traceability.
3. Granular permissions. Scopes on the token decide what each caller can do — run agents, read sessions, manage the platform. Admin tokens can do everything; scoped tokens get exactly what their claims grant.

During ./scripts/modal/up.sh, once the app URL exists the script pauses so you can mint the key.

1. Open os.agno.com, click Connect OS → Live, and enter your modal.run URL.
2. Name it Live AgentOS, flip Token-Based Authorization (JWT) on and connect. The UI generates your public key. (Ran into an issue? Go to Settings → OS & Security → Token-Based Authorization (JWT) to get the key from the settings page.)
3. Copy the public key.
4. Paste the full public key into the up.sh prompt. The script saves it into your env file for future syncs:

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

If you run non-interactively or skip the prompt, you can sync environment variables later with ./scripts/modal/env-sync.sh.

The script prints the app URL — open /docs on it, or tail the logs:

modal app logs agentos

AgentOS comes with an MCP server at /mcp (wired via mcp=MCPConfig(...) in app/main.py), where Agno itself is published as a first-class agno tool — clients just call it, no id discovery. There are two ways to connect your AgentOS to MCP clients:

1. AI Apps like Claude and ChatGPT connect to your AgentOS over the internet using OAuth. Add https://<workspace>--agentos.modal.run/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 that up.sh generated during deploy (saved in .env.production).
2. Coding agents like Claude Code, Claude Desktop, Codex, and Cursor connect to your AgentOS via the MCP URL. Register your AgentOS with the MCP clients on your machine:

uvx agno connect --url https://<workspace>--agentos.modal.run

After a successful connection, open one of these apps and ask:

can you access my agentos mcp?

./scripts/modal/redeploy.sh

Modal rebuilds the image from the Dockerfile (cached layers where nothing changed) and rolls the always-warm container.

To re-sync environment variables, run the following command:

./scripts/modal/env-sync.sh

It rewrites the agentos-secrets Modal secret and redeploys — secrets are read at container start, so the redeploy is what applies them.

./scripts/modal/down.sh

Stops the Modal app and deletes the Neon project, including all data, then verifies both are gone before declaring success.

Change authorization=runtime_env != "dev" to authorization=False in app/main.py and redeploy. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your service URL can access your platform.

This platform is designed so that coding agents can drive the entire create → improve → evaluate → maintain lifecycle for you.

Open your coding agent of choice (Claude Code, Codex, Cursor) and run:

/create-agent

It asks a few questions, generates the agent file in agents/, registers it in app/main.py, adds its description and quick prompts to app/config.yaml, restarts the container, and smoke-tests it for you.

Improve your agents by running the following skills:

• /extend-agent — Add a tool, add a capability, refine the instructions, fix a known bug.
• /improve-agent — Claude simulates scenarios from the agent's INSTRUCTIONS and its real usage recorded in the database, runs them against the live container, judges the responses, and edits until they pass.

Run the eval suite to check for regressions. The evals live in evals/cases.py, and run history shows up in the AgentOS UI next to your sessions and traces.

The evals run on the host machine, so set up the venv with ./scripts/venv_setup.sh && source .venv/bin/activate, then run:

python -m evals --tag smoke      # fast checks of the self-driving surfaces
python -m evals --tag release    # broader pre-release confidence
python -m evals --name <case>    # one case while iterating
python -m evals -v               # stream the full run with rich panels

If a case fails, run /eval-and-improve — it diagnoses each failure, fixes what's in scope, and loops until green.

Because the repo is managed by coding agents, it moves fast. Run /review-and-improve before a release or after a refactor: it sweeps for drift between docs, code, and config, auto-fixes mechanical drift like stale paths and missing env vars, and flags anything bigger.

• Agno documentation
• AgentOS introduction
• Agno on GitHub. Drop a star if this is useful.