Skip to main content
The agentos-fly template is for teams that develop locally with Docker and deploy to production on Fly.io. 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 container logs to inspect and improve the platform.

​
Get started

Copy the prompt below into Claude Code, Cursor, or Codex to configure and run 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: flyctl installed and fly auth login 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

Provisions the app and an unmanaged Fly Postgres on the same private network, pushes your credentials as Fly secrets, and deploys a single always-on machine. Fly app names are global, so the script generates agentos-<suffix> and records it in fly.toml. It also sets AGENTOS_URL to https://<app>.fly.dev before the first deploy so scheduled jobs reach the platform, and generates MCP_CONNECT_SECRET, the OAuth consent secret for chat apps, into .env.production when it’s missing.Deploys use fly deploy --ha=false on purpose: the Fly default creates two machines, which doubles cost and runs two in-process schedulers double-firing every cron. Default sizing is shared-cpu-2x with 4 GB (21/mo)plusasmallPostgresmachine( 21/mo) plus a small Postgres machine (~4/mo). For dedicated cores, switch the size to performance-2x ($62/mo) in fly.toml.
Fly’s stock postgres-flex image does not ship pgvector: sessions and memory work out of the box, but knowledge bases (RAG) need the extension. Set FLY_PG_IMAGE to a postgres-flex derivative with pgvector installed before running up.sh. Without it, the script prints a warning and everything except knowledge bases works. See Enable pgvector.
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 Fly 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 deploys.
If you skip the prompt, add JWT_VERIFICATION_KEY to .env.production later and run ./scripts/fly/env-sync.sh. For JWKS, bake or mount the file in the Fly Machine, set JWT_JWKS_FILE to its container path, then deploy. Env sync only forwards the path.
Live AgentOS connections are a paid feature. Use code PLATFORM30 for one month off.
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://<app>.fly.dev/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

The app name comes from fly.toml, so no --app flag is needed. Open https://<app>.fly.dev/docs to confirm the API is serving.
Your AgentOS is live on Fly.io.

​
Redeploy after code changes

​
Sync environment variables

​
Tear down

Destroys the Fly app and its Postgres, including all data in the database. Once both are confirmed gone, it resets fly.toml so a future up.sh provisions fresh.

​
Next steps

Build with coding agents

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

Fly.io reference

Commands, environment variables, troubleshooting.