Skip to main content

​
Aion Control Plane Settings

These settings control optional integration with the Aion control plane. When they are not provided, aion serve can still start local agent and proxy processes, and you can invoke agents directly through the local A2A and proxy endpoints. Without them, the SDK cannot authenticate with or use the Aion control plane. For deployments hosted by Aion, the control plane provides these values automatically. Set them yourself only when running outside Aion-hosted deployments or when testing local control plane connectivity.
VariableTypeRequiredDefault
AION_CLIENT_IDstringNounset
Client ID used with AION_CLIENT_SECRET for control plane authentication. For Aion-hosted deployments this is populated by the Aion control plane. Set it manually only for self-managed deployments or local testing against the control plane.
AION_CLIENT_SECRETstringNounset
Secret paired with AION_CLIENT_ID for control plane authentication. For Aion-hosted deployments this is populated by the Aion control plane. Set it manually only for self-managed deployments or local testing against the control plane.
AION_API_HOSTstringNohttps://api.aion.to
Base URL for Aion control plane HTTP and WebSocket calls. Must start with http:// or https://; invalid values fail settings validation during startup.
AION_API_KEEP_ALIVEintegerNo60
Keep-alive interval exposed by SDK settings for control plane connections. If unset, the SDK uses the default value.

​
Storage Settings

VariableTypeRequiredDefault
POSTGRES_URLstringNounset
PostgreSQL DSN for persistence and DB-backed features. If unset, the SDK falls back to in-memory storage where supported. If set but unreachable, database initialization logs connection or migration errors and durable storage features remain unavailable.
This database is used for A2A task history and other durable runtime data. Framework adapters can also use it for framework-specific persistence, such as LangGraph execution state and checkpoint data when PostgreSQL-backed checkpointing is enabled.
FILE_STORAGE_BACKENDstringNounset
Optional backend for converting inline file parts into URI-based file references. When unset, file content is left inline. The only supported value today is stub, which is intended for development and test flows. Unknown values fail startup when file upload handling is initialized.
This is used by the ADK artifact service when inline artifact data should be uploaded and stored as URI references, and by A2A file parts that carry inline file bytes instead of URLs.

​
Logging Settings

VariableTypeRequiredDefault
LOG_LEVELstringNoINFO
Allowed: DEBUG, INFO, WARNING, ERROR. Invalid values fail settings validation.
LOGSTASH_HOSTstringNounset
Host for centralized log shipping. Must be set together with LOGSTASH_PORT; otherwise remote log shipping remains disabled and logs stay on local stream handlers. For Aion-hosted deployments, the control plane populates this automatically.
LOGSTASH_PORTintegerNounset
Port for centralized log shipping. Must be set together with LOGSTASH_HOST; otherwise remote log shipping remains disabled. For Aion-hosted deployments, the control plane populates this automatically.
NODE_NAMEstringNounset
Optional deployment node identifier used primarily in log metadata. For Aion-hosted deployments, the control plane populates this automatically. If unset, local logging still works normally.
VERSION_IDstringNounset
Optional deployment version identifier used primarily in log and deployment metadata. For Aion-hosted deployments, the control plane populates this automatically. If set, the SDK uses this value directly. If unset, aion serve attempts to fetch it from the control plane; on failure it logs a warning and continues without a version ID.

​
Miscellaneous Settings

VariableTypeRequiredDefault
AION_DOCS_URLstringNohttps://docs.aion.to/
Base documentation URL used when the SDK builds agent-card extension links. If unset, the default docs URL is used.

​
Loading Behavior

  • Variables can be provided through the system environment or a .env file in the project root.
  • If the same variable is set in both places, the system environment value wins.
  • Variable names are case-insensitive in settings parsing.
  • Missing optional variables use defaults or remain unset.
  • Variables with explicit format or allowed-value constraints fail validation when set to invalid values.

​
Example .env

# Optional: Aion control plane integration
# For Aion-hosted deployments, these are provided by the control plane.
# Set them yourself only for self-managed deployments or local testing.
AION_CLIENT_ID=your_client_id
AION_CLIENT_SECRET=your_client_secret
AION_API_HOST=https://api.aion.to
AION_API_KEEP_ALIVE=60

# Optional: storage
POSTGRES_URL=postgresql://user:password@localhost:5432/aion_db
AION_FILE_STORAGE_BACKEND=stub

# Optional: logging
LOG_LEVEL=INFO