> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentOS on AWS

> AgentOS template for teams that develop locally with Docker and deploy to production on AWS.

**The [agentos-aws](https://github.com/agno-agi/agentos-aws) template is for teams that develop locally with Docker and deploy to production on AWS.**

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](/deploy/coding-agents)** 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.

Production runs in your own AWS account: the deploy scripts use ECS Express Mode for the service and RDS for Postgres.

## Get started

Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.

<Snippet file="setup-prompt-aws.mdx" />

Prefer to drive yourself? Follow the manual steps below.

## Manual setup

**Prerequisites:** [Docker](https://www.docker.com/get-started/) installed and running. An [OpenAI API key](https://platform.openai.com).

<Steps>
  <Step title="Clone and configure">
    ```bash theme={null}
    git clone https://github.com/agno-agi/agentos-aws.git agentos
    cd agentos

    cp example.env .env
    ```

    Edit `.env` and set `OPENAI_API_KEY`.
  </Step>

  <Step title="Start the platform">
    ```bash theme={null}
    docker compose up -d --build
    ```

    The first build takes a few minutes. Confirm the API is available at [localhost:8000/docs](http://localhost:8000/docs).
  </Step>

  <Step title="Verify end to end">
    ```bash theme={null}
    ./scripts/mcp_check.sh
    ```

    Prints `MCP OK` with the tool count and a real agent answer through the MCP endpoint.
  </Step>

  <Step title="Connect the AgentOS UI">
    1. Open [os.agno.com](https://os.agno.com) and sign in.
    2. Click **Connect OS**, enter `http://localhost:8000`, and name it **Local AgentOS**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Check>At this point, your AgentOS is running locally.</Check>

## 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](https://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](/agent-os/interfaces/slack/setup).                                                                                                           |
| Your product                | Call the AgentOS REST API with 80+ endpoints. Browse them at `/docs`.                                                                                                                                            |

## Deploy to production

**Prerequisites:** [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 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.

<Steps>
  <Step title="Create a production env">
    ```bash theme={null}
    cp .env .env.production
    ```

    Edit `.env.production` with production values: a different OpenAI key, production-only credentials, a different Slack workspace.
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    ./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`).

    <Note>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`.</Note>
  </Step>

  <Step title="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](https://os.agno.com), click **Connect OS** → **Live**, and enter your service 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, pushes it to Secrets Manager, and rolls a fresh task-definition revision.

    If you skip the prompt, add `JWT_VERIFICATION_KEY` to `.env.production` later and run `./scripts/aws/env-sync.sh`. For JWKS, add the file to the image build context and rebuild, or configure a mount. Set `JWT_JWKS_FILE` to its container path, then redeploy the service. `up.sh` and `env-sync.sh` only forward the path.

    <Note>Live AgentOS connections are a paid feature. Use code `PLATFORM30` for one month off.</Note>
  </Step>

  <Step title="Connect your MCP clients">
    Re-run `uvx agno connect`, this time pointed at your deployed domain:

    ```bash theme={null}
    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`).
  </Step>

  <Step title="Confirm it's live">
    ```bash theme={null}
    aws logs tail /ecs/agent-os --follow --region <region>
    ```

    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.
  </Step>
</Steps>

<Check>Your AgentOS is live on AWS.</Check>

### Redeploy after code changes

```bash theme={null}
./scripts/aws/redeploy.sh
```

### Sync environment variables

```bash theme={null}
./scripts/aws/env-sync.sh
```

### Tear down

```bash theme={null}
./scripts/aws/down.sh
```

<Warning>
  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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Build with coding agents" icon="wand-magic-sparkles" href="/deploy/coding-agents">
    Skills to create → improve → evaluate your platform using coding agents.
  </Card>

  <Card title="AWS reference" icon="book" href="/deploy/templates/aws/reference">
    Commands, environment variables, troubleshooting.
  </Card>
</CardGroup>