Skip to main content

​
Why Self-Host?

Full Control

Host on your infrastructure. Your data and API keys never leave your network.

Scalable

Deploy multiple instances behind a load balancer as demand grows.

API Access

Expose agents via HTTP API for integration with other services.

Reproducible

Same container runs identically across machines. Share your setup with teammates.

​
Quick Start

docker run -d --name agentuse \
  -p 12233:12233 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd)/agents:/agents \
  ghcr.io/agentuse/agentuse:latest
Test it: 
curl http://localhost:12233/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "/agents/hello.agentuse"}'

​
Local Development

For local development, mount your credentials and workspace instead of using environment variables: 
docker run -d --name agentuse-dev \
  -p 12233:12233 \
  -v ~/.local/share/agentuse:/root/.local/share/agentuse \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/agentuse/agentuse:latest
This gives the container access to your OAuth tokens, API keys, and session logs from agentuse auth login. Run agents via exec: 
docker exec -it agentuse-dev agentuse run my-agent.agentuse
Add alias agentuse-docker='docker exec -it agentuse-dev agentuse' to your shell profile for convenience.
OAuth tokens may expire. If you encounter auth errors, run agentuse auth login on your host to refresh.

​
Configuration

​
Environment Variables

VariableDescription
ANTHROPIC_API_KEYAnthropic Claude API key
CLAUDE_CODE_OAUTH_TOKENLong-lived OAuth token from claude setup-token (valid 1 year)
OPENAI_API_KEYOpenAI API key
OPENROUTER_API_KEYOpenRouter API key
At least one AI provider authentication is required. For Anthropic, use either ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN.

​
Using an Environment File

docker run -d -p 12233:12233 --env-file .env \
  -v $(pwd)/agents:/agents \
  ghcr.io/agentuse/agentuse:latest

​
Including Your Agents

Volume mount (best for development): 
-v $(pwd)/agents:/agents
Bake into image (best for production): 
FROM ghcr.io/agentuse/agentuse:latest
COPY ./agents /agents

​
Docker Compose

# docker-compose.yml
version: '3.8'
services:
  agentuse:
    image: ghcr.io/agentuse/agentuse:latest
    ports:
      - "12233:12233"
    environment:
      - ANTHROPIC_API_KEY
      - OPENAI_API_KEY
    volumes:
      - ./agents:/agents
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:12233/run"]
      interval: 30s
      timeout: 10s
      retries: 3

​
Extending the Base Image

FROM ghcr.io/agentuse/agentuse:latest

RUN apk add --no-cache ffmpeg imagemagick
RUN pip3 install --no-cache-dir pandas numpy requests
RUN npm install -g typescript puppeteer

COPY ./agents /agents

​
Multi-arch Build

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myregistry/agentuse:latest \
  --push .

​
Production Deployment

​
Reverse Proxy with nginx

server {
    listen 443 ssl;
    server_name agents.example.com;

    location / {
        proxy_pass http://127.0.0.1:12233;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location / {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://127.0.0.1:12233;
}

certbot --nginx -d agents.example.com

​
Troubleshooting

Check logs with docker logs agentuse. Common causes: missing API keys, port already in use.
The official image binds to 0.0.0.0 by default. If using a custom image, ensure:
ENTRYPOINT ["/usr/local/bin/agentuse", "serve", "-H", "0.0.0.0"]
Check the volume mount with docker exec -it agentuse ls /agents. Ensure API request paths match container paths.