AXIS Documentation / Getting Started / Configuration

Configuration

Environment-drivenFail-fast validation

AXIS is configured through environment variables (loaded from the process environment and a .env file via dotenvy). Invalid or contradictory configuration fails startup — there is no "unlimited mode" and no silent downgrade path.

.env.example is local-only. .env.production.example is a placeholder template containing no real secrets. Never commit .env.production.local.

Core settings

Variable	Default	Notes
`LISTEN_ADDR`	`0.0.0.0:6543`	HTTP listener address
`DATABASE_URL`	built from DB fields	PostgreSQL connection
`DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASS`	`localhost` / `5432` / `prod_main` / `varux` / `varux`	Compose uses demo credentials only
`OPERATING_MODE`	`enforce`	One of `shadow`, `approval_first`, `enforce`, `emergency_bypass` — see Operating Modes
`AXIS_OPERATOR_TOKEN`	unset	Required for mutating policy lifecycle endpoints and approval resolution; header `X-AXIS-Operator-Token` or `Authorization: Bearer <token>`

Policy store

Variable	Default	Notes
`AXIS_POLICY_DIR`	`./policies`	Policy directory (compose mounts it read-only)
`AXIS_POLICY_MANIFEST`	`./policies/policy_manifest.json`	Manifest is authoritative at startup
`AXIS_ENABLE_POLICY_RELOAD`	`false`	Controlled reload is internal-only in v0.9 and disabled by default; no HTTP reload endpoint exists
`POLICY_PATH`	`./policies/prod_main.json`	Deprecated compatibility variable
`AXIS_POLICY_STORE_PATH`	`./data/policies`	Local lifecycle store (`active.json`, `manifest.json`, `versions/`)

Policy lifecycle details (validation, dry-run, activation, rollback, operator protection) are on the Policy Engine page.

Audit & evidence paths

Variable	Default	Notes
`AUDIT_WAL_PATH`	`./audit.wal`	Canonical append-only audit WAL (enterprise compose uses `AXIS_AUDIT_WAL_PATH`)
`AUDIT_LOG_PATH`	`./audit.log`	JSONL projection (non-authoritative; enterprise name `AXIS_AUDIT_LOG_PATH`)
`AXIS_APPROVAL_DB_PATH`	`./data/approvals.sqlite`	Approval store (install guide; the security model also documents a JSONL-backed store at `approvals.jsonl`)
`AUDIT_INDEX_PATH`	`./data/index/audit_index_v1.json`	Derived read-model index; safe to delete, rebuild or ignore — WAL remains canonical
`AXIS_AUDIT_EXPORT_REQUIRES_OPERATOR`	`false`	Production default is enabled; local mode leaves export public because Evidence Bundle V1 is redacted

Runtime hardening & limits

Variable	Default	Notes
`AXIS_RUNTIME_PROFILE`	—	`local` or `production`; invalid value fails startup. Production fails fast without a strong operator token; weak values (`changeme`, `default`, `password`, `secret`, ...) are rejected
`AXIS_REQUEST_TIMEOUT_MS`	`10000`	Must be greater than `AXIS_DB_QUERY_TIMEOUT_MS`
`AXIS_DB_QUERY_TIMEOUT_MS`	`8000`	DB operation timeout; on expiry execution state is reported as `unknown`
`AXIS_DB_CONNECT_TIMEOUT_MS`	`5000`	Connection acquisition timeout
`AXIS_DB_POOL_MAX_CONNECTIONS`	`10`	DB pool size
`AXIS_DB_POOL_ACQUIRE_TIMEOUT_MS`	`3000`	Pool acquire timeout → `db_pool_exhausted`
`AXIS_MAX_BODY_BYTES`	`1048576`	Request body limit → `request_body_too_large`
`AXIS_MAX_SQL_BYTES`	`262144`	SQL text limit (must be ≤ body limit) → `sql_too_large`; oversized SQL is never written raw
`AXIS_RATE_LIMIT_ENABLED`	`true`	Rate limiting on; `/health` is not rate-limited
`AXIS_RATE_LIMIT_REQUESTS_PER_MINUTE`	`120`	Per-actor limit; first enforced key for `POST /query` is `actor`
`AXIS_RATE_LIMIT_BURST`	`30`	Burst allowance → `rate_limited` (429)

Protected writes are never retried automatically after a timeout; reconcile database state first (see Failure & Recovery).

Operator auth (JWT)

Variable	Default	Notes
`AXIS_AUTH_MODE`	—	`jwt_hs256` for local/demo JWT validation; HS256 is not full enterprise IAM
`AXIS_JWT_REQUIRED`	`false`	When `true`, `/query` requires `Authorization: Bearer <token>`; spoofed JSON body fields are ignored and conflicts are recorded in request audit payloads
`AXIS_JWT_HS256_SECRET`	—	Strong managed local validation secret

Evidence signing

Variable	Notes
`AXIS_EVIDENCE_SIGNING_ENABLED`	`true` enables optional server-side Ed25519 signing of Evidence Bundle V1 exports
`AXIS_EVIDENCE_SIGNING_KEY_ID`	Key identifier recorded in bundle metadata (`kid`)
`AXIS_EVIDENCE_SIGNING_PRIVATE_KEY_B64` / `AXIS_EVIDENCE_SIGNING_PUBLIC_KEY_B64`	Base64 raw keys; invalid key material makes export fail safely with a structured error — no key material is leaked

Unsigned exports are marked signature_status: disabled / signature_algorithm: none and are never presented as signed evidence. Audit WAL signing itself requires AXIS_AUDIT_SIGNING_KEY_PATH in production startup (tests use ephemeral local keys).

TLS / mTLS (hardened core)

Variable	Notes
`AXIS_TLS_REQUIRE_CLIENT_CERT`	Production rejects `false`; local mode allows cleartext only when TLS material is not configured
`AXIS_TLS_CLIENT_CA_BUNDLE_PATH` / `AXIS_TLS_SERVER_CERT_PATH` / `AXIS_TLS_SERVER_KEY_PATH`	Client-to-AXIS TLS termination material
`AXIS_TLS_UPSTREAM_CLIENT_CERT_PATH` / `AXIS_TLS_UPSTREAM_CLIENT_KEY_PATH` / `AXIS_TLS_UPSTREAM_CA_BUNDLE_PATH`	AXIS-to-PostgreSQL mTLS material

These variables exist in the hardened core. The v0.6 pilot package itself does not yet deliver a complete TLS/mTLS deployment story — see mTLS & Network.

pg_hba baseline (native path)

Variable	Notes
`AXIS_PG_HBA_PROXY_CIDR`	Allowed proxy CIDR; drift → signed `AXIS_PG_HBA_DRIFT_DETECTED` audit event
`AXIS_ENFORCE_PG_HBA_BASELINE`	Checks `pg_hba_file_rules` against the proxy-only hostssl/cert baseline
`AXIS_PG_HBA_CHECK_INTERVAL_MINUTES`	Baseline check interval

Audit checkpoint anchoring

Variable	Notes
`AXIS_AUDIT_CHECKPOINT_INTERVAL_EVENTS` / `AXIS_AUDIT_CHECKPOINT_INTERVAL_MINUTES`	Checkpoint frequency (signed compact statement of the durable WAL head)
`AXIS_AUDIT_CHECKPOINT_FAILURE_ALERT_THRESHOLD` / `AXIS_AUDIT_CHECKPOINT_MAX_BACKOFF_SECONDS`	Failure escalation and bounded exponential backoff
`AXIS_AUDIT_CHECKPOINT_FILE_REPLICA_PATH`	Append-only file replica sink
`AXIS_AUDIT_CHECKPOINT_WEBHOOK_URL` / `AXIS_AUDIT_CHECKPOINT_WEBHOOK_BEARER_TOKEN`	Webhook sink; failures do not roll back a locally committed WAL event

Native PG wire listener (lab)

Variable	Default	Notes
`AXIS_PGWIRE_ENABLED`	`false`	Disabled by default; lab-only Simple Query listener
`AXIS_PGWIRE_LISTEN_ADDR`	`0.0.0.0:6544`	PG wire listener address
`AXIS_PGWIRE_BACKEND_ADDR`	`127.0.0.1:5432`	Upstream PostgreSQL
`AXIS_PGWIRE_LAB_MODE`	`true`	Cleartext startup/auth pass-through, lab only
`AXIS_PGWIRE_UNSUPPORTED_FAIL_CLOSED`	`true`	Unsupported protocol messages fail closed

Control Plane

Variable	Default	Notes
`AXIS_CONTROL_PLANE_MODE`	`real`	`real` reads live endpoints; `mock` is explicit server-side demo behavior only, not production evidence
`AXIS_BACKEND_URL`	`http://localhost:6543`	Server-only; the browser must never receive the backend URL
`AXIS_PROXY_TIMEOUT_MS`	`8000`	Server-side proxy timeout
`NEXT_PUBLIC_REFRESH_INTERVAL_MS`	`5000`	Dashboard refresh interval

Policy file format

The active policy is a JSON file (e.g. policies/prod_main.json). The manifest (policies/policy_manifest.json) declares the active policy version and stores the raw policy file SHA-256; the manifest is authoritative at startup.

policies/prod_main.json (shape)

{
  "schema_version": "1.0",
  "policy_version": "prod_main@1.0.0",
  "defaults": { "read": "ALLOW", "write": "BLOCK", "ddl": "REQUIRE_APPROVAL" },
  "write_rules": [
    {
      "id": "rule-1",
      "action": "REQUIRE_APPROVAL",
      "match": { "operation": "DELETE", "condition": "bulk_limit > 100" },
      "approver_group": "platform-leads",
      "reason_code": "approval_required_batch"
    }
  ]
}

Accepted action values: ALLOW, BLOCK, REQUIRE_APPROVAL (the alias APPROVAL_REQUIRED is accepted in policy deserialization). Validation is read-only; invalid policy JSON prevents healthy startup.

Secret handling

Central redaction replaces secrets with <REDACTED> in logs and responses: bearer tokens, JWT-like tokens, AXIS_OPERATOR_TOKEN, password=... connection fields, postgres://user:password@host/db, secret=..., token=..., signing_key=..., private_key=... and private-key PEM blocks.
Production deployments should source credentials from a secret manager, rotate axis_executor and application credentials independently, and revoke direct write-capable application credentials before routing protected writes through AXIS.
The repository may contain local demo placeholders intentionally labeled local/demo — they are not production credentials.

See Operations and mTLS & Network for the related runbook material.