# Configuration

Configuration discovery, starter settings and the complete field references.

Aion reads one TOML file, then applies supported environment overrides and command-line overrides. The shipped starter config enables local features explicitly. That file is different from the defaults of an omitted section.

> This reference follows main
> The public 18 September 2026 release has earlier settings, including a singular gRPC listener. Start with your installed binary’s generated config. See [release availability](/aion/reference/sources/) before copying main settings.


## Which file wins

An explicit config path wins. Otherwise Aion checks the working directory's project config, then the config under Aion home, then built-in values. It reads only the first discovered file; a read or parse error is a refusal.

Environment overrides win over that file. Command-line overrides win over the environment. The environment mapping is an allowlist, not a variable for every field.

## Aion home

An explicit Aion home environment value selects the home; otherwise it is derived under the user's home directory. Store and authoring defaults live beneath it. An explicit store or workspace path wins.

A derived home can adopt an existing legacy data or authoring directory in the working directory. An explicit Aion home disables that legacy discovery. Read the config path and data directory in the startup report.

## Startup code

- `workflow_packages`: Top-level archive path list, default empty. Boot merges these with .aion files directly in the working directory and repeatable CLI package flags. Discovery is sorted, not recursive; canonical duplicate paths load once.


## Shipped starter configuration

This is the current scaffold's active configuration. It chooses an unlimited node cache explicitly, enables deployment, enables the local liminal worker listener and commissions worker supervision. Change those values for the deployment you are operating.

**aion.toml — shipped starter settings**

```toml
[server]
listen_address = "127.0.0.1:8080"
grpc_addresses = ["127.0.0.1:50051"]
[store]
backend = "haematite"
node_cache_budget = "unlimited"
[runtime]
query_timeout_ms = 10000
stop_drain_timeout_ms = 30000
[outbox]
enabled = true
transport = "liminal"
liminal_listen_address = "127.0.0.1:50061"
[worker_supervision]
restart_backoff_initial_ms = 1000
restart_backoff_max_ms = 30000
restart_backoff_multiplier = 2
restart_window_ms = 600000
max_restarts_per_window = 5
stop_grace_ms = 10000
[websocket]
event_broadcast_capacity = 1024
cluster_broadcast_capacity = 64
[observability]
max_batch_events = 64
max_batch_hold_ms = 200
[deploy]
enabled = true
max_archive_bytes = 16777216
max_inflated_bytes = 67108864
```


## Complete field references

[Engine and storage](/aion/reference/configuration-engine/)

Listeners, haematite, cluster peers, runtime, drain and namespaces.
[Access and authoring](/aion/reference/configuration-access/)

Auth, Lys, TLS, console, authoring, deployment and assistant accounts.
[Workers and streams](/aion/reference/configuration-workers/)

Worker policy, supervision, outbox, transcripts, WebSocket and MCP.
[Environment](/aion/reference/environment/)

Every served environment override and the separate client settings.

## Existing configurations

The boot path can heal missing required file values. It preserves the prior file beside the target and logs the inserted keys. Invalid values or a failed config write refuse boot.

Unknown keys are refused. The old libSQL inputs and singular gRPC-listener key are refused with their replacement. The two retired store-lock timing keys are warned and ignored; lock acquisition waits for the kernel writer lock.