> ## 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 Modal

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

**The [agentos-modal](https://github.com/agno-agi/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](/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 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.

<Snippet file="setup-prompt-modal.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-modal.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://<workspace>--agentos.modal.run/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:** Python 3 and OpenSSL. [Modal CLI](https://modal.com/docs/guide) installed with `modal token new` completed. [neonctl](https://neon.tech/docs/reference/neon-cli) installed with `neonctl auth` completed.

<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/modal/up.sh
    ```

    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.
  </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 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.
  </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://<workspace>--agentos.modal.run
    ```

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

  <Step title="Confirm it's live">
    ```bash theme={null}
    modal app logs agentos
    ```

    Open `https://<workspace>--agentos.modal.run/docs` to confirm the API is serving.
  </Step>
</Steps>

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

### Redeploy after code changes

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

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

### Sync environment variables

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

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

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

<Warning>
  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.
</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="Modal reference" icon="book" href="/deploy/templates/modal/reference">
    Commands, environment variables, troubleshooting.
  </Card>
</CardGroup>