> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-update-deprecated-models.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentOS on Docker

> Run AgentOS locally using Docker.

This template includes AgentOS and PostgreSQL with pgvector. Run locally for development, or deploy to any cloud that supports Docker.

## Prerequisites

* [Docker Desktop](https://docs.docker.com/get-docker/)
* An API key from a model provider

## Step-by-step Guide

<Steps>
  <Step title="Install tools">
    * Install [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/)
    * Install [uv](https://docs.astral.sh/uv/) (Python package manager)
  </Step>

  <Step title="Create and activate a virtual environment">
    ```bash theme={null}
    uv venv --python 3.12
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Install Agno">
    ```bash theme={null}
    uv pip install -U 'agno[infra]'
    ```
  </Step>

  <Step title="Create your codebase">
    ```bash theme={null}
    ag infra create --template agentos-docker --name agentos-docker

    cd agentos-docker
    ```

    <Tip>
      Or clone directly: `git clone
              https://github.com/agno-agi/agentos-docker-template.git`
    </Tip>
  </Step>

  <Step title="Export your API key">
    ```bash theme={null}
    export OPENAI_API_KEY=sk-***
    ```

    <Tip>
      Agno works with any model provider. Just update the agents in your codebase.
    </Tip>
  </Step>

  <Step title="Start your AgentOS">
    ```bash theme={null}
    docker compose up -d --build
    ```
  </Step>

  <Step title="Verify it works">
    Open [http://localhost:8000/docs](http://localhost:8000/docs) to see your AgentOS API:

    <Frame>
      <img src="https://mintcdn.com/agno-v2-update-deprecated-models/pmcAegusM2TuIVwq/images/agentos-endpoints.png?fit=max&auto=format&n=pmcAegusM2TuIVwq&q=85&s=8c9e871a7a61902d4492f7336f11dc93" alt="AgentOS FastAPI endpoints" width="3064" height="2272" data-path="images/agentos-endpoints.png" />
    </Frame>
  </Step>

  <Step title="Connect your AgentOS to the control plane">
    1. Open [os.agno.com](https://os.agno.com)
    2. Click "Connect OS" and select "Local"
    3. Enter `http://localhost:8000`

    <Frame>
      <img src="https://mintcdn.com/agno-v2-update-deprecated-models/pmcAegusM2TuIVwq/images/agent-os-connection-dialog.png?fit=max&auto=format&n=pmcAegusM2TuIVwq&q=85&s=e251d597f9aaee1525febc380f7abe79" alt="AgentOS connection dialog" width="2472" height="2408" data-path="images/agent-os-connection-dialog.png" />
    </Frame>

    Your AgentOS is deployed in a docker container and is accessible at `http://localhost:8000`.
  </Step>
</Steps>

## Tips

<AccordionGroup>
  <Accordion title="Cloud Deployment">
    You can also deploy this template to any cloud that supports Docker.

    * **Cloud providers:** [AWS ECS](https://aws.amazon.com/ecs/), [Google Cloud Compute Engine](https://cloud.google.com/compute-engine/), [Azure Virtual Machines](https://azure.microsoft.com/en-us/products/virtual-machines/)
    * **Platforms:** [Railway](https://railway.app/), [Render](https://render.com/), [DigitalOcean](https://digitalocean.com/), [Fly.io](https://fly.io/), [Modal](https://modal.com/)
  </Accordion>

  <Accordion title="Hot reload">
    Changes to agents, teams, and workflows are reflected automatically.
  </Accordion>

  <Accordion title="Environment variables">
    Restart containers when updating environment variables.
  </Accordion>

  <Accordion title="Common commands">
    | ag infra           | docker compose                 | Description        |
    | ------------------ | ------------------------------ | ------------------ |
    | `ag infra up`      | `docker compose up -d --build` | Start containers   |
    | `ag infra down`    | `docker compose down`          | Stop containers    |
    | `ag infra restart` | `docker compose restart`       | Restart containers |
    |                    | `docker compose logs -f`       | View logs          |
  </Accordion>

  <Accordion title="Project structure">
    ```
    agentos-docker/
    ├── agents/              # Your agents
    ├── teams/               # Your teams
    ├── workflows/           # Your workflows
    ├── app/                 # AgentOS directory
    ├── db/                  # Database tables
    ├── compose.yml          # Docker Compose configuration
    ├── Dockerfile           # Container build
    ├── pyproject.toml       # Python dependencies
    └── scripts/             # Helper scripts
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    Modify `compose.yml`: `yaml ports: - "8080:8000" # Change 8000 to 8080 `
  </Accordion>

  <Accordion title="Database connection issues">
    Ensure PostgreSQL is running: `bash docker compose ps ` If the database
    isn't ready, wait a few seconds and try again.
  </Accordion>
</AccordionGroup>