AgentOS on AWS

AgentOS is a secure, scalable platform for running agents. The agentos-aws codebase runs AgentOS locally using Docker and deploys to production on AWS. 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 runs in your own AWS account: the deploy scripts use ECS Express Mode for the service and RDS for Postgres.

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-aws.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 deploying to production first using ./scripts/aws/up.sh (needs a recent AWS CLI v2 with credentials configured and Docker running; the script pauses while I mint a JWT key at os.agno.com, and saves the MCP_CONNECT_SECRET — the OAuth consent secret — in .env.production). Then I add https://<service-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-aws.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. Deploy to production first, then add `https://<service-url>/mcp` as a custom connector and approve the consent page with the `MCP_CONNECT_SECRET` that `up.sh` generates.
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`.

Deploy to production

Prerequisites: AWS CLI v2 recent enough for ECS Express Mode (aws ecs create-express-gateway-service help must work), credentials configured (aws sts get-caller-identity succeeds), and Docker running. The image is built locally and pushed to ECR.

Create a production env

cp .env .env.production

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

Deploy

./scripts/aws/up.sh

Provisions an ECR repo, a private RDS PostgreSQL 17 instance, and Secrets Manager secrets, then makes one aws ecs create-express-gateway-service call. That call brings the Fargate service, an ALB with HTTPS, security groups, autoscaling, CloudWatch logs and alarms, and a public URL (https://ag-<id>.ecs.<region>.on.aws, generated per service). The script pins scaling to a single always-on task so the in-process scheduler never double-fires, and sets AGENTOS_URL to the generated URL so scheduled jobs reach the platform. It also generates MCP_CONNECT_SECRET into .env.production when it’s missing, so chat apps can connect over OAuth from the first deploy.The first run takes 30-45 minutes end to end. Certificate and DNS provisioning is the long pole, and the script waits until the gateway actually answers before declaring success. Redeploys take minutes. Region comes from AWS_REGION (default us-east-1).

This stack idles at roughly

100-110/month: about

70/mo for Fargate (2 vCPU/4 GB),

17-25/mo for the ALB (shared across up to 25 Express services), and

14/mo for the RDS db.t4g.micro. AWS bills idle resources. Tear down what you don’t use with ./scripts/aws/down.sh.

Mint your JWT key

The script pauses for a JWT_VERIFICATION_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 service 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 the up.sh prompt. The script saves it to your env file, pushes it to Secrets Manager, and rolls a fresh task-definition revision.

If you skip the prompt, add the key to .env.production later and run ./scripts/aws/env-sync.sh. If .env.production sets JWT_JWKS_FILE instead, the script skips the prompt and delivers the path through the task-definition env.

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

Connect your MCP clients

Re-run uvx agno connect, this time pointed at your deployed domain:

uvx agno connect --url https://<service-url>

For claude.ai and ChatGPT on the web: add https://<service-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 that up.sh generated during deploy (saved in .env.production).

Confirm it's live

aws logs tail /ecs/agent-os --follow

The app finishes rolling out behind the gateway; first boot pulls the image and waits for the database. Open https://<service-url>/docs to confirm the API is serving.

Your AgentOS is live on AWS.

Redeploy after code changes

./scripts/aws/redeploy.sh

Sync environment variables

./scripts/aws/env-sync.sh

Tear down

./scripts/aws/down.sh

Deletes the Express service (its ALB wiring, security groups, and autoscaling with it), the RDS instance and all its data with no final snapshot, the ECR repo and its images, the agentos/* secrets, and the log group. If no other Express service shares the gateway ALB, the script removes that too, then prints verification commands so you can confirm nothing is left billing.

Get Started

Starters

Apps

Agno CLI

AgentOS on AWS

Get started

Manual setup

Connect your frontends

Deploy to production

Redeploy after code changes

Sync environment variables

Tear down

Next steps

Build with coding agents

AWS reference

​Get started

​Manual setup

​Connect your frontends

​Deploy to production

​Redeploy after code changes

​Sync environment variables

​Tear down

​Next steps

Build with coding agents

AWS reference

Get started

Manual setup

Connect your frontends

Deploy to production

Redeploy after code changes

Sync environment variables

Tear down

Next steps