---
title: Configuration & environment
path: reference/configuration
status: published
---

# Configuration & environment

ScaiLog is configured through environment variables, a few command-line flags,
and — for the CLI — a `config.toml` file. Each runtime component reads its own
`SCAILOG_*` variables; there is no shared global config file for the server.
This page enumerates every environment variable and config key from the source,
grouped by the component that reads it, then describes the CLI config file and
the on-disk data-dir layout.

## Server (`scailog-server`)

The server reads its configuration from `ServerConfig.from_env()`. Command-line
flags to `scailog-server` are `--standalone`, `--data-dir`, `--host` (default
`127.0.0.1`), `--port` (default `8080`), and `--init` (initialize, print the
bootstrap key, and exit).

| Variable | Controls | Default |
| --- | --- | --- |
| `SCAILOG_DATA_DIR` | Directory holding all SQLite files and keys | `./scailog-data` |
| `SCAILOG_STANDALONE` | Embed the agent role (open the local socket, ingest directly) | `false` |
| `SCAILOG_KEYSTORE` | Path to the passphrase-encrypted root keystore | `<data-dir>/scailog-root.key` |
| `SCAILOG_KEYSTORE_PASSPHRASE` | Passphrase that unlocks the keystore | *(unset)* |
| `SCAILOG_VAULT_URL` | Optional ScaiVault URL for KRoot custody | *(unset)* |
| `SCAILOG_VAULT_TOKEN` | Optional ScaiVault token | *(unset)* |
| `SCAILOG_OIDC_BASE_URL` | Optional OIDC (ScaiKey) issuer base URL | *(unset)* |
| `SCAILOG_OIDC_CLIENT_ID` | OIDC client id | *(unset)* |
| `SCAILOG_OIDC_CLIENT_SECRET` | OIDC client secret | *(unset)* |
| `SCAILOG_OIDC_DEFAULT_TENANT` | Tenant for OIDC tokens with no tenant claim; if unset such tokens are rejected (fail-closed) | *(unset)* |
| `SCAILOG_SOCKET` | Local agent socket used in standalone mode | `/run/scailog/agent.sock` |

`SCAILOG_STANDALONE` is truthy for `1`, `true`, `yes`, or `on` (case-insensitive).

OIDC is enabled only when **both** `SCAILOG_OIDC_BASE_URL` and
`SCAILOG_OIDC_CLIENT_ID` are set **and** the ScaiKey SDK is installed; otherwise
the server accepts only built-in API keys. OIDC tokens are mapped to a role via
the `scailog_role` claim (unknown or missing role defaults to `log_reader`); the
tenant comes from the `tenant`/`tid` claim or `SCAILOG_OIDC_DEFAULT_TENANT`.

A few `ServerConfig` fields are not wired to environment variables and take
their dataclass defaults: `keymap_backup_retention_days` (`7`),
`retention_sweep_seconds` (`3600`), and `self_ingest` (`true`).

## Agent (`scailog-agent`)

The agent reads these (all overridable by command-line flags of the same name).

| Variable | Controls | Default |
| --- | --- | --- |
| `SCAILOG_AGENT_KEY` | The agent's `ingest`-capable API key | *(unset)* |
| `SCAILOG_SOCKET` | Local unix socket the SDK connects to | `/run/scailog/agent.sock` |
| `SCAILOG_AGENT_CACHE` | Agent-side SQLite cache path | `./agent.db` |
| `SCAILOG_SERVER` | Central server base URL | `http://127.0.0.1:8080` |
| `SCAILOG_TENANT` | Tenant the agent enrolls into | `default` |
| `HOSTNAME` | Host label attached to entries | `localhost` |

## SDK (emit path)

The default logger reads its identity from the environment.

| Variable | Controls | Default |
| --- | --- | --- |
| `SCAILOG_SOCKET` | Agent socket to emit to | `/run/scailog/agent.sock` |
| `SCAILOG_TENANT` | Tenant | `default` |
| `SCAILOG_SERVICE` | Service name | `unknown` |
| `SCAILOG_ENV` | Environment label | `prod` |

## CLI (`scailog`) and CI (`scailog-ci`)

Both read the same config file and a small set of variables.

| Variable | Controls | Default |
| --- | --- | --- |
| `SCAILOG_CONFIG` | Path to the CLI config file | `~/.config/scailog/config.toml` |
| `SCAILOG_SERVER` | Server base URL | `http://127.0.0.1:8080` |
| `SCAILOG_API_KEY` | API key (highest credential precedence) | *(unset)* |
| `SCAILOG_TENANT` | Default tenant | `default` |
| `SCAILOG_CREDENTIALS` | Path to the stored OIDC session (CLI only) | `~/.config/scailog/credentials.json` |
| `SCAILOG_OIDC_BASE_URL` | OIDC issuer for `scailog login` | *(unset)* |
| `SCAILOG_OIDC_CLIENT_ID` | OIDC client id for `scailog login` | *(unset)* |

## Audit (`scailog-audit`)

The offline audit job reads `scailog.db` directly and calls the ScaiGrid
classifier.

| Variable | Controls | Default |
| --- | --- | --- |
| `SCAILOG_DB` | Path to the central store to scan | `./scailog-data/scailog.db` |
| `SCAILOG_TENANT` | Tenant to audit | `default` |
| `SCAILOG_AUDIT_MODEL` | Classifier model name | `poolnoodle-small` |
| `SCAILOG_AUDIT_BASE_URL` | ScaiGrid base URL | *(unset)* |
| `SCAIGRID_API_KEY` | ScaiGrid API key (note: no `SCAILOG_` prefix) | *(unset)* |

## The CLI config file (`config.toml`)

The `scailog` CLI and `scailog-ci` load `~/.config/scailog/config.toml` (or
`$SCAILOG_CONFIG`). Top-level keys mirror the environment overrides, and an
optional `[oidc]` section supplies device-flow login settings.

```toml
server_url = "http://127.0.0.1:8080"
api_key = "slk_read_XXXXXXXXXXXX"
tenant = "default"

[oidc]
base_url = "https://id.example.com"
client_id = "scailog-cli"
```

Environment variables win over the file: `SCAILOG_SERVER`, `SCAILOG_API_KEY`,
and `SCAILOG_TENANT` override `server_url`, `api_key`, and `tenant`
respectively. For login, `--oidc-url`/`--client-id` win over
`SCAILOG_OIDC_*`, which win over the `[oidc]` section.

## Data-dir layout

Everything the server persists lives under the data dir (`SCAILOG_DATA_DIR`).
The key-map is a deliberately separate SQLite file so its backups can be held to
a short retention window — that retention bound is what makes cryptographic
erasure absolute.

| Path | What it is |
| --- | --- |
| `scailog.db` | The central store: entries, call sites, policies, receipts, audit findings, API keys (SQLite + FTS5, WAL) |
| `keymap.db` | Per-subject DEK map — a **separate** SQLite file with short backup retention; destroying a key here is the crypto-shred |
| `scailog-root.key` | Passphrase-encrypted root keystore (holds KRoot), unless `SCAILOG_KEYSTORE` points elsewhere |
| `report-keyring.json` | The rotating report signing keyring (active + retired Ed25519 keys) |
| `report.key` | Legacy single report key; imported into the keyring if present |

The agent, when run separately, keeps its own cache in `agent.db`
(`SCAILOG_AGENT_CACHE`) on the agent host, not in the server data dir.