Skip to main content
The agentos-modal template is for teams that develop locally with Docker and deploy to production on Modal. It includes:
  • Agent Builder, which creates agents, teams, and workflows.
  • Platform Manager, which inspects and explains the platform, eval history, deployment checks, and schedules.
  • Eight skills for setting up, building, testing, reviewing, and deploying the project with a coding agent.
Coding agents can use these skills with the AgentOS API, evals, traces, and deployment logs to inspect and improve the platform.

​
Get started

Copy the prompt below into Claude Code, Cursor, or Codex to set up the template with a coding agent.
Prefer to drive yourself? Follow the manual steps below.

​
Manual setup

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

Clone and configure

Edit .env and set OPENAI_API_KEY.
2

Start the platform

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

Verify end to end

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

Connect the AgentOS UI

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

Build your first agent

  1. Chat with Agent Builder: “Build an agent that tracks AI news and writes a daily brief”. Go through the agent development process.
  2. Once created, click Refresh on the top right, pick the new agent from the Agents dropdown, and ask: “What’s new with Anthropic?”
  3. 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

​
Deploy to production

Prerequisites: Python 3 and OpenSSL. Modal CLI installed with modal token new completed. neonctl installed with neonctl auth completed.
1

Create a production env

Edit .env.production with production values: a different OpenAI key, production-only credentials, a different Slack workspace.
2

Deploy

Reuses the DB_HOST and DB_PASS in your env file when both are set. Otherwise, it creates a Neon Postgres project and saves its connection details. The script writes your config into the agentos-secrets Modal secret and deploys modal_app.py as one always-warm container. It then sets AGENTOS_URL to the stable https://<workspace>--agentos.modal.run URL and generates MCP_CONNECT_SECRET when your env file does not have one.
3

Mint your JWT key

The script pauses for a JWT_VERIFICATION_KEY. Token-Based Authorization is on by default. Production startup requires that verification key or a readable JWKS file at the container path in JWT_JWKS_FILE; otherwise the process exits.
  1. Open os.agno.com, click Connect OS → Live, and enter your modal.run URL.
  2. Name it Live AgentOS, turn on Token-Based Authorization (JWT) on the connection panel, and connect. The UI generates the public key. If the OS is already connected, enable the setting under Settings → OS & Security.
  3. Copy the public key and paste the full PEM into the up.sh prompt. The script saves it to your env file and runs a second deploy to apply it.
If you skip the prompt, add JWT_VERIFICATION_KEY to .env.production later and run ./scripts/modal/env-sync.sh. For JWKS, add the file to the Docker build context or configure a Modal mount, set JWT_JWKS_FILE to its container path, then deploy. Env sync only forwards the path.
4

Connect your MCP clients

Re-run uvx agno connect, this time pointed at your deployed domain:
For claude.ai and ChatGPT on the web: 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).
5

Confirm it's live

Open https://<workspace>--agentos.modal.run/docs to confirm the API is serving.
Your AgentOS is live on Modal.

​
Redeploy after code changes

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

​
Sync environment variables

Rewrites the agentos-secrets Modal secret from .env.production and redeploys. Secrets are read at container start, so the redeploy is what applies them.

​
Tear down

Stops the Modal app and deletes the agentos-secrets secret. If NEON_PROJECT_ID is set, it also deletes that template-managed Neon project and its data. A supplied external database is retained. Database values stay in your env file; remove the Neon values only when you want up.sh to provision a fresh database.

​
Next steps

Build with coding agents

Skills to create → improve → evaluate your platform using coding agents.

Modal reference

Commands, environment variables, troubleshooting.