From invitation
to a scoped receiver.

1. Accept your invitation

Open the invitation on the app origin provided by the operator. 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.

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

The first 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. Service acceptance is still pending: use the accepted API origin supplied with your invitation.

When the operator publishes the accepted site's downloads, get the version 0.1.0 archive, SHA-256 checksum and source/version metadata. Until publication, the operator supplies those files with the invitation. 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. Linux, Intel Macs and other platform variants are not offered here.

Once the accepted CLI is installed, these are the intended commands. Replace the placeholders with the operator-confirmed origin and resource references:

vaultperch login --origin API_ORIGIN --email OWNER_EMAIL
vaultperch enroll-start --origin API_ORIGIN --label receiver
vaultperch enroll-complete --origin API_ORIGIN

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 service on the tested macOS configuration, 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 API_ORIGIN --vault VAULT_UUID
vaultperch import --origin API_ORIGIN --vault VAULT_UUID \
  --label credential --file /private/location/credential
vaultperch delivery-create --origin API_ORIGIN --vault VAULT_UUID \
  --credential CREDENTIAL_UUID --mode run
vaultperch run --origin API_ORIGIN --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 accepted CLI uses the rule to create a shared credential reference:

vaultperch handoff --origin API_ORIGIN --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 API_ORIGIN --vault DESTINATION_VAULT_UUID \
  --credential SHARED_CREDENTIAL_UUID --mode run
vaultperch run --origin API_ORIGIN --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 API_ORIGIN --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 upcoming pilot. The locally implemented recovery procedure below still requires hosted acceptance.

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.