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

​
Step-by-step Guide

1

Install tools

2

Create and activate a virtual environment

uv venv --python 3.12
source .venv/bin/activate
3

Install Agno

uv pip install -U 'agno[infra]'
4

Create your codebase

ag infra create --template agentos-docker --name agentos-docker

cd agentos-docker
Or clone directly: git clone https://github.com/agno-agi/agentos-docker-template.git
5

Export your API key

export OPENAI_API_KEY=sk-***
Agno works with any model provider. Just update the agents in your codebase.
6

Start your AgentOS

docker compose up -d --build
7

Verify it works

Open http://localhost:8000/docs to see your AgentOS API:
AgentOS FastAPI endpoints
8

Connect your AgentOS to the control plane

  1. Open os.agno.com
  2. Click “Connect OS” and select “Local”
  3. Enter http://localhost:8000
AgentOS connection dialog

​
Tips

Hot reload: Changes to agents, teams, and workflows are reflected automatically. Environment variables: Restart containers when updating environment variables. Common commands:
ag infradocker composeDescription
ag infra updocker compose up -d --buildStart containers
ag infra downdocker compose downStop containers
ag infra restartdocker compose restartRestart containers
docker compose logs -fView logs
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

​
Deploy to Production

You can deploy this template to any cloud that supports Docker. Cloud providers: AWS ECS, Google Cloud Compute Engine, Azure Virtual Machines Platforms: Railway, Render, DigitalOcean, Fly.io, Modal

​
Troubleshooting

Modify compose.yml:
    ports:
      - "8080:8000"  # Change 8000 to 8080
Ensure PostgreSQL is running:
    docker compose ps
If the database isn’t ready, wait a few seconds and try again.