Configuration

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.

The session directory

serve with neither root configured takes a per-process session directory and puts both roots inside it:

<tmp>/slivingdoc-<random>/notebook    the workspace root
<tmp>/slivingdoc-<random>/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:

<user-cache-dir>/slivingdoc/pack-cache/<bucket>-<prefix>-<digest>/

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 for the bucket permissions this configuration assumes, and Restrict agents with path policies for --read-only-paths and --writable-paths in practice.