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
• An API key from a model provider

Step-by-step Guide

1. Install tools

   • Install Docker Desktop
   • Install uv (Python package manager)
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:

   
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

   

   Your AgentOS is deployed in a docker container and is accessible at http://localhost:8000.

Tips

Cloud Deployment

You can also 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

Hot reload

Changes to agents, teams, and workflows are reflected automatically.

Environment variables

Restart containers when updating environment variables.

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

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

Troubleshooting

Port already in use

Modify compose.yml: yaml ports: - "8080:8000" # Change 8000 to 8080

Database connection issues

Ensure PostgreSQL is running: bash docker compose ps If the database isn’t ready, wait a few seconds and try again.