Control plane configuration using environment variables, config files, and CLI flags

The AgentField control plane can be configured in three ways, with environment variables taking the highest priority.

Configuration Precedence

AgentField follows this configuration order (highest to lowest priority):

Environment variables - Override everything (e.g., AGENTFIELD_PORT=8080)
Config file - YAML configuration file (agentfield.yaml)
CLI flags - Command-line arguments (e.g., --port 8080)
Defaults - Built-in fallback values

Best Practice

Use environment variables for deployment-specific settings (database URLs, ports) and config files for application logic (agent definitions, workflows). This makes your deployments portable across environments.

Configuration File

Location

The control plane looks for agentfield.yaml in these locations (in order):

Path specified in AGENTFIELD_CONFIG_FILE environment variable
./config/agentfield.yaml (current directory)
~/.agentfield/config.yaml (home directory)

Example: Custom Config Path

AGENTFIELD_CONFIG_FILE=/etc/agentfield/production.yaml af server

Basic Structure

# agentfield.yaml
server:
  port: 8080
  mode: cloud

storage:
  mode: postgres
  postgres:
    host: db.example.com
    port: 5432
    database: agentfield
    user: agentfield
    password: ${POSTGRES_PASSWORD}  # Reference env vars
    sslmode: require
    max_connections: 100

ui:
  enabled: true

api:
  cors:
    allowed_origins:
      - https://app.example.com
      - https://admin.example.com

Secrets in Config Files

Avoid hardcoding secrets in agentfield.yaml. Instead, reference environment variables using ${VAR_NAME} syntax:

storage:
  postgres:
    password: ${POSTGRES_PASSWORD}

This keeps secrets in your environment or secrets manager, not in version control.

Essential Control Plane Settings

Server Configuration

Variable	Type	Default	Description
`AGENTFIELD_PORT`	integer	`8080`	HTTP server port
`AGENTFIELD_MODE`	string	`local`	Deployment mode: `local` or `cloud`
`AGENTFIELD_HOME`	string	`~/.agentfield`	Home directory for data and config

CLI Flags:

af server --port 8080 --mode cloud

Environment Variables:

AGENTFIELD_PORT=8080
AGENTFIELD_MODE=cloud
af server

Config File:

server:
  port: 8080
  mode: cloud

Storage Configuration

AgentField supports two storage backends for development and production use.

Storage Modes Comparison

Feature	Local (SQLite)	PostgreSQL
Use Case	Development, single machine	Production, distributed systems
Database	SQLite (file-based)	PostgreSQL 12+
Key-Value Store	BoltDB (file-based)	PostgreSQL tables
Concurrent Access	❌ Single process only	✅ Multiple control plane instances
High Availability	❌ No	✅ Yes (with PostgreSQL HA)
Backup	File copy	PostgreSQL backups
Performance	Fast for single node	Scales with PostgreSQL

Production Requirement

Always use postgres storage mode in production. Local storage is file-based and doesn't support concurrent access or high availability.

Local Storage (Development)

Environment Variables:

AGENTFIELD_STORAGE_MODE=local
AGENTFIELD_STORAGE_LOCAL_DATABASE_PATH=./agentfield_local.db
AGENTFIELD_STORAGE_LOCAL_KV_STORE_PATH=./agentfield_local.bolt

CLI Flags:

af server --storage-mode local

Config File:

storage:
  mode: local
  local:
    database_path: ./agentfield_local.db
    kv_store_path: ./agentfield_local.bolt

PostgreSQL (Production)

Using Full Connection String:

AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_DATABASE_URL="postgres://user:pass@db.example.com:5432/agentfield?sslmode=require"

Using Individual Components:

AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_STORAGE_POSTGRES_HOST=db.example.com
AGENTFIELD_STORAGE_POSTGRES_PORT=5432
AGENTFIELD_STORAGE_POSTGRES_DATABASE=agentfield
AGENTFIELD_STORAGE_POSTGRES_USER=agentfield
AGENTFIELD_STORAGE_POSTGRES_PASSWORD=secure_password
AGENTFIELD_STORAGE_POSTGRES_SSLMODE=require

Format:

postgres://[user]:[password]@[host]:[port]/[database]?sslmode=[mode]

SSL Modes:

disable - No SSL (only for development)
require - SSL required, no certificate verification
verify-ca - Verify server certificate against CA
verify-full - Full certificate verification (most secure)

Aliases: These environment variables all work the same way:

AGENTFIELD_DATABASE_URL (recommended)
AGENTFIELD_POSTGRES_URL
AGENTFIELD_STORAGE_POSTGRES_URL

storage:
  mode: postgres
  postgres:
    host: db.example.com
    port: 5432
    database: agentfield
    user: agentfield
    password: ${POSTGRES_PASSWORD}  # From environment
    sslmode: require
    max_connections: 100
    max_idle_connections: 25
    connection_timeout: 30s
    query_timeout: 30s

CLI Flags:

af server --storage-mode postgres --postgres-url "postgres://user:pass@host:5432/db"

PostgreSQL Performance Tuning

Connection Pool Settings

Variable	Default	Recommendation
`AGENTFIELD_STORAGE_POSTGRES_MAX_CONNECTIONS`	`25`	Low traffic: 25 Medium traffic (10-50 agents): 50-100 High traffic (100+ agents): 100-200
`AGENTFIELD_STORAGE_POSTGRES_MAX_IDLE_CONNECTIONS`	`5`	Set to 20-25% of max connections
`AGENTFIELD_STORAGE_POSTGRES_CONNECTION_TIMEOUT`	`30s`	Increase to `60s` for slow networks
`AGENTFIELD_STORAGE_POSTGRES_QUERY_TIMEOUT`	`30s`	Increase to `60s` for complex queries

Example: High-Traffic Production Setup

AGENTFIELD_STORAGE_POSTGRES_MAX_CONNECTIONS=100
AGENTFIELD_STORAGE_POSTGRES_MAX_IDLE_CONNECTIONS=25
AGENTFIELD_STORAGE_POSTGRES_CONNECTION_TIMEOUT=60s
AGENTFIELD_STORAGE_POSTGRES_QUERY_TIMEOUT=60s

PostgreSQL Server Tuning

Ensure your PostgreSQL server's max_connections setting is higher than the sum of all control plane instances' MAX_CONNECTIONS values.

Example: If running 3 control plane instances with 100 connections each, set PostgreSQL:

-- postgresql.conf
max_connections = 350  # 3 × 100 + 50 buffer

Web UI Configuration

Control the built-in AgentField dashboard.

Enable/Disable UI

Environment Variable:

AGENTFIELD_UI_ENABLED=false  # Disable UI for API-only deployment

Config File:

ui:
  enabled: false

Use Cases for Disabling UI:

Headless API-only deployments
Custom frontend applications
Security-hardened environments
Reduced resource usage

Custom UI Path

If you've built a custom UI or want to serve from a different location:

AGENTFIELD_UI_DIST_PATH=/var/www/agentfield-ui

API & CORS Configuration

Configure Cross-Origin Resource Sharing (CORS) for frontend applications.

CORS Settings

Variable	Default	Description
`AGENTFIELD_API_CORS_ALLOWED_ORIGINS`	`http://localhost:3000,http://localhost:5173,http://localhost:8080`	Allowed origins (comma-separated)
`AGENTFIELD_API_CORS_ALLOWED_METHODS`	`GET,POST,PUT,DELETE,OPTIONS`	Allowed HTTP methods
`AGENTFIELD_API_CORS_ALLOWED_HEADERS`	`Origin,Content-Type,Accept,Authorization,X-Requested-With`	Allowed headers
`AGENTFIELD_API_CORS_ALLOW_CREDENTIALS`	`true`	Allow cookies and credentials

Production Example:

AGENTFIELD_API_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
AGENTFIELD_API_CORS_ALLOW_CREDENTIALS=true

Config File:

api:
  cors:
    allowed_origins:
      - https://app.example.com
      - https://admin.example.com
    allowed_methods:
      - GET
      - POST
      - PUT
      - DELETE
      - OPTIONS
    allow_credentials: true

Security: Restrict Origins in Production

The default CORS configuration allows localhost origins for development. In production, always restrict allowed_origins to your actual frontend domains.

Insecure (don't do this):

AGENTFIELD_API_CORS_ALLOWED_ORIGINS=*  # Allows any origin

Secure:

AGENTFIELD_API_CORS_ALLOWED_ORIGINS=https://app.example.com

Complete Configuration Example

Development Setup

# agentfield.yaml (development)
server:
  port: 8080
  mode: local

storage:
  mode: local
  local:
    database_path: ./dev_data.db
    kv_store_path: ./dev_kv.bolt

ui:
  enabled: true

api:
  cors:
    allowed_origins:
      - http://localhost:3000
      - http://localhost:5173

# .env (development)
AGENTFIELD_LOG_LEVEL=debug

Production Setup

# agentfield.yaml (production)
server:
  port: 8080
  mode: cloud

storage:
  mode: postgres
  postgres:
    host: ${POSTGRES_HOST}
    port: 5432
    database: agentfield
    user: agentfield
    password: ${POSTGRES_PASSWORD}
    sslmode: verify-full
    max_connections: 100
    max_idle_connections: 25

ui:
  enabled: true

api:
  cors:
    allowed_origins:
      - https://app.example.com
      - https://admin.example.com
    allow_credentials: true

# .env (production)
POSTGRES_HOST=db-prod.example.com
POSTGRES_PASSWORD=<from-secrets-manager>
AGENTFIELD_API_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

Configuration Validation

Check Current Configuration

# View effective configuration (resolves precedence)
af server --config /path/to/agentfield.yaml --dry-run

Common Issues

Environment Variables Not Working?

Problem: Environment variables seem to be ignored.

Solution: Check precedence order. Config file values override CLI flags but are overridden by environment variables.

Debug:

# Verify environment variables are set
env | grep AGENTFIELD

# Check which config file is being used
af server --debug

PostgreSQL Connection Failed?

Problem: failed to connect to postgres: dial tcp: lookup failed

Solution: Verify connection string format and network access:

# Test connection manually
psql "postgres://user:pass@host:5432/db?sslmode=require"

# Check SSL mode - try 'disable' for local development
AGENTFIELD_STORAGE_POSTGRES_SSLMODE=disable

Environment Variables Reference - Complete list of all environment variables
af server Command - Control plane CLI reference
Docker Deployment - Container-specific configuration
Production Best Practices - Production deployment patterns
Python SDK Configuration - Agent configuration