Documentation Index
Fetch the complete documentation index at: https://docs.aion.to/llms.txt
Use this file to discover all available pages before exploring further.
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.
| Variable | Type | Required | Default |
|---|
AION_CLIENT_ID | string | No | unset |
| 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_SECRET | string | No | unset |
| 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_HOST | string | No | https://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_ALIVE | integer | No | 60 |
| Keep-alive interval exposed by SDK settings for control plane
connections. If unset, the SDK uses the default value. |
Storage Settings
| Variable | Type | Required | Default |
|---|
POSTGRES_URL | string | No | unset |
| 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_BACKEND | string | No | unset |
| 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
| Variable | Type | Required | Default |
|---|
LOG_LEVEL | string | No | INFO |
| Allowed: DEBUG, INFO, WARNING,
ERROR. Invalid values fail settings validation. |
LOGSTASH_HOST | string | No | unset |
| 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_PORT | integer | No | unset |
| 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_NAME | string | No | unset |
| 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_ID | string | No | unset |
| 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
| Variable | Type | Required | Default |
|---|
AION_DOCS_URL | string | No | https://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
