Files and environment variables are explicit boundaries.
Skarbiec separates the encrypted vault, audit journal, keyring, acquisition state, capability routes, and consumer token files so each can be owned and backed up independently.
There is no configuration file#
Skarbiec has no configuration file of its own. Almost every setting is an environment variable read by the process that needs it, plus a handful of owner-only state files whose defaults derive from the vault path. Defaults are stated wherever the product has one. The one exception is the vault's own policy section, below.
Administrative policy#
The vault carries a policy section holding administrative rules applied before an operation. It is written with policy-set and read back with policy-get, and it is an enforcement surface rather than an open bag of operator metadata. The supported keys are a compiled registry, and a key the registry does not carry is refused rather than stored, because a rule an operator believes is in force and is not is worse than no rule at all. The registry checks the value as well as the name: a value the rule's reader could not consume would leave the rule visible and unenforced, which is the same defect.
Exactly one rule is registered today. A refusal names every supported key and the shape it demands, because withholding the allowed set only moves the guessing one step along.
| Key | Value | Meaning |
|---|---|---|
min_generated_length | A whole number | Minimum character count a generated value is expected to reach. policy-check-length decides a candidate against it and reports required, actual, and ok. With no minimum configured, required is null and ok is true. generate does not consult it, so a short value is produced and then checked rather than refused at generation. |
Vault and state#
| Variable | Meaning |
|---|---|
SKARBIEC_VAULT_FILE | Path of the encrypted vault. Default ~/.local/share/skarbiec/skarbiec.vault.json. An operator-route request may override it for exactly that request through its body's vault member. |
SKARBIEC_AUDIT_FILE | Path of the append-only, hash-chained audit journal. Default ~/.local/state/skarbiec/audit.jsonl. verify-chain always names the journal it read, because the default and an override are different files. |
SKARBIEC_ACQUISITION_FILE | Owner-only acquisition state: issued bearer hashes, their bindings, and expiry. Default is the vault file name with acquisitions.json appended, beside the vault. |
SKARBIEC_CAPABILITY_FILE | Capability broker state. Default is the vault file name with capabilities.json appended, beside the vault. |
SKARBIEC_CAPABILITY_ROUTES_FILE | The capability routes table. Default capability-routes.json beside the capability state file; routes help prints the path that resolves. |
SKARBIEC_SYNC_DIR | Git synchronization working directory. Default ~/.skarbiec-sync. |
Unlocking a protected key#
| Variable | Meaning |
|---|---|
SKARBIEC_UNLOCK | Unlock phrase for a passphrase-protected recipient key, for a single invocation. Handed to gpg over stdin, never on argv and never written to disk. |
SKARBIEC_UNLOCK_FILE | Owner-only file holding the same phrase, for a persistent service. With neither source an unprotected key decrypts normally and a protected key fails closed, without an interactive prompt. |
Acquisition#
| Variable | Meaning |
|---|---|
SKARBIEC_ACQUISITION_TTL_SECONDS | One-use bearer TTL, an integer from 1 through 300. Default 30. A value of zero or above 300 is refused. The TTL itself is not secret. |
Consumer files#
A service reads its bearer from an owner-controlled token file or its own environment. Tokens are never passed as command arguments. Workload-bound acquisition identities keep the private signing key with the workload and register only the public key.
Server surfaces#
The MCP server keeps its compatibility resolve path disabled until all three of its variables are set in the server process's own environment — never as tool arguments, so no bearer lands in a transcript, a log, or a child's argv.
| Variable | Meaning |
|---|---|
SKARBIEC_MCP_CONSUMER | Consumer identity the server gates by. |
SKARBIEC_MCP_TOKEN or SKARBIEC_MCP_TOKEN_FILE | That consumer's scoped grant, inline or from a file. |
SKARBIEC_MCP_OUT_DIR | Required absolute directory for emitted mode-0600 env files. A relative path is refused, so a launch directory cannot place files inside a repository. |
SKARBIEC_URL | Loopback API base the native host calls. Default http://127.0.0.1:8787. |
SKARBIEC_BROWSER_TOKEN_FILE | Owner-private token file of the browser consumer. Default ~/.local/state/skarbiec/browser-host-token. |
SKARBIEC_BROWSER_CONSUMER | Consumer name the native host presents. Default skarbiec-browser-host. |
Credential lifecycle#
| Variable | Meaning |
|---|---|
STADO_FORWARDS_DIR | Directory of forward files. Default ~/.stado/forwards. Remote credential calls resolve their endpoint from the skarbiec.local forward in that directory; the bridge resolves Weles admission from weles-admission.local beside it. |
SKARBIEC_CREDENTIAL_TOKEN_FILE | Owner-only file holding the bearer for remote credential calls, the alternative to naming a token file on the command line. |
SKARBIEC_WELES_CREDENTIAL_COMMAND | Absolute, owner-controlled, non-symlink executable implementing the skarbiec.credential-operation.v3 bridge. Anything else is refused before an operation starts. |
Diagnostics, receipts, and bounds#
| Variable | Meaning |
|---|---|
SKARBIEC_WORM_RECEIPT_DIR and SKARBIEC_WORM_CHECKPOINT | Enable write-once receipt checking in doctor. With either unset, doctor reports not_configured, which is deliberately not a failure. |
SKARBIEC_OPENSSL | Path of the openssl binary when the preferred build lives somewhere unusual. |
SKARBIEC_HTTP_WORKERS and SKARBIEC_HTTP_QUEUE | Bound the active and waiting HTTP work. Defaults 16 and 32; a full queue is refused rather than allowed to consume cryptographic or descriptor capacity. |
SKARBIEC_CRYPTO_CONCURRENCY and SKARBIEC_GPG_CONCURRENCY | Bound all external cryptographic children and the GPG subset. Defaults 8 and 2. |
SKARBIEC_CRYPTO_TIMEOUT_SECONDS | Kills and reaps a cryptographic child after this many seconds. Default 30. |
SKARBIEC_READINESS_ITEMS | Comma-separated additional item ids that readiness must decrypt. |
SKARBIEC_READINESS_INTERVAL_SECONDS | How often readiness is re-measured. Default 60. |
SKARBIEC_RELEASE_URI and SKARBIEC_RELEASE_COMMIT | Build-time stamps reported by version. A source build reports them as null rather than guessing a coordinate. |
Synchronization#
Bonds move ciphertext documents and public metadata; they do not widen recipient sets or make a destination key capable of decrypting an item.
External tools#
Skarbiec requires gpg for per-recipient encryption, decryption, owner signatures, and key custody, and openssl for high-entropy bearer values. Both run only through a bounded executor with a deadline and guaranteed child reaping. Bearer, proof, and capability digests use shasum; the audit journal computes its own SHA-256 in process. oathtool is required only by totp, and breach checking is the only other shasum caller.