Skip to content

Persistent Platform Configuration

Every install ships a release-owned a10e.toml that an upgrade replaces, and a shared .env that operators have always been able to edit safely. This page covers a third layer: an operator config overlay at /etc/a10e/config.toml, read by env-manager serve and every bundle program (up, start, stop, health), that no install, upgrade, or rollback ever touches. It uses the same schema as a10e.toml, so anything you can set in the shipped file you can pin here instead — most usefully the API and dashboard ports.

File Owner Survives upgrade? Purpose
a10e.toml (release root) Release No — replaced every install/upgrade Baseline platform config for that release. Don’t edit it on a host.
.env.defaults (release root, bundles only) Release No — replaced every install/upgrade Secret-free defaults such as AUTH_PROVIDER=local, applied as their own layer between the shipped TOML and the overlay.
/etc/a10e/config.toml Operator Yes The overlay this page covers. Same schema as a10e.toml; may hold secrets.
/etc/a10e/a10e.toml Operator Yes Legacy overlay filename, honored only when config.toml is absent. Never merged with it — see Discovery.
.env (shared .env on bundle installs) Operator Yes The existing operator mechanism — secrets and any KEY=value override, process-environment precedence.
/etc/a10e/config.json a10e CLI Yes Unrelated: the CLI’s own install metadata (source directory, channel). Not a config overlay and not TOML — don’t confuse the two files in /etc/a10e/.

The overlay lookup is unconditional and independent of -config / A10E_CONFIG_PATH (which only select the shipped base file):

  1. config.toml in the overlay directory (default /etc/a10e, redirect with A10E_CONFIG_OVERLAY_DIR), if present.
  2. Otherwise a10e.toml in that same directory — a legacy fallback for hosts that already kept one there before this feature existed.
  3. Otherwise no overlay; this is a silent no-op, not an error.

Exactly one file is ever loaded. If both config.toml and a10e.toml exist in the directory, only config.toml applies and the ignored a10e.toml is logged as a warning — it is never merged in. A10E_CONFIG_OVERLAY_PATH names a single file directly, bypassing this directory search entirely (mainly for tests and non-root local runs).

A present but unreadable or malformed overlay fails startup with an error naming the path — unlike a missing overlay, it never falls back to the shipped config unnoticed.

Bundle programs (bundle up, bundle start/stop/health) resolve configuration lowest to highest:

built-in defaults < shipped a10e.toml < release .env.defaults < operator overlay < shared .env < process environment < explicit flag (bundle up -dashboard-port, -postgres-port)

env-manager serve and the CLI subcommands (catalog scan, cleanup run) use the same chain without the .env.defaults layer, since that file is bundle-specific:

built-in defaults < shipped a10e.toml < operator overlay < environment variables < CLI flags

A10E_PORT and A10E_DASHBOARD_PORT — wherever they’re set, shared .env or the plain process environment — always win over the overlay. The overlay always wins over anything the release ships. Dashboard port precedence specifically: an explicit -dashboard-port flag beats A10E_DASHBOARD_PORT, which beats [bundle] dashboard_port in the overlay, which beats the shipped a10e.toml, which beats the built-in default of 3000.

Passing -dashboard-port to bundle start pins that value into the generated a10e-bundle.service unit’s ExecStart. Omitting it (the default for both the a10e CLI and the documented manual-install unit) leaves the unit to resolve the port itself at every start, which is what lets an overlay edit plus a restart take effect without touching the unit.

The overlay is merged over the shipped config per key, not replaced wholesale:

  • A key you set in the overlay replaces the shipped value.
  • A key you leave out keeps the value from the layer below (shipped a10e.toml, or the built-in default if the shipped file didn’t set it either).
  • Nested tables merge per key: an overlay [ai] table with only model set keeps whatever [ai] provider the shipped file had.
  • Arrays — for example [cors] allowed_origins — are replaced wholesale, not appended to. Setting one origin in the overlay drops every origin the shipped file listed.
  • No key is ever removed by a lower layer; the overlay can only add or override.

Startup logs the paths it loaded, never values:

journalctl -u a10e-bundle.service | grep 'Loaded platform config'

which also carries the “ignoring legacy overlay” warning when both config.toml and a10e.toml were present.

Minimal example: moving the API and dashboard ports

Section titled “Minimal example: moving the API and dashboard ports”

This is the persistent alternative to A10E_PORT / A10E_DASHBOARD_PORT in .env — use whichever mechanism fits; both are supported and the overlay is not required.

sudo mkdir -p /etc/a10e
printf 'port = 8443\n\n[bundle]\ndashboard_port = 8444\n' | sudo tee /etc/a10e/config.toml
sudo chmod 0600 /etc/a10e/config.toml
sudo systemctl restart a10e.service

Root port is API-only — keep it before any [table] header, as TOML requires. [bundle] dashboard_port only affects bundle installs; it’s ignored by a plain env-manager serve deployment, which has no dashboard container to publish.

Verify both endpoints on their new ports, and check the unit picked up the change:

curl -fsS http://127.0.0.1:8443/v1/healthcheck && echo " API OK"
curl -fsS http://127.0.0.1:8444/api/health && echo " Dashboard OK"
journalctl -u a10e-bundle.service -n 50 --no-pager | grep -i 'platform config\|dashboard'

There is no hot reload — a config change only takes effect on the next bundle up/start, so always restart after editing. Setting port = 8443 does not itself enable HTTPS; the API and dashboard still serve plain HTTP on that port. The dashboard’s container-internal port always stays 3000 — only the host-published port moves, so nothing besides the port number itself needs to change. If browsers reach either service through a new host port, update the URLs you hand out, any CORS_ALLOWED_ORIGINS entries that embedded the old port, and firewall/reverse-proxy/SSH-tunnel rules that referenced it (see Remote Access).

Root ownership and 0600 matter because this file can carry secrets — jwt_secret, api_key, database DSNs — the same as .env. A world-readable overlay is still loaded; nothing enforces the mode for you.

Keys below use the overlay’s TOML sections; every one has a matching environment-variable override that still wins over the file. Not every environment variable has a TOML equivalent — the ones without one are marked accordingly.

Section / key Purpose Env override Notes
port API port A10E_PORT Default 8080.
[bundle] dashboard_port Bundled dashboard’s host-published port A10E_DASHBOARD_PORT Default 3000. Bundle installs only.
[cors] allowed_origins Allowed browser origins for the API CORS_ALLOWED_ORIGINS (comma-separated; ALLOWED_ORIGINS as a fallback name) Array — overlay value replaces the shipped list entirely, it does not append.
[auth] provider, jwt_secret, auth0_*, workos_* Authentication — see Identity Integration AUTH_PROVIDER, JWT_SECRET, AUTH0_*, WORKOS_* Prefer keeping jwt_secret in .env, not the overlay, unless you specifically want it host-persisted outside the shared env file too.
[ai] provider, model, api_key, ollama_server_addr, generation_timeout, google_cloud_project, google_cloud_location AI-assisted catalog summaries — see Catalog Scanning AI_PROVIDER, AI_MODEL, AI_API_KEY, AI_OLLAMA_SERVER_ADDR, AI_GENERATION_TIMEOUT, AI_GOOGLE_CLOUD_PROJECT, AI_GOOGLE_CLOUD_LOCATION An empty effective provider disables scan summaries; unsetting AI_PROVIDER does not clear a TOML provider. The scanner does not use enabled/AI_ENABLED or the server generation timeout; see scan triage.
[expiry] default, max Data-enclave request expiry durations A10E_DEFAULT_EXPIRY_DURATION, A10E_MAX_EXPIRY_DURATION Duration strings such as "12h".
[tunnels] default_provider, edge_base_url, cloudflare_image, ngrok_image, ngrok_reserved_tcp_addr Public data-tunnel provider and images — see Tunnel Architecture A10E_TUNNEL_DEFAULT_PROVIDER, A10E_TUNNEL_EDGE_BASE_URL, A10E_CLOUDFLARE_TUNNEL_IMAGE, A10E_NGROK_TUNNEL_IMAGE, A10E_NGROK_RESERVED_TCP_ADDR A10E_LOCAL_TUNNEL_HOST, A10E_CLOUDFLARE_PROXY_HOSTNAME, and A10E_CLOUDFLARE_PROXY_HOSTNAME_MYSQL are environment-only — there is no overlay key for them.
[health] probe_interval, snowflake_probe_interval Background datasource health-probe cadence A10E_HEALTH_PROBE_INTERVAL, A10E_HEALTH_SNOWFLAKE_PROBE_INTERVAL The Snowflake-specific interval exists because probing it runs a real query that can keep an auto-suspending warehouse resumed.
[catalog_scan] interval Background catalog-scan cadence — see Catalog Scanning A10E_CATALOG_SCAN_INTERVAL Default is disabled (0). Bundle releases set A10E_CATALOG_SCAN_INTERVAL=6h in their .env.defaults, so bundle installs scan automatically once A10E_DEIDENTIFY_SECRET_KEY is set in the shared .env (see Catalog Scanning); a plain env-manager serve deployment leaves this unset and relies on its own external scheduler instead.
[db] dsn, max_open_conns, max_idle_conns, max_idle_time PostgreSQL connection A10E_DB_DSN, A10E_DB_MAX_OPEN_CONNS, A10E_DB_MAX_IDLE_CONNS, A10E_DB_MAX_IDLE_TIME Setting dsn (overlay or env) skips the bundled PostgreSQL container entirely. There is no TOML or environment key for the bundled container’s host port — that’s bundle up -postgres-port/bundle start -postgres-port only, a flag, not a persisted setting.
[deployment] driver, image_pull_policy, docker_network Container runtime model A10E_DRIVER, A10E_IMAGE_PULL_POLICY, A10E_DOCKER_NETWORK Bundle installs require driver = "docker".
[approvals.<role>] approvers, allow_self, mode Who may approve or deny each requester role’s access requests, self-approval, and auto-approval — see Request Approval Policy None (TOML only) Overlay table replaces the shipped table for that role whole. Read at startup; restart to apply.
[file_dataset] max_bytes, warn_bytes, warn_days Size and day limits for a table loaded from SSH files — see below A10E_FILE_DATASET_MAX_BYTES, A10E_FILE_DATASET_WARN_BYTES, A10E_FILE_DATASET_WARN_DAYS Defaults 268435456 (256 MB), 104857600 (100 MB), 31. 0 turns a check off.
[fluentd] and sub-tables Audit log streaming — see Auditing with FluentD A10E_FLUENTD_* Unchanged by the overlay feature beyond gaining overlay support like every other section.

A request that loads an SSH datasource’s dated files (see Loading Files Into A Request) builds one table per schema from the files in the requested dates. Three settings bound that load, each per table:

Setting Default Over the limit
max_bytes / A10E_FILE_DATASET_MAX_BYTES 268435456 (256 MB), the sum of the file sizes The request can’t be created: the wizard won’t let the schema be ticked, and the API answers 422.
warn_bytes / A10E_FILE_DATASET_WARN_BYTES 104857600 (100 MB) Allowed. A warning is stored on the request and shown to the requester and the approver.
warn_days / A10E_FILE_DATASET_WARN_DAYS 31 days Allowed, with a warning, as above.

Set any of them to 0 to turn that check off. Values are in bytes and days:

[file_dataset]
max_bytes = 536870912 # 512 MB
warn_bytes = 209715200 # 200 MB
warn_days = 14

Independently of these settings, a request that lists more files than the data environment can accept is rejected with the request lists too many files; narrow the dates. Like every other setting here, a change applies after a restart.

You don’t have to migrate anything — A10E_PORT / A10E_DASHBOARD_PORT and any other override already in .env keeps working exactly as before, and .env keeps winning over the overlay. If you’d rather consolidate port and platform settings into a file separate from secrets:

  1. Add the equivalent key to /etc/a10e/config.toml (see the table above).
  2. Remove the now-redundant A10E_PORT / A10E_DASHBOARD_PORT (or other conflicting key) from .env so precedence isn’t ambiguous — leaving both in place isn’t wrong, but .env will keep winning, which defeats the point of moving it.
  3. Restart (see above).

Keep secrets — JWT_SECRET, A10E_DB_DSN, API keys — in .env unless you have a specific reason to also persist them in the overlay; both are root-owned 0600 and both are read on every start, so there’s no security difference, but .env remains the file every other guide assumes holds your secrets. Settings in either location remain operator-owned across install, upgrade, and rollback — none of the three ever touch /etc/a10e/ or .env.

Once the CLI is on a release that includes aliengiraffe/cli#13, a10e status reports the resolved dashboard port:

Dashboard port: 8444

or Dashboard port: not configured (release default) when nothing overrides it. a10e install, a10e upgrade, and a10e rollback show the same line with --verbose, and include a dashboard_port field in --json output when a port is configured (omitted, not zero, when it isn’t). This is a read-only report of the operator override the CLI can see — A10E_DASHBOARD_PORT in the CLI’s own environment or shared .env, else [bundle] dashboard_port from the same /etc/a10e/config.toml / a10e.toml overlay described above. It is not the release’s fully resolved effective configuration (the CLI never loads a10e.toml or .env.defaults itself), and it’s not what the CLI waits on: health remains fully delegated to the release’s own bundle health command, which already resolves the port through the full precedence chain above, so there’s no separate CLI-side port assumption to get out of sync. The CLI never writes to the overlay and never fails when it’s absent; a malformed overlay or an out-of-range port value does fail status/install/upgrade/rollback, with exit code 2 and an error naming the path.

Symptom Cause / fix
Edited the overlay but the old port is still in use You forgot to restart — there is no hot reload. sudo systemctl restart a10e.service (or a10e-bundle.service directly) and re-check.
Overlay edit has no effect even after restarting A10E_PORT / A10E_DASHBOARD_PORT in .env or the process environment is masking it — that layer always wins over the overlay. Check /opt/a10e/shared/.env (or your equivalent) for the same key.
journalctl shows “Ignoring legacy config overlay” Both /etc/a10e/config.toml and /etc/a10e/a10e.toml exist. Only config.toml applied. Consolidate into one file and delete the other.
Startup fails immediately after creating the overlay Malformed TOML, or the selected file isn’t a valid overlay — the startup error names the exact path. Validate with pnpm dlx @iarna/toml < /etc/a10e/config.toml or any TOML linter, and confirm you didn’t nest port under a table header by mistake (it must be a root-level key, before any [section]).
a10e status / install / upgrade / rollback exits 2 mentioning a dashboard port Same malformed-file or out-of-range-port case, surfaced by the CLI’s own read of the overlay. Fix the file the error names; the CLI never writes it for you.
New port works but you get connection-refused from another host The bundled port change only affects what the container publishes on the host — update any firewall rule, reverse proxy, or SSH tunnel that still targets the old port (see Remote Access).
Health check on the new port never passes Confirm the port isn’t already in use by something else on the host, and that you updated both the API and dashboard verification commands to the new ports — they move independently.
-config / A10E_CONFIG_PATH change didn’t do what you expected with the overlay They only select the shipped base file, not the overlay — see Discovery for how the two interact when they happen to point at the same path.