Vault syncs Bast-managed hosts, keys, and metadata between your machines. It is separate from cloud provider sync (GCP / AWS / Azure / box.ascii.dev / Upstash Box), which lives on the Sync tab (4).

Ciphertext is stored by Bast. The encryption passphrase never leaves your machine. Bast keeps a local copy in ~/.config/bast/vault-passphrase (mode 0600) so linked machines stay unlocked across launches. That file is a local secret equivalent to an unlocked key: protect the account that can read ~/.config/bast. Log out deletes it.

What syncs

Included	Not included
Managed hosts in `~/.ssh/bast/config`	External hosts in `~/.ssh/config`
Bast-managed keys in `~/.ssh/bast/keys/`	External keys under `~/.ssh`
Host labels, groups, tags, notes, preferences	Cloud VM inventory files
Cloud integration settings (filters, auto-sync flags)	Cloud credentials, SA JSON paths, Upstash API keys, host passwords, last-sync errors

External hosts and keys stay local until you promote them into Bast-managed ownership.

Link a machine

Open the Vault tab (3), or use the CLI:

bast vault login --email [email protected] --accept-terms

Enter your email.
On hosted bast.sh, accept the Terms of Service and Privacy Policy. Self-hosted API bases skip this step.
Paste the one-time code from email.
Choose a vault passphrase (and confirm it).

--json / --no-input require --accept-terms when talking to https://bast.sh.

Lost passphrase means the remote vault cannot be decrypted. Bast cannot recover it.

On first link, local and remote state are merged by stable IDs (ManagedID for hosts, key fingerprint for keys). True conflicts (same alias, different managed IDs) open a chooser in the TUI: keep this machine, keep remote, or cancel. Cancelling leaves the machine unlinked so you can link again. From the CLI:

bast vault pull --mode replace_local   # keep remote
bast vault pull --mode replace_remote  # keep this machine

Everyday use

On the Vault tab, Sync (or Sync now) pulls remote changes and then pushes local ones. Click the Link, Unlock, or Sync chip to run it, or click a secondary row twice to open that action. If the same alias or key name exists on both sides with different identities, Bast opens that same keep-local / keep-remote chooser instead of failing with a dead-end status. Linked machines also pull in the background after hosts load when a passphrase is available, and local edits debounce a push after a few seconds (push merges with the remote vault first). Opening Bast never waits on the network to show your hosts.

CLI still exposes pull and push separately:

bast vault status
bast vault pull
bast vault push
bast vault logout
bast vault passphrase          # rotate (needs current passphrase)
bast vault passphrase --force  # reset: encrypt this machine and overwrite remote

Change or reset the passphrase

Rotate when you still know the current passphrase. Bast decrypts the remote vault, re-encrypts it with the new passphrase, and uploads it:

bast vault passphrase

In the TUI: Vault → Rotate passphrase. If the session is already unlocked, only the new passphrase is requested.

Force reset when the old passphrase is lost, or you want this machine’s managed hosts/keys to become the remote vault under a new passphrase. This does not need the old passphrase. Remote-only data that is not on this machine is discarded:

bast vault passphrase --force

In the TUI: Vault → Reset passphrase, type RESET, then enter the new passphrase twice.

Other linked machines must unlock (or reset) with the new passphrase afterward.

Self-hosting

By default Bast talks to https://bast.sh. To keep vault storage on your own infrastructure, self-host the web app and set the API base in Vault → API base URL, with bast vault login --api https://your.origin, or with BAST_VAULT_API. Custom API bases do not show Ellipse terms.

Promote

External hosts and keys cannot enter the vault until Bast owns them.

Surface	Action
Hosts tab	`p` on an external host, or the detail affordance
Keys tab	`p` on an external key (managed keys still use `p` for passphrase)
CLI	`bast hosts promote <host>` · `bast keys promote <key> [--name name]`

Promote copies into Bast-managed config/keys. The original external SSH config block or key file is left in place.

Encryption

Passphrase → Argon2id → 256-bit key
Vault document sealed with XChaCha20-Poly1305
Server stores only the opaque envelope (plus revision metadata in Redis and the blob in object storage)

Session tokens live in ~/.config/bast/vault-session.json (mode 0600) and authorize upload/download of ciphertext only.

Vault