Configuration

Reference

Configuration & precedence

Every Aarmos setting is declared once and resolved through a single, documented precedence order. Nothing in the runtime reads the environment on its own, so there is always one answer to “why is it doing that?”.

Precedence — highest wins

  • 1 · Flag

    An explicit command-line flag, e.g. --port 7700.

  • 2 · Environment

    An AARMOS_* variable in the process environment.

  • 3 · Workspace

    ./.aarmos/config.json — checked into the project or local to it.

  • 4 · User

    ~/.aarmos/config.json — your machine-wide defaults.

  • 5 · Default

    The value declared by the runtime.

A lower-precedence value is not discarded when something outranks it — it is retained and reported as shadowed, so you can see what would apply if you removed the override.

Ask the runtime

aarmos config explain prints the effective value of every setting, where it came from, what it shadows, and which AARMOS_* variables in your environment the runtime does not recognise — so a typo shows up instead of silently doing nothing.

aarmos config explain
aarmos config explain port

Secrets are reported as set or unset. Their values are never printed, and never included in a diagnostics bundle.

Recognised settings

Config-file keys use the camelCase name; the environment uses the AARMOS_* name.

  • port · AARMOS_PORT

    Local governance endpoint port. A convention, not a reservation — change it freely.

    Default: 7681

  • listen · AARMOS_LISTEN

    Bind address, or a Unix socket / named pipe path. Non-loopback addresses are refused.

    Default: 127.0.0.1

  • transport · AARMOS_TRANSPORT

    auto | tcp | ipc. auto prefers a socket where available and falls back to loopback TCP.

    Default: auto

  • localAuth · AARMOS_LOCAL_AUTH

    required | compat. Local client authentication mode. compat exists only for migration.

    Default: required

  • sessionTtlMinutes · AARMOS_SESSION_TTL_MINUTES

    Lifetime of a local runtime session token, in minutes.

    Default: 720

  • observationSource · AARMOS_OBSERVATION_SOURCE

    Display name shown for this observation source in the Operations view.

    Default: machine name

  • observe port · flag only (--port)

    Loopback port for the observation service started by aarmos observe. Separate from the governance endpoint port.

    Default: 7682

  • observeTrust · AARMOS_OBSERVE_TRUST

    enabled | disabled. Whether browsers may register as observation clients. Set to disabled to require a fresh pairing code every session.

    Default: enabled

  • operationsUrl · AARMOS_OPERATIONS_URL

    Destination printed by aarmos observe. Point it at your own deployment if you self-host.

    Default: aarmos.io/observe

  • syncAppends · AARMOS_SYNC_APPENDS

    Commit every evidence append synchronously instead of coalescing writes.

    Default: false

  • telemetry · AARMOS_TELEMETRY

    on | off. Anonymous install-funnel telemetry. Off unless you turn it on.

    Default: off

  • rekorUrl · AARMOS_REKOR_URL

    Transparency log endpoint used by aarmos anchor.

    Default: unset

Secret material

Supplied through the environment only — never through a config file.

  • AARMOS_POLICY_PRIVATE_KEY

    Ed25519 key used to sign compiled policy bundles.

  • AARMOS_IDENTITY_PASSPHRASE

    Passphrase protecting exported identity bundles.

A workspace config file

// .aarmos/config.json
{
  "port": 7700,
  "transport": "ipc",
  "observationSource": "build-agent-3",
  "syncAppends": true
}

An invalid value fails at startup with exit code 14 (configuration-invalid) and names the key, rather than being coerced into something surprising.

Related