> ## 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`                                    | 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)      |

<Note>
  At least one AI provider authentication is required. For Anthropic, use either `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`.
</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
```

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

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