AgentUse: Open-source agent runtime

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/api/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

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic Claude API key
`CLAUDE_CODE_OAUTH_TOKEN`	Long-lived OAuth token from `claude setup-token` (valid 1 year)
`OPENAI_API_KEY`	OpenAI API key
`OPENROUTER_API_KEY`	OpenRouter API key
`OPENCODE_GO_API_KEY`	OpenCode Go API key
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION`	Amazon Bedrock (SigV4 auth)
`AWS_SESSION_TOKEN`	Optional Bedrock session token (temporary credentials)
`AWS_BEARER_TOKEN_BEDROCK`	Amazon Bedrock API key (Bearer auth, alternative to SigV4)

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

Restarts and Worker Memory

agentuse serve runs agents in per-project worker processes, and two behaviours matter when you put it behind pm2, systemd, or a container supervisor. A restart releases workers rather than killing them. Runs already in flight keep going in the released worker and finish normally; only the daemon is replaced. A released worker still has a hard deadline, by default the longest in-flight run’s own timeout plus ten minutes of grace, tunable with AGENTUSE_RELEASE_BACKSTOP_SECONDS. Set AGENTUSE_RELEASE_WORKERS=0 if you want the old kill-on-shutdown behaviour instead. Idle workers are recycled once they get heavy. A fresh worker peaks around 130MB of heap; after it has executed runs, that settles at roughly 350-450MB, which a long-lived daemon would otherwise hold forever. When an idle worker is above AGENTUSE_WORKER_RECYCLE_MB (default 300) it is retired through the same release path, so a replacement starts serving immediately. Recycling only happens while the worker is idle, and never within two minutes of it starting. Set AGENTUSE_WORKER_RECYCLE_MB=0 to disable it. After a crash, settle the stragglers. If the host or the container died outright, sessions can be left marked running with no process behind them. agentuse serve sweeps these at startup, but only back 30 days:

docker exec -it agentuse agentuse sessions reconcile --all --dry-run
docker exec -it agentuse agentuse sessions reconcile --all

Runs that are genuinely still executing are never touched. See CLI Commands.

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/api"]
      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;
    }
}

Rate limiting

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;
}

SSL certificates

certbot --nginx -d agents.example.com

Troubleshooting

Container exits immediately

Check logs with docker logs agentuse. Common causes: missing API keys, port already in use.

Cannot connect to server

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"]

Agent file not found

Check the volume mount with docker exec -it agentuse ls /agents. Ensure API request paths match container paths.

Getting Started

Building

Running

Reference

Self-Hosting

Why Self-Host?

Full Control

Scalable

API Access

Reproducible

Quick Start

Local Development

Configuration

Environment Variables

Using an Environment File

Restarts and Worker Memory

Including Your Agents

Docker Compose

Extending the Base Image

Multi-arch Build

Production Deployment

Reverse Proxy with nginx

Troubleshooting

​Why Self-Host?

Full Control

Scalable

API Access

Reproducible

​Quick Start

​Local Development

​Configuration

​Environment Variables

​Using an Environment File

​Restarts and Worker Memory

​Including Your Agents

​Docker Compose

​Extending the Base Image

​Multi-arch Build

​Production Deployment

​Reverse Proxy with nginx

​Troubleshooting

Why Self-Host?

Quick Start

Local Development

Configuration

Environment Variables

Using an Environment File

Restarts and Worker Memory

Including Your Agents

Docker Compose

Extending the Base Image

Multi-arch Build

Production Deployment

Reverse Proxy with nginx

Troubleshooting