> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-runtime-token-header.mintlify.site/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.
</Note>

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