# Configuration > Every flag, environment variable, and default, with precedence rules and the session-directory and shared-cache notes. Canonical URL: https://www.slivingdoc.dev/docs/reference/configuration/ · Version: 0.1 · Updated: 2026-09-21 Full site index: https://www.slivingdoc.dev/llms.txt `serve`, `pull`, and `commit` read the same flags and environment variables. Flags override environment variables, and the environment overrides defaults. A bucket is required, as `--bucket` or as `SLIVINGDOC_BUCKET`. `-h` on any of the three prints the same reference. | Function | Flag | Environment variable | Default | | --------------------- | ------------------------ | --------------------------------- | ------------------------- | | S3 bucket (required) | `--bucket` | `SLIVINGDOC_BUCKET` | — | | S3 object prefix | `--prefix` | `SLIVINGDOC_PREFIX` | `slivingdoc` | | S3 region | `--region` | `AWS_REGION` | `us-east-1` | | S3 endpoint | `--endpoint` | `AWS_ENDPOINT_URL_S3` | empty (AWS resolution) | | S3 path-style access | `--path-style` | `SLIVINGDOC_PATH_STYLE` | `false` | | Workspace root | `--workspace-root` | `SLIVINGDOC_WORKSPACE_ROOT` | session dir / working dir | | Private state root | `--private-root` | `SLIVINGDOC_PRIVATE_ROOT` | session dir / user cache | | Shared pack cache | `--shared-pack-cache` | `SLIVINGDOC_SHARED_PACK_CACHE` | `false` | | CAS retry limit | `--commit-retries` | `SLIVINGDOC_COMMIT_RETRIES` | `8` (0..100) | | Checkpoint pack count | `--checkpoint-packs` | `SLIVINGDOC_CHECKPOINT_PACKS` | `256` (minimum 1) | | Retained checkpoints | `--retained-checkpoints` | `SLIVINGDOC_RETAINED_CHECKPOINTS` | `1` (0..64) | | Read-only paths | `--read-only-paths` | `SLIVINGDOC_READ_ONLY_PATHS` | empty (no read-only path) | | Writable paths | `--writable-paths` | `SLIVINGDOC_WRITABLE_PATHS` | empty (no confinement) | | Log levels | `--log-level` | `LOG_LEVEL` | `info` | | Log timestamps | `--log-timestamp` | `SLIVINGDOC_LOG_TIMESTAMP` | `true` | `--workspace-root` is the root below which request paths may live, and is also the notebook directory an omitted path resolves to. The private root holds the internal Git repository, the state record, and the operation locks. It must not be at or below the workspace root. Both roots become absolute before startup. ## How values are read Flags override environment variables, which override defaults — with one sharp edge: an explicitly empty flag value does **not** fall back to the environment. `--read-only-paths=` clears an inherited `SLIVINGDOC_READ_ONLY_PATHS` rather than falling back to it, and the same holds for every shared flag. That is how a process asks not to inherit a setting its parent exported. Boolean values are parsed as Go booleans, so `true`, `false`, `1`, and `0` all work. Decimal integer values do not accept a sign. An invalid flag value refuses startup before any native or network dependency is touched; the one exception is `LOG_LEVEL`, whose malformed value is reported and falls back to `info` — see [Logging and profiling](/docs/reference/logging/). ## The session directory `serve` with neither root configured takes a per-process session directory and puts both roots inside it: ```text /slivingdoc-/notebook the workspace root /slivingdoc-/private the private root ``` This is the default because it needs no configuration and no coordination: every server gets its own notebook directory and its own private state, so concurrent agents never contend for one operation lock. The tools then need no `path`, and both the server instructions and every tool result name the directory. The whole session directory is removed at shutdown — the durable notebook is the bucket, so nothing of value is in it. A process killed outright leaves its directory for the operating system to reap; no later process reuses it, because the derived private key binds to that random path. Configuring either root turns the default off, and neither root is removed at shutdown. Use that when humans and agents share one directory, or when you want the notebook to survive a server restart on disk. `pull` and `commit` never take a session directory: they default to the working directory, which you can still open after the process exits. ## The shared pack cache By default every workspace keeps its own cache of downloaded pack bytes inside its private state, so several agents on one machine each download the same packs — and an ephemeral session throws its cache away at shutdown. `--shared-pack-cache` moves that cache to one durable directory per notebook: ```text /slivingdoc/pack-cache/--/ ``` Every server addressing the same endpoint, bucket, and prefix computes the same directory from its own configuration, so agents share downloads with no coordination: the first cold pull populates the directory and later pulls by any agent read from it. Entries are keyed by SHA-256 and re-verified against the authoritative manifest on every read, so a corrupt or foreign entry is discarded and re-downloaded, never trusted. Only pack bytes are shared: each workspace keeps its own private repository, baseline, and locks. The directory names make manual cleanup easy. Remove a notebook's directory when you are done with it, and the next pull simply re-downloads. > **Note:** Writing into the shared cache is best-effort. A read-only or > full cache directory logs a warning and the operation continues, which > is what makes a pre-populated read-only cache — baked into a container > image, for example — work as-is. > **Warning:** `--workspace-root` and `--private-root` must never point at > the same directory, and the private root must not sit at or below the > workspace root. Startup refuses otherwise. See [S3 requirements](/docs/reference/s3/) for the bucket permissions this configuration assumes, and [Restrict agents with path policies](/docs/guides/path-policies/) for `--read-only-paths` and `--writable-paths` in practice.