> ## Documentation Index
> Fetch the complete documentation index at: https://podium.do/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Podium installation

> Reference the supported state path, configuration keys, environment overrides, and precedence.

The default instance writes installation settings to `~/.podium/config.json`. An instance selected with `PODIUM_INSTANCE` uses `${XDG_STATE_HOME:-$HOME/.local/state}/podium/instance_name/config.json`. Environment variables override matching file values, which override built-in defaults.

## Configuration locations

The state root keeps configuration beside the database and runtime files:

| Path | Purpose |
| - | - |
| `<state-root>/config.json` | Deployment and update settings |
| `<state-root>/podium.db` | Issues, sessions, repositories, machines, and settings |
| `<state-root>/logs/` | Logs for detached components |
| `<state-root>/uploads/` | Session attachments |
| `<state-root>/transcripts/` | Mirrored and indexed daemon transcripts |
| `<state-root>/artifacts/` | Server snapshots attached to issues |
| `<state-root>/daemon.json` | Stable paired-machine identity and token |
| `<state-root>/daemon.secret` | Owner-only same-host daemon credential |

Set `PODIUM_STATE_DIR` to move the whole state root. Do not point two live instances at the same directory.

## Supported operator keys

These file keys are useful for local and self-hosted operation:

| Key | Values | Default |
| - | - | - |
| `mode` | `all-in-one`, `server`, `daemon`, `client`, `supervisor` | Unconfigured installs choose `all-in-one` |
| `serverUrl` | WebSocket server URL | Required for daemon, client, or supervisor mode |
| `port` | Positive integer | `18787` for the default instance |
| `bindHost` | `127.0.0.1` or `0.0.0.0` | `127.0.0.1` |
| `publicUrl` | Device-reachable HTTP or HTTPS URL | Unset |
| `updateChannel` | `stable`, `edge`, or development-only `dev` | `stable` |
| `persistence` | `systemd` or `detached` | Chosen during headless setup |
| `networkOption` | Setup network choice | Unset |
| `auth.openMode` | Boolean | Depends on whether credentials exist |
| `appUrl` | Origin that serves a separately hosted web UI | Unset |
| `allowedOrigins` | Credentialed cross-origin UI origins | Empty list |
| `updateScope` | `all` or `fleet-only` | `all` |
| `transcriptLake` | `on` or `off` | `on` |
| `telemetry.usage` | `on` or `off` | Off unless enabled |
| `telemetry.crash` | `on` or `off` | Off unless enabled |

Use `podium setup` and `podium channel` for routine changes. Hand-edit the file only when no supported command covers the setting, then restart for boot-time values such as mode, port, and bind host.

## Common environment overrides

Use environment overrides when the deployment, rather than the interactive setup flow, owns a value:

| Variable | Effect |
| - | - |
| `PODIUM_INSTANCE` | Selects an isolated named instance |
| `PODIUM_STATE_DIR` | Replaces the default state root |
| `PODIUM_PORT` | Overrides `port` |
| `PODIUM_HOST` | Overrides `bindHost` |
| `PODIUM_MODE` | Overrides `mode` |
| `PODIUM_PUBLIC_URL` | Overrides `publicUrl` |
| `PODIUM_APP_URL` | Overrides `appUrl` for a separately hosted UI |
| `PODIUM_ALLOWED_ORIGINS` | Sets the comma-separated credentialed CORS origins |
| `PODIUM_UPDATE_CHANNEL` | Overrides `updateChannel` |
| `PODIUM_UPDATE_SCOPE` | Selects self-and-fleet or fleet-only updates |
| `PODIUM_TRANSCRIPT_LAKE` | Enables or disables transcript mirroring |
| `PODIUM_PASSWORD` | Seeds the first admin password once without overwriting an existing credential |
| `PODIUM_TLS_KEY_FILE` and `PODIUM_TLS_CERT_FILE` | Enable direct TLS; both must be set together |
| `PODIUM_TRUSTED_PROXY_HOPS` | Sets how many reverse-proxy hops may supply forwarded request metadata |
| `PODIUM_TELEMETRY=off` | Suppresses telemetry and its setup prompt |
| `DO_NOT_TRACK=1` | Suppresses telemetry |

For layered values that appear in setup, an environment-owned value locks the corresponding control. Change the deployment environment instead of editing the file.

<Warning>
  Many additional `PODIUM_*` variables exist for internal services, tests, or hosted deployment. The entries above are supported operator controls, not an inventory of every source-level variable. Do not treat an unlisted variable as a public contract unless it also appears in command help or deployment documentation.
</Warning>