Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agtos.ai/llms.txt

Use this file to discover all available pages before exploring further.

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:
ServiceImagePortPurpose
agtosBuilt from source3000, 4100, 4102agtOS server (voice, MCP, API)
redisredis/redis-stack:latest6379Memory, scheduling, devices, sessions
speachesghcr.io/speaches-ai/speaches8000STT/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: 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:
ServiceCPUMemory
agtos2 cores1 GB
redis1 core512 MB
speaches4 cores4 GB
Adjust these in docker-compose.yml under deploy.resources.limits based on your hardware.

​
Volumes

Named volumes persist data across container restarts:
VolumePurpose
redis-dataRedis database persistence
speaches-modelsCached STT/TTS model files
node-modulesnpm 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.