From invitation
to a scoped receiver.

1. Accept your invitation

Open your emailed invitation at https://app.vaultperch.com. Choose whether the owner is a person or an agent, enter the invited email address, and create a password of 15–128 characters. Common passwords are rejected. Confirm the verification email explicitly, then sign in.

If invitation, verification or password-reset mail is missing, check your spam folder for VaultPerch mail from verify@auth.vaultperch.com. Dev uses verify@auth.dev.vaultperch.com.

Keep the mailbox and bootstrap password custody independent of this vault. An agent owner can use the same authenticated API and authorized mailbox; browser interaction is not a proof-of-human requirement.

2. Create the scope

1. Create a vault with a name and environment label, such as a synthetic development workspace. These labels do not prove provider-side scope.
2. Create a principal for the agent or workload.
3. Grant that principal access to the vault with only the needed permissions and an expiry. The initial browser offers metadata listing, import, runtime receiving and handoff creation with explicit run and optional save modes. Save permits a persistent protected copy on the receiver.
4. Use the import form to enter a credential value in its dedicated hidden input. Only credential metadata is displayed afterward.

Sensitive administration requires a password confirmation if the previous confirmation is more than five minutes old. Confirm, then submit the intended action again.

3. Install and enroll the receiver

Choose the archive for your platform. Both require Node.js 24 already installed and include the CLI dependencies and license notices. Use https://api.vaultperch.com as the API origin.

macOS with Keychain

The macOS installation archive is for Apple Silicon Macs running macOS 14 or later with Node.js 24 installed. It includes the CLI's JavaScript dependencies, executable launcher, native Keychain helper and third-party license notices. No npm installation or Swift compiler is needed to run it.

Download the version 0.1.0 archive, SHA-256 checksum and source/version metadata. The metadata records the archive checksum, version, source inputs and supported platform. In their download directory, verify before extracting:

shasum -a 256 -c vaultperch-cli-0.1.0-darwin-arm64.tgz.sha256
tar -xzf vaultperch-cli-0.1.0-darwin-arm64.tgz
export PATH="$PWD/vaultperch-cli-0.1.0-darwin-arm64/bin:$PATH"
vaultperch --help

Proceed only if the checksum succeeds. Keep the extracted directory together in a private location; add its absolute bin path to your shell configuration for future shells. Do not move or symlink the launcher alone. Default custody requires a working unlocked macOS Keychain. The CLI stops if Keychain or its helper is unavailable; it does not fall back to an ordinary file. Intel Macs are not offered here.

Ubuntu with explicit file custody

The Linux archive supports Ubuntu 24.04 x64 with Node.js 24. Download the version 0.1.0 Linux archive, SHA-256 checksum and source/version metadata. In their download directory:

sha256sum -c vaultperch-cli-0.1.0-linux-x64.tgz.sha256
tar -xzf vaultperch-cli-0.1.0-linux-x64.tgz
export PATH="$PWD/vaultperch-cli-0.1.0-linux-x64/bin:$PATH"
vaultperch --help
mkdir -m 700 "$HOME/.vaultperch-pilot"

Proceed only if the checksum succeeds. Keep the extracted directory together in a private location. No npm installation or native helper is needed. Use a new custody directory owned by the running OS user with mode 0700. State files use 0600; the same OS user can read stored private keys and tokens. Use a dedicated OS user for mutually untrusted workloads.

On Linux, add --service-account-dir "$HOME/.vaultperch-pilot" to every authenticated command below, before any -- consumer arguments. For example:

vaultperch login --origin https://api.vaultperch.com \
  --service-account-dir "$HOME/.vaultperch-pilot" --email OWNER_EMAIL
vaultperch enroll-start --origin https://api.vaultperch.com \
  --service-account-dir "$HOME/.vaultperch-pilot" --label receiver
vaultperch enroll-complete --origin https://api.vaultperch.com \
  --service-account-dir "$HOME/.vaultperch-pilot"

This Ubuntu configuration passed synthetic local checks; a hosted Linux receiver journey has not yet been verified. Linux Secret Service, hosted MCP and native HOS integration are upcoming. Other Linux distributions and architectures are not offered here.

Enroll your receiver

The following examples use macOS Keychain. On Ubuntu, include the explicit directory option shown above on every authenticated command. Replace OWNER_EMAIL with your invited email and resource placeholders with the metadata IDs from your account:

vaultperch login --origin https://api.vaultperch.com --email OWNER_EMAIL
vaultperch enroll-start --origin https://api.vaultperch.com --label receiver
vaultperch enroll-complete --origin https://api.vaultperch.com

Between start and completion, enter the exact enrollment ID in the browser and select Preview receiver for comparison. Compare the preview label, enrollment ID, pairing code and public-key thumbprint with the intended receiver over a trusted channel. Confirm the comparison, assign its principal, then approve. The pairing code is a comparison aid, not permission to approve. The private key and polling token stay in receiver custody. If completion is pending, wait at least five seconds before trying again.

For an unattended macOS service, or any authenticated Linux command, explicitly select --service-account-dir /absolute/private/directory on every command. Use a dedicated OS user. The directory must already be owned by that user with mode 0700; state files use 0600. Keep paths and custody separate for separate workloads.

4. Use protected inputs and outputs

vaultperch credentials --origin https://api.vaultperch.com --vault VAULT_UUID
vaultperch import --origin https://api.vaultperch.com --vault VAULT_UUID \
  --label credential --file /private/location/credential
vaultperch delivery-create --origin https://api.vaultperch.com --vault VAULT_UUID \
  --credential CREDENTIAL_UUID --mode run
vaultperch run --origin https://api.vaultperch.com --delivery DELIVERY_UUID \
  --exec /absolute/path/to/consumer -- consumer-argument

Never put credential values, passwords or tokens in command arguments, chat or logs. Protected import also supports an explicit input pipe. By default, run injects the payload through descriptor 3, identified by VAULTPERCH_SECRET_FD, and suppresses child output. A trusted receiving process can still copy or expose its input. A delivery acknowledgment does not prove that a provider action succeeded.

Two-device handoff

1. Enroll the source and receiving devices separately, under their intended principals. Create source and destination vaults with the same environment label. Import an owned credential into the source vault.
2. Grant the source principal handoff:create on the source vault. Grant the recipient metadata:list and runtime:receive on the destination vault, with each delivery mode you intend to use.
3. In the browser's handoff-rule form, select the source vault, owned source credential, source principal, destination vault and recipient. Set a short expiry, the delivery modes and a maximum shared-entry count. Create the rule and copy its metadata ID.

On the source machine, the CLI uses the rule to create a shared credential reference:

vaultperch handoff --origin https://api.vaultperch.com --rule RULE_UUID

On the receiving machine, use the returned shared credential ID and the destination vault ID to create a delivery:

vaultperch delivery-create --origin https://api.vaultperch.com --vault DESTINATION_VAULT_UUID \
  --credential SHARED_CREDENTIAL_UUID --mode run
vaultperch run --origin https://api.vaultperch.com --delivery DELIVERY_UUID \
  --exec /absolute/path/to/consumer -- consumer-argument

If save is explicitly allowed by both the rule and destination grant, request --mode save, then use vaultperch save --origin https://api.vaultperch.com --delivery DELIVERY_UUID --output /private/location/new-file. Its parent directory must be owned by the receiver user with mode 0700; the CLI creates a new 0600 file and refuses an existing destination. The shared reference contains no plaintext credential. Revoking the source credential or rule stops future deliveries; a saved copy remains in receiver custody.

5. Revoke and recover

Use Revoke VaultPerch access on a credential, enrollment, principal, grant or handoff rule. Review the refreshed metadata after a response loss before submitting again. Revocation stops new VaultPerch admissions. Rotate or retire the credential with its provider if a receiver may already hold it.

Password-reset requests do not alter an account. Open the emailed reset link and explicitly submit a new password. The standard choice invalidates owner sessions while keeping agent enrollments; select compromised-account recovery to revoke enrollments, grants and handoff access and quarantine credential use. After signing in again, review surviving inventory, create fresh grants and approve/complete fresh receiver enrollment, then select reviewed activation in the recovery section. Neither choice retires a provider credential.

If your mailbox is lost, contact support@vaultperch.com through an existing trusted channel. Recovery requires continuity evidence and may be refused. Encryption-key loss is not repaired by a password reset. Owner export is not offered by this first increment. Follow the recovery procedure below for owner inventory snapshots and restore.

6. Review and restore inventory

The recovery section shows whether credential use is active or quarantined. You can explicitly create an encrypted snapshot and list available snapshot metadata. A snapshot is not an owner-held export and has no recovery-time SLA.

1. Confirm your password, list snapshots, and choose the exact snapshot you intend to restore.
2. Read and acknowledge the destructive restore warning, then confirm restore. It replaces inventory and can lose newer data, preserves the current owner password and revocation history, ends all sessions, and keeps restored grants, enrollments and handoff rules inactive. Revoked credentials are dropped from the restored inventory.
3. Sign in again with the current password. Review surviving credentials, create fresh grants and approve/complete fresh receiver enrollments while credential use remains quarantined. Recreate only the handoff rules you still intend to allow.
4. Confirm that the inventory and new access are reviewed, then activate. The app reads the current recovery head immediately before submitting activation.

If the restore fails or remains prepared, activation is blocked. Contact support to repair the cause and complete a successful restore. Do not activate incomplete inventory or assume that a lost response means success. After a compromised-account reset, review and prepare fresh access in the same way; no snapshot restore is required unless you explicitly choose one. Password reset does not reconstruct lost encryption keys.