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

# Configuration

> Environment variables, server settings, authentication, and database setup.

## SDK Environment Variables

| Variable | Default | Description |
| - | - | - |
| `AGENT_CONTROL_URL` | `http://localhost:8000` | Server URL |
| `AGENT_CONTROL_API_KEY` | — | API key for authentication |
| `AGENT_CONTROL_RUNTIME_TOKEN_HEADER` | `Authorization` | Header used to send runtime tokens. Must match the server setting. |

For server database configuration, use the `AGENT_CONTROL_DB_*` variables in the server section below.

***

## Server Environment Variables

### Core Settings

| Variable | Default | Description |
| - | - | - |
| `HOST` | `0.0.0.0` | Server bind address |
| `PORT` | `8000` | Server port |
| `DEBUG` | `false` | Enable debug mode |
| `API_VERSION` | `v1` | API version prefix |
| `API_PREFIX` | `/api` | API path prefix |

### Runtime Token

| Variable | Default | Description |
| - | - | - |
| `AGENT_CONTROL_RUNTIME_TOKEN_HEADER` | `Authorization` | Header from which the server reads runtime tokens. Must match the SDK setting. |

By default, the SDK sends the runtime token in the `Authorization` header as `Authorization: Bearer <runtime-token>`.

If a gateway reserves `Authorization` for its own identity credential, configure the server and SDK to use a dedicated header:

```bash theme={null}
export AGENT_CONTROL_RUNTIME_TOKEN_HEADER="X-Agent-Control-Runtime-Token"
```

With this setting, Agent Control SDK 8.5.0 or later sends the runtime token in `X-Agent-Control-Runtime-Token` as a raw token without a `Bearer` prefix. `Authorization` remains available for gateway authentication.

You can alternatively set the header when initializing the SDK:

```python theme={null}
agent_control.init(
    agent_name="my-agent",
    runtime_token_header="X-Agent-Control-Runtime-Token",
)
```

If `runtime_token_header` is not provided, the SDK uses `AGENT_CONTROL_RUNTIME_TOKEN_HEADER`. If neither is configured, it defaults to `Authorization`.

> [!NOTE]
>
> Upgrading to version 8.5.0 or later does not change the default header. A dedicated header is used only after you configure the environment variable or the SDK option.

### CORS

| Variable | Default | Description |
| - | - | - |
| `CORS_ORIGINS` | `*` | Allowed origins (comma-separated) |
| `ALLOW_METHODS` | `*` | Allowed HTTP methods |
| `ALLOW_HEADERS` | `*` | Allowed headers |

### Database

| Variable | Default | Description |
| - | - | - |
| `AGENT_CONTROL_DB_URL` | — | Preferred database URL. Supports PostgreSQL and SQLite (for example `sqlite+aiosqlite:///./agent_control.db`). |
| `AGENT_CONTROL_DB_HOST` | `localhost` | PostgreSQL host when `AGENT_CONTROL_DB_URL` is unset |
| `AGENT_CONTROL_DB_PORT` | `5432` | PostgreSQL port when `AGENT_CONTROL_DB_URL` is unset |
| `AGENT_CONTROL_DB_USER` | `agent_control` | Database user when `AGENT_CONTROL_DB_URL` is unset |
| `AGENT_CONTROL_DB_PASSWORD` | `agent_control` | Database password when `AGENT_CONTROL_DB_URL` is unset |
| `AGENT_CONTROL_DB_DATABASE` | `agent_control` | Database name when `AGENT_CONTROL_DB_URL` is unset |
| `AGENT_CONTROL_DB_DRIVER` | `psycopg` | Database driver when `AGENT_CONTROL_DB_URL` is unset |

### Observability

| Variable | Default | Description |
| - | - | - |
| `OBSERVABILITY_ENABLED` | `true` | Enable observability pipeline |
| `OBSERVABILITY_FLUSH_INTERVAL_SECONDS` | `10` | Flush interval for observability events |

### Evaluators

| Variable | Default | Description |
| - | - | - |
| `GALILEO_API_KEY` | — | API key for Luna-2 evaluator |
| `PROMETHEUS_METRICS_PREFIX` | `agent_control_server` | Metrics prefix for Prometheus exports |

***

## Authentication

Agent Control supports API key authentication for production deployments.

### Configuration

| Variable | Default | Description |
| - | - | - |
| `AGENT_CONTROL_API_KEY_ENABLED` | `false` | Master toggle for authentication |
| `AGENT_CONTROL_API_KEYS` | — | Comma-separated list of valid API keys |
| `AGENT_CONTROL_ADMIN_API_KEYS` | — | Comma-separated list of admin API keys |

### Usage

Include the API key in the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/agents
```

With the Python SDK:

```python theme={null}
from agent_control import AgentControlClient

# Via constructor

async with AgentControlClient(api_key="your-api-key") as client:
    await client.health_check()

# Or via environment variable

# export AGENT_CONTROL_API_KEY="your-api-key"

async with AgentControlClient() as client:
    await client.health_check()
```

### Access Levels

| Endpoint | Required Level |
| - | - |
| `/health` | Public (no auth) |
| All `/api/v1/*` | API key required |

### Key Rotation

Agent Control supports multiple API keys for zero-downtime rotation:

1. Add new key to `AGENT_CONTROL_API_KEYS` (e.g., `key1,key2,new-key`)
2. Deploy the server
3. Update clients to use the new key
4. Remove the old key from the variable
5. Redeploy

***

## UI Environment Variables

| Variable | Default | Description |
| - | - | - |
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | Backend API URL |

***

## Database Setup

Agent Control uses PostgreSQL. The easiest way to run it locally:

```bash theme={null}
cd server
docker compose up -d          # Start PostgreSQL
make alembic-upgrade          # Run migrations
```

Default credentials in docker-compose:

* **User:** `agent_control`
* **Password:** `agent_control`
* **Database:** `agent_control`
* **Port:** `5432`


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