Access
Vault
Vault is Swarm's password-gated protection for saved provider credentials. It protects API keys, OAuth tokens, refresh tokens, account IDs, active credential selections, and other local auth records. Vault is not a generic facts, notes, or memory database; it is the credential vault behind /auth and the credential bundle path used by Swarm Sync.
Vault replaces local key-file unlock with a password-gated credential unlock.
Swarm seals saved credential records before writing them to the local secret Pebble store. Without Vault, the data-encryption key is wrapped by a local key file next to the secret store. With Vault enabled, that same data-encryption key is wrapped by a password-derived key, so copied local data cannot be read without the Vault password.
When Vault is locked, normal credential-dependent runtime APIs are blocked until you unlock it. Swarm keeps the decrypted key in memory only for the current app run, or until you lock Vault manually.
Bottom line: saved Swarm credentials are encrypted at rest. Vault adds a user password requirement for unlocking those credentials instead of relying only on the local key-file path.
Use /vault to turn Vault on, unlock it, lock it, disable it, export, or import.
/vault/vault export.swarmvault bundle./vault export <path>/vault import <file>
If Vault is off, /vault opens setup. Press Enter, set a password, and confirm it. If Vault is
enabled but locked, /vault prompts for the Vault password. If Vault is enabled and unlocked,
the status panel lets you export, import, lock, or disable it.
Exports are encrypted credential bundles, not plaintext credential dumps.
/vault export prompts for an export password and writes a .swarmvault file. By default,
Swarm writes to ~/Downloads/Swarm/swarm-credentials-YYYYMMDD-HHMMSS.swarmvault. You can pass an
explicit path with /vault export <path>.
The export bundle includes saved credentials and active credential IDs. The bundle is encrypted with a password-derived key. Move it only as long as needed, and delete it after importing on the target machine.
/vault import <file> prompts for the export password. If local Vault is enabled, Swarm also asks for
the local Vault password; pressing Enter reuses the import password. If Vault is off and a Vault password is provided,
import can enable Vault while placing the imported credentials.
Vault uses password wrapping around Swarm's credential data-encryption key.
Credential sealingCredential records are sealed with XChaCha20-Poly1305 before they are stored.Password key derivationVault derives the password wrapping key with Argon2id and a per-vault salt.Unlock lifetimeUnlocking caches the decrypted data-encryption key in memory until Vault is locked or the app exits.Locked runtimeWhen Vault is enabled and locked, Swarm gates normal API access until Vault is unlocked.Swarm Sync reuses the Vault export/import path to keep child swarms managed by the host.
When Swarm Sync is enabled for a child swarm, the host remains the source of truth for synced auth state. The host exports an encrypted credential bundle, and the child imports it as managed credentials owned by the host swarm ID.
If the host Vault is enabled, the sync setup asks for the host Vault password so the host can decrypt and export credentials into the managed bundle. The child stores synced credentials in its own local auth store and can also use Vault protection locally.
Swarm Sync can also mirror agent profiles and custom tool definitions when those sync modules are enabled. Those modules are separate from Vault itself; Vault specifically protects the saved provider credentials used by synced auth.
Managed sync is not a second independent auth authority. Synced credentials are marked as managed by the parent swarm, and stale managed credentials can be removed when they disappear from the host bundle.
The local runtime exposes Vault status and operations through /v1/vault routes.
GET/v1/vaultPOST/v1/vault/enablePOST/v1/vault/unlockPOST/v1/vault/lockPOST/v1/vault/disablePOST/v1/vault/exportPOST/v1/vault/import