> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting

> Run AgentUse in Docker for local development or production deployment

## Why Self-Host?

<CardGroup cols={2}>
  <Card title="Full Control" icon="sliders">
    Host on your infrastructure. Your data and API keys never leave your network.
  </Card>

  <Card title="Scalable" icon="arrow-up-right-dots">
    Deploy multiple instances behind a load balancer as demand grows.
  </Card>

  <Card title="API Access" icon="webhook">
    Expose agents via HTTP API for integration with other services.
  </Card>

  <Card title="Reproducible" icon="copy">
    Same container runs identically across machines. Share your setup with teammates.
  </Card>
</CardGroup>

## Quick Start

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
docker exec -it agentuse-dev agentuse run my-agent.agentuse
```

<Tip>
  Add `alias agentuse-docker='docker exec -it agentuse-dev agentuse'` to your shell profile for convenience.
</Tip>

<Warning>
  OAuth tokens may expire. If you encounter auth errors, run `agentuse auth login` on your host to refresh.
</Warning>

## Configuration

### Environment Variables

| Variable | Description |
| - | - |
| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
| `CLAUDE_CODE_OAUTH_TOKEN` | Claude subscription OAuth token; requires the Claude Code subscription provider plugin |
| `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) |

<Note>
  At least one AI provider authentication is required. `ANTHROPIC_API_KEY` works with the built-in provider. `CLAUDE_CODE_OAUTH_TOKEN` works only when the Claude Code subscription provider plugin is installed in the container or mounted project scope.
</Note>

### Using an Environment File

```bash theme={"system"}
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:

```bash theme={"system"}
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](/reference/cli-commands#reconcile-stuck-sessions).

## Including Your Agents

**Volume mount** (best for development):

```bash theme={"system"}
-v $(pwd)/agents:/agents
```

**Bake into image** (best for production):

```dockerfile theme={"system"}
FROM ghcr.io/agentuse/agentuse:latest
COPY ./agents /agents
```

## Docker Compose

```yaml theme={"system"}
# 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

```dockerfile theme={"system"}
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

```bash theme={"system"}
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myregistry/agentuse:latest \
  --push .
```

## Production Deployment

### Reverse Proxy with nginx

```nginx theme={"system"}
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;
    }
}
```

Start serve with `--public-url https://agents.example.com` (or set `serve.publicUrl`) so approval links use the public address and a keyless daemon accepts requests for that host.

<AccordionGroup>
  <Accordion title="Rate limiting">
    ```nginx theme={"system"}
    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;
    }
    ```
  </Accordion>

  <Accordion title="SSL certificates">
    ```bash theme={"system"}
    certbot --nginx -d agents.example.com
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Container exits immediately">
    Check logs with `docker logs agentuse`. Common causes: missing API keys, port already in use.
  </Accordion>

  <Accordion title="Cannot connect to server">
    The official image binds to `0.0.0.0` by default. If using a custom image, ensure:

    ```dockerfile theme={"system"}
    ENTRYPOINT ["/usr/local/bin/agentuse", "serve", "-H", "0.0.0.0"]
    ```
  </Accordion>

  <Accordion title="Agent file not found">
    Check the volume mount with `docker exec -it agentuse ls /agents`. Ensure API request paths match container paths.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.