Skip to content

ENVIRONMENT_VARIABLES.md

Latest commit

 

History

History
135 lines (91 loc) · 8.22 KB

ENVIRONMENT_VARIABLES.md

File metadata and controls

135 lines (91 loc) · 8.22 KB
Raw

Environment Variables

This repo supports running AgentField in multiple modes (local binary, Docker, Kubernetes). Most configuration is loaded via a YAML config file and can be overridden via environment variables.

AgentField uses Viper with the prefix AGENTFIELD and maps nested config keys using _ (for example storage.mode → AGENTFIELD_STORAGE_MODE).

Control Plane (Server)

Core

  • AGENTFIELD_PORT (optional): HTTP port for the control plane (default: 8080).
  • AGENTFIELD_CONFIG_FILE (optional): Path to agentfield.yaml (in containers this is typically /etc/agentfield/config/agentfield.yaml).
  • AGENTFIELD_HOME (recommended in containers): Base directory where AgentField stores local state (SQLite DB, Bolt DB, keys, logs). In Kubernetes, mount a PVC and set AGENTFIELD_HOME=/data.

Storage

AgentField supports:

  • local (SQLite + BoltDB, stored under AGENTFIELD_HOME)
  • postgres (PostgreSQL + pgvector)

Common:

  • AGENTFIELD_STORAGE_MODE: local (default) or postgres.

Local storage (usually not needed if AGENTFIELD_HOME is set):

  • AGENTFIELD_STORAGE_LOCAL_DATABASE_PATH: SQLite path.
  • AGENTFIELD_STORAGE_LOCAL_KV_STORE_PATH: BoltDB path.

PostgreSQL storage:

  • AGENTFIELD_POSTGRES_URL (preferred) or AGENTFIELD_STORAGE_POSTGRES_URL: PostgreSQL DSN/URL (examples below).
  • Alternatively, individual fields:
    • AGENTFIELD_STORAGE_POSTGRES_HOST
    • AGENTFIELD_STORAGE_POSTGRES_PORT
    • AGENTFIELD_STORAGE_POSTGRES_DATABASE
    • AGENTFIELD_STORAGE_POSTGRES_USER
    • AGENTFIELD_STORAGE_POSTGRES_PASSWORD
    • AGENTFIELD_STORAGE_POSTGRES_SSLMODE

Example DSNs:

  • postgres://agentfield:agentfield@postgres:5432/agentfield?sslmode=disable
  • postgresql://agentfield:agentfield@postgres:5432/agentfield?sslmode=disable

API Authentication (optional)

If set, the control plane requires an API key for most endpoints.

  • AGENTFIELD_API_KEY or AGENTFIELD_API_AUTH_API_KEY: API key checked by the control plane.

UI

  • AGENTFIELD_UI_ENABLED (default: true)
  • AGENTFIELD_UI_MODE (default: embedded)

Anonymous Telemetry

Anonymous usage telemetry is enabled by default to help us improve AgentField. It records coarse product signals such as startup, agent registration, SDK language, runtime type, storage mode, and execution status buckets. Events use a pseudonymous, installation-scoped identifier; it represents an AgentField installation, not a person or account.

The telemetry payload does not include prompts, inputs, outputs, logs, secrets, API keys, IP addresses, hostnames, user IDs, DIDs, or raw error text. Sending is best-effort and does not affect control-plane or execution behavior.

  • AGENTFIELD_TELEMETRY_ENABLED (default: true): Set to false to disable anonymous usage telemetry.
  • AGENTFIELD_TELEMETRY_ENDPOINT (default: https://agentfield.ai/api/oss/telemetry): Hosted anonymous telemetry endpoint.
  • AGENTFIELD_TELEMETRY_INSTALL_ID (optional): Stable externally managed installation ID. Use a random, opaque value—not an email, account name, hostname, or other identifying value. The control plane hashes it before sending.
  • AGENTFIELD_TELEMETRY_INSTALL_ID_PATH (optional): Path for the persisted local install ID.
  • AGENTFIELD_TELEMETRY_TIMEOUT (default: 800ms): Per-event send timeout. Failures are ignored.

CORS (HTTP API)

These map to api.cors.* in config. When set via env, use comma-separated values.

  • AGENTFIELD_API_CORS_ALLOWED_ORIGINS (comma-separated)
  • AGENTFIELD_API_CORS_ALLOWED_METHODS (comma-separated)
  • AGENTFIELD_API_CORS_ALLOWED_HEADERS (comma-separated): Include X-Admin-Token when browser clients access admin or /debug/pprof/* endpoints.
  • AGENTFIELD_API_CORS_EXPOSED_HEADERS (comma-separated)
  • AGENTFIELD_API_CORS_ALLOW_CREDENTIALS (true/false)

Authorization (VC-Based Permissions)

When enabled, the control plane issues DID identities to agents and enforces tag-based access policies on agent-to-agent calls.

  • AGENTFIELD_AUTHORIZATION_ENABLED (default: false): Enable VC-based authorization.
  • AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN (recommended): Separate token for admin operations and /debug/pprof/*; clients send it in X-Admin-Token. Without it, those endpoints rely on the global API key, so do not expose pprof outside trusted networks unless authentication is configured.
  • AGENTFIELD_AUTHORIZATION_MASTER_SEED (required when enabled): Master seed for deriving Ed25519 keypairs for agent DIDs. Keep this secret and consistent across restarts — changing it invalidates all existing DID signatures.
  • AGENTFIELD_AUTHORIZATION_TAG_APPROVAL_MODE (default: auto): auto (tags approved immediately) or admin (tags require admin approval before the agent becomes ready).
  • AGENTFIELD_AUTHORIZATION_DEFAULT_DENY (default: false): When true, the tag policy middleware returns HTTP 403 for any request where no access policy matches the (caller_tags, target_tags, function) tuple. Default is false, preserving the existing behavior of allowing unmatched requests. The unmatched tuple is logged at DEBUG in both modes for diagnosis. Equivalent YAML: features.did.authorization.default_deny.

Connector (External Management API)

The connector API provides token-authenticated management endpoints for external systems (CI/CD, orchestration platforms, dashboards).

  • AGENTFIELD_CONNECTOR_TOKEN (optional): Bearer token required for all /connector/* endpoints.
  • AGENTFIELD_CONNECTOR_CAPABILITIES (optional, default: all): Comma-separated list of granted capabilities. Available capabilities: reasoners:read, reasoners:write, versions:read, versions:write, restart.

Example:

AGENTFIELD_CONNECTOR_TOKEN=my-secret-token
AGENTFIELD_CONNECTOR_CAPABILITIES=reasoners:read,versions:read,versions:write,restart

Agent Nodes

Agent nodes run as separate processes/pods and register with the control plane. The most important Kubernetes-specific concept is:

  • The control plane must be able to reach the agent at the URL the agent registers (its callback/public URL).
  • In Kubernetes, this should usually be a Service DNS name (for example http://my-agent.default.svc.cluster.local:8001).

The same concept applies to Docker:

  • If the control plane runs in a container and the agent runs on your host, set the agent’s callback/public URL to host.docker.internal (or the Docker host gateway on Linux).
  • If both run in the same Docker network/Compose project, set the callback/public URL to the agent service name (for example http://demo-go-agent:8001).

Go SDK agents (example: examples/go_agent_nodes)

  • AGENTFIELD_URL (optional): Control plane base URL (example: http://agentfield:8080).
  • AGENTFIELD_TOKEN (optional): Bearer token (use this if you enable AGENTFIELD_API_KEY on the control plane).
  • AGENT_NODE_ID (optional): Node id (default varies by example).
  • AGENT_LISTEN_ADDR (optional): Listen address (default: :8001).
  • AGENT_PUBLIC_URL (recommended in Docker/Kubernetes): Public URL the control plane will call back to (example: http://my-agent:8001).

Python SDK agents

  • AGENTFIELD_URL (recommended): Control plane base URL.
  • AGENT_NODE_ID (optional): Node id.
  • AGENT_CALLBACK_URL (recommended in Docker/Kubernetes): URL the control plane will call back to (examples: http://my-agent:8001, or for host-run agents with Dockerized control plane: http://host.docker.internal:8001).

Many Python examples also require model provider credentials (for example OPENAI_API_KEY), depending on the AIConfig you choose.

OpenRouter attribution

OpenRouter attribution is request metadata, not authentication. AgentField SDKs send these as HTTP-Referer, X-OpenRouter-Title, and X-Title for OpenRouter requests.

  • AGENTFIELD_OPENROUTER_SITE_URL (default: https://agentfield.ai)
  • AGENTFIELD_OPENROUTER_APP_NAME (default: AgentField AI)
  • OR_SITE_URL, OR_APP_NAME: LiteLLM-compatible attribution env vars.
  • AGENTFIELD_OPENROUTER_ATTRIBUTION=false: Disable OpenRouter attribution headers/env propagation.

Explicit SDK config or explicit request headers win over env defaults. AGENTFIELD_API_KEY, SDK api_key / apiKey, Go WithAPIKey, and the X-API-Key header are only for AgentField control-plane authentication and are not used for OpenRouter attribution.