Docker Deployment

Docker Compose is the recommended way to deploy agtOS in production or when you want Redis and all services running together.

Quick start

git clone https://github.com/agtos-ai/agtos.git
cd agtos
docker compose up -d

This starts three services:

Service	Image	Port	Purpose
agtos	Built from source	3000, 4100, 4102	agtOS server (voice, MCP, API)
redis	`redis/redis-stack:latest`	6379	Memory, scheduling, devices, sessions
speaches	`ghcr.io/speaches-ai/speaches`	8000	STT/TTS fallback server (Faster Whisper + Kokoro)

Configuration

Environment variables

Create a .env.local file in the project root with your API keys:

# Cloud provider API keys (at least one recommended)
ANTHROPIC_API_KEY=sk-ant-api03-your-key
# OPENAI_API_KEY=sk-your-openai-key
# Cloud provider configured per slot in ~/.agtos/config.json
AGTOS_API_KEY=your-secret-api-key

Docker Compose automatically loads .env.local for secrets.

Connecting to host services

When running in Docker, use host.docker.internal to reach services on the host machine:

# Ollama running on host
OLLAMA_HOST=http://host.docker.internal:11434

# speaches on host (if not using the container)
SPEACHES_URL=http://host.docker.internal:8000

On Linux, host.docker.internal may not work out of the box. Use --network=host or add extra_hosts: ["host.docker.internal:host-gateway"] to your compose file.

GPU acceleration

For GPU-accelerated speech processing (STT/TTS), use the GPU override:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

This adds NVIDIA CUDA support to the speaches container. Requires:

NVIDIA GPU with CUDA support
NVIDIA Container Toolkit installed

GPU acceleration provides 4-6x faster STT/TTS inference compared to CPU.

Redis only

If you’re running agtOS via the CLI or desktop app but want Redis for memory and scheduling:

docker compose up -d redis

Or install Redis directly without Docker:

# macOS
brew install redis && brew services start redis

# Ubuntu/Debian
sudo apt install redis-server

The CLI can also install Redis for you: the POST /api/dependencies/install-redis endpoint creates a redis/redis-stack container automatically.

Resource limits

The default Docker Compose configuration sets resource limits:

Service	CPU	Memory
agtos	2 cores	1 GB
redis	1 core	512 MB
speaches	4 cores	4 GB

Adjust these in docker-compose.yml under deploy.resources.limits based on your hardware.

Volumes

Named volumes persist data across container restarts:

Volume	Purpose
`redis-data`	Redis database persistence
`speaches-models`	Cached STT/TTS model files
`node-modules`	npm dependencies

Health checks

The agtOS container includes a built-in health check:

wget -qO- http://localhost:4102/health

Runs every 30 seconds with a 10-second timeout. Docker reports container health status accordingly. The speaches container health check verifies model loading:

curl -f http://localhost:8000/v1/models

Production tips

Set NODE_ENV=production for structured JSON logging and credential salt enforcement
Set AGTOS_API_KEY to protect API endpoints
Set AGTOS_CREDENTIAL_SALT for persistent encrypted credential storage
Use restart: unless-stopped (already configured) for automatic recovery
Mount .env.local as env_file for secrets management
Use a reverse proxy (nginx, Caddy) for TLS termination if exposing externally

See Security for the full production checklist.

​Quick start

​Configuration

​Environment variables

​Connecting to host services

​GPU acceleration

​Redis only

​Resource limits

​Volumes

​Health checks

​Production tips

Quick start

Configuration

Environment variables

Connecting to host services

GPU acceleration

Redis only

Resource limits

Volumes

Health checks

Production tips