Quickstart

This walkthrough takes you from a fresh install to a running stillvault get call in about ten minutes. You need: a Linux or macOS host, and an Android phone (iOS support in progress).

1. Install the broker and consumer wrapper

# Download the latest release for your platform.
# Exact package manager support is coming — for now, install from the release tarball.
curl -fsSL https://stillvault.wolstapp.com/install.sh | sh

# Verify the broker binary is on PATH.
stillvault --version
# stillvault-enroll is installed alongside it.
stillvault-enroll --version

Flags are stabilising. Where exact flags are not yet fixed, comments note this. Check stillvault help and stillvault-enroll help for the current surface.

2. Create an Org Identity key and enroll your phone

The Org Identity key is a P-256 keypair you hold — the private key never leaves your machine. It anchors that every request is authentic and not vendor-substituted.

Your phone must be present for this step: stillvault-enroll initiates a WebAuthn ceremony that derives the per-secret unwrap key from a biometric-gated passkey.

# Run the enrollment ceremony. This will:
#   1. Generate an Org Identity keypair and write the private key to a local store.
#      (Location is configurable — default: ~/.config/stillvault/org-identity.key)
#   2. Open a browser page for the passkey enrollment ceremony.
#   3. Wrap the DEK for your first secret to your enrolled passkey.
stillvault-enroll init --org <your-org-name>

# Phone present: tap the passkey prompt on your phone to complete biometric
# verification and finalize the enrollment. The DEK wrapped to your key is written
# to the store — the broker never sees an unwrapped key.

3. Seal a first secret

# Seal a secret. The value is read from stdin so it never appears in shell history.
stillvault-enroll seal --name db/prod/password
# Enter secret value: <type your secret, then Ctrl-D>

# The sealed store (ciphertext + wrapped DEK envelope) is written to the broker.
# The broker holds only ciphertext. Neither it nor the control plane can decrypt.

4. Retrieve the secret — phone tap required on first access

# Request the secret. The consumer wrapper opens a Unix socket, mints an ephemeral
# keypair, signs the request with the Org Identity key, and sends it to the broker.
stillvault get db/prod/password
# A push notification arrives on your enrolled phone.
# Tap it, authenticate with biometric, and the plaintext is printed to stdout.

The push notification shows:

• Which secret: db/prod/password
• Which process: the uid, pid, and exe of the calling process (via SO_PEERCRED)
• Which host: your machine hostname
• When: the request timestamp

Verify all fields match what you expect before approving. One approval releases exactly one named secret.

5. Repeat access within the lease TTL — no phone needed

# Within the lease window, the wrapper serves from its local RAM cache.
# No network call, no phone tap.
stillvault get db/prod/password
# <plaintext printed immediately>

# When the lease expires, the next get triggers the push again.

The lease lives entirely in the consumer wrapper’s non-swappable RAM. The control plane enforces the maximum TTL policy; your local wrapper wipes the plaintext when the TTL elapses.

What happens at each step

The vendor relay never sees plaintext or an unwrapped DEK at any point in this flow.