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:

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:

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.

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:

curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/agents

With the Python SDK:

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:

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