Pocket-Vault docs

Getting started

Pocket-Vault is a Mac app that keeps your credentials in an encrypted vault and lets AI coding tools and scripts use them under rules you set. Its command-line tool is built in.

Requirements and availability

• macOS 11 or later. No account and no internet connection; everything runs on your Mac.
• Windows is not supported yet. The command-line tool passes its automated tests there, but the desktop app is macOS only.
• Version 1.0 is complete and awaiting distribution, so there is no public download yet. To hear when it is available, email us.

First run

With no vault on your Mac, Pocket-Vault opens a five-step Welcome screen.

1. Create your vault. Choose a passphrase of at least 12 characters, repeat it under Confirm passphrase, and press Continue. Longer is better than complex.
2. Your recovery key. It is shown once, and it is the only way back in if you forget your passphrase. Write it down somewhere that is not this computer, tick I have written this down, and press Continue.
3. Secrets already on this Mac. Press Skip for now.
4. Connect an AI tool. Press Skip for now.
5. Done. Press Open Pocket-Vault and unlock with your new passphrase. Creating a vault does not leave it open.

Unlocking and locking

• Type your passphrase and press Unlock. While the vault is unlocked, the programs you have allowed can use it.
• Lock in the top bar locks it now, and Pocket-Vault locks itself after 15 minutes without use. Locking withdraws every live permission.
• Closing the window does not quit: Pocket-Vault leaves the Dock and keeps running from its menu bar icon, so your tools keep working. That menu has Open Pocket-Vault, Lock now, Advanced mode, and Quit Pocket-Vault. Quitting locks the vault, and your tools stop until you open and unlock it again.

Simple and Advanced

Simple mode has five screens: Home, Secrets, Tools, Settings, and Help. Advanced mode adds Access, Audit, Rules, and Simulator. Switch in Settings or from the menu bar icon; it shows more, never allows more. The Help screen is also under Help → How to use Pocket-Vault in the menu bar.

Storing secrets

The Secrets screen lists names and details only. A value appears only when you press Show.

Add a secret by hand

1. Open Secrets and use the Add a secret panel.
2. Enter a Name. It is the name tools ask for, and the environment variable a command receives.
3. Paste the Value and pick a Risk: low, medium, high, or critical. Under the starter rule, connected tools use Low and Medium secrets on their own and ask you about High and Critical ones.
4. Pick a Kind (such as api_key or password) and a Project, or This Mac for none.
5. Optionally press Check the value first, then press Add.

Scan this Mac

1. On Secrets, press Scan this Mac, then Scan this Mac in the panel that opens. To search one folder, choose or choose a folder…, enter the path, and press Scan.
2. Pocket-Vault lists the .env files, SSH keys, and cloud, npm, database, Docker, and Kubernetes credential files in your home folder — names and kinds only, nothing ticked.
3. For a .env file, press show lines. Its lines are sorted into Credentials, ticked, and Hidden: settings such as ports, switches, paths, and timeouts, plus names you hid. Tick either way. Hide a name and it is never offered again.
4. Tick the files you want, or press Select all, and press Import N selected.

A .env file is imported line by line; any other file is stored whole. Each lands in a project named for its folder — ~/code/acme/.env goes into acme — or in This Mac for files in your home folder or its hidden folders. Risk levels are set from what Pocket-Vault recognizes. The original files are never changed or deleted; delete them yourself once nothing reads them.

Projects

Move a secret with its Filed under menu, which also offers New project…. Rename a project from its heading with Rename; Delete works once it is empty. Projects are for filing and do not change who may use what, but they set which names a connected tool is told about: the secrets filed under the project with that folder’s name.

Show, Check, and Verify

• Show brings a value back for 30 seconds, then hides it. Every Show is recorded, and there is no copy button, on purpose.
• Check says whether a secret looks like a real credential of its kind — a recognized format from more than thirty providers, a valid built-in checksum, an unexpired token — or a placeholder, stray quotes, or a key cut short. It sends nothing anywhere, so plausible means shaped right, not proven to work.
• Verify (beta) appears in Advanced mode once Live key checks is on in Settings. It sends that one key to its issuer — OpenAI, Anthropic, GitHub, GitLab, Groq, Hugging Face, Stripe, Slack, or npm — and reports whether they accepted it. Verify all does the same for every recognized key after you confirm the count. This is the only feature that sends a secret anywhere, and each request is recorded.

Clean up

• Remove settings, then Remove them, deletes stored entries that look like settings — timeouts, flags, modes — records each deletion, and hides the names from future scans.
• Delete, then Delete for good, removes one secret. Backups made earlier still hold it.

Connecting an AI tool

A connected tool gets secrets from the vault instead of from .env files or your chat. It asks for permission to run a command; Pocket-Vault runs it with the secret in its environment and hands back the output and exit status, not the secret.

Connect a tool

1. Make sure Pocket-Vault is running and unlocked.
2. Open Tools. Under AI tools, press Connect on the Codex or OpenCode card, or Connect a project on the Claude Code card. A tool already set up offers Connect again or add a project.
3. Enter the Project folder you work in. Claude Code needs one; for Codex and OpenCode it is optional, and worth giving.
4. Press Connect, and confirm with Touch ID, your Apple Watch, or your login password.

Connect then:

• Writes the tool’s settings — .mcp.json in the project folder for Claude Code, ~/.codex/config.toml for Codex, ~/.config/opencode/opencode.json for OpenCode. Codex’s entry lets it use Pocket-Vault without asking you on every call.
• Allows the two programs inside the app that tools talk through, including the pocket-vault command-line tool.
• Installs the starter rule, if it is not there yet.
• Writes a note into CLAUDE.md (Claude Code) or AGENTS.md (Codex and OpenCode) in the project folder, telling the tool to get secrets from the vault, never to ask you to paste one, and which secret names it may ask for. Values never leave the vault.

The first time Claude Code opens that folder, it asks whether to use the new pocket-vault server. Approve it.

The starter rule

A connected tool may run commands with Low and Medium risk secrets on its own, for up to an hour at a time, then asks again. Each High or Critical secret asks you on Home, by name, and so does anything in an environment marked production — set only from the command line. Your own rules still apply, and a deny always wins. On the Rules screen it is the Pocket-Vault AI tools policy; switch it off there and Connect leaves it off.

Connect the project again whenever you add a secret. That refreshes the names in the note and adds the ask-first rule for a High or Critical secret. Until then, the tool is refused that one secret.

What a tool may report

Codex runs shell commands in a sandbox that cannot reach Pocket-Vault, so pocket-vault run does not work inside Codex. Its Pocket-Vault connection does, and the note tells Codex to use it.

Approvals, programs, and rules

Answer a request

A request a rule says to check with you appears on Home under Asking you now, with a count beside Home in the sidebar. Each card says who is asking and for which secrets, and quotes the requester’s stated purpose — the program’s own words, marked unverified, which never decide anything. Press Approve or Refuse. Nothing is granted while you are away, and an unanswered request expires. Recently, below, lists the last 20 events in plain sentences.

Decide which programs may ask

Tools → Programs this vault knows lists every program that has tried to connect. A new one is recorded as Blocked; being listed is not being let in.

1. Open the program’s Can it ask? menu.
2. Choose Allowed and press Allow it, or choose Blocked to refuse it at once.
3. Confirm with Touch ID, your Apple Watch, or your login password.

The third choice, Waiting for you, also refuses the program and shows as Not allowed. A program is recognized by its location and a fingerprint of its file, checked on every connection; if the file changes, it is blocked until you allow it again.

Access, Audit, and Simulator

These screens appear in Advanced mode.

• Access lists every permission issued (the screen calls them capabilities). Revoke withdraws a live one, and its next use is refused; Lock withdraws all of them. A command already running keeps what it was given until it ends.
• Audit shows the last 200 events: what asked, for what, the decision, and why. The record is chained, so an entry edited or removed from the middle is detected; the screen then says The audit chain does not verify. It is reported, never repaired.
• Simulator lists programs that asked what would be allowed in the last hour. Many questions from one program suggest it is mapping which secrets need your approval. It blocks nothing.

Rules

Rules decide what a program may use, and when to ask you first. A request no rule allows is refused; nothing is quietly allowed. In Advanced mode, Rules shows the whole set as JSON, switched-off policies included.

1. Edit the text.
2. Press Import, then Replace.
3. Confirm when macOS says Pocket-Vault is trying to replace the vault’s access rules.

Import replaces the whole set; an empty set refuses everything. Discard changes drops your edits. A rule can match a program, project, environment, secret name or kind, maximum risk, kind of use, production flag, and maximum duration, and answers allow, deny, or require_approval. A deny always wins, and asking outranks allowing. A request’s stated purpose is never matched on. For a template, run pocket-vault policy example.

The command line

The command line is optional. It is inside the app at /Applications/Pocket-Vault.app/Contents/MacOS/pocket-vault; these docs call it pocket-vault. A secret’s value is never typed into a command — it comes from a hidden prompt, standard input, or a file — so it stays out of your shell history.

While the app is unlocked

These commands ask the vault, the same way an AI tool does. Connecting any AI tool allows the command-line tool and gives it the starter rule.

• Repeat --secret for more than one. A permission lasts 900 seconds unless you pass --duration.
• Output containing a supplied value comes back as [REDACTED].
• If a rule asks you first, run waits up to 120 seconds for your approval on Home; --wait 0 stops at once.
• run exits with the command’s own exit code, so it works in scripts.

With the app quit

These commands change the vault directly and need it to themselves. Quit Pocket-Vault from the menu bar first, or they stop with a pocket-vault daemon is holding this vault — stop the daemon first. Each asks for your passphrase.

SSH keys

Pocket-Vault can be your SSH agent, signing with a key kept in the vault. It runs only under pocket-vault daemon, so quit the app first, and it takes unencrypted Ed25519 keys only.

1. Store the key: pocket-vault add deploy_key --from-file ~/.ssh/id_ed25519 --kind ssh_private_key. RSA, ECDSA, and passphrase-protected keys are refused by name.
2. Save the output of pocket-vault policy show to a file. Add a rule to a policy’s "rules" list with its own "id", "effect": "allow", "operation": "sign", and "secret_kind": "ssh_private_key", then load the file with pocket-vault policy import. The agent offers only keys a rule allows.
3. Allow your SSH client — for the one in macOS, pocket-vault enroll /usr/bin/ssh.
4. Run pocket-vault daemon --ssh-agent and paste the export SSH_AUTH_SOCK=… line it prints into your shell.

Every signature is one rule check and one recorded event. Restart the daemon after changing rules.

Backups and recovery

Automatic backups

The app copies the vault and its record at its first unlock after starting, and before any change to the vault’s format; pocket-vault daemon copies them at every start. The newest ten are kept in ~/Library/Application Support/PocketVault/backups. If a backup cannot be written, the app will not unlock.

A backup copies files that are already encrypted. Values stay sealed, but names, kinds, risk levels, project names, and timestamps are as readable as in the vault, and a backup keeps credentials you have since replaced. It guards against a damaged vault, a failed update, or a mistaken delete — not a lost disk.

Backup commands

Quit the app first, except for backup list.

Restoring deletes nothing: the current vault and record are renamed aside with pre-restore and a timestamp, and both paths are printed. Permissions are not restored — every one comes back revoked and every allowed program comes back blocked — so connect your tools again afterward.

If you forget your passphrase

1. Quit Pocket-Vault from its menu bar icon.
2. In Terminal, run pocket-vault recover and enter your recovery key.
3. Set a new passphrase; the command does not finish without one. The old passphrase is removed.
4. Open Pocket-Vault and unlock with the new passphrase.

The recovery key still works afterward. If anyone may have seen it, run pocket-vault slot add recovery, then slot remove ID for the old one (slot list shows which). Earlier backups still open with the old passphrase.

pocket-vault rotate re-seals everything under a new vault key — worth doing if a copy of the vault’s files may have got out. Lose every way in and the vault stays encrypted, with no back door and no one to ask.

Settings, privacy, and data

Settings

Auto-lock is always on in the app, at 15 minutes without use.

What is stored, and where

Everything lives in ~/Library/Application Support/PocketVault, readable only by your macOS account: the vault, the record, backups, and two small preference files. Secret values are encrypted one by one, under a key never written to disk unprotected; your passphrase and recovery key are never stored. Names, kinds, risk levels, project names, and timestamps are not encrypted, so the app can list them without opening any value. The record holds identifiers and decisions, never values.

What leaves your Mac

Nothing, unless you use Verify. There is no account, sync, telemetry, or analytics. Verify (beta) sends one key to its issuer, over an encrypted connection, only when you press it, and records the sending and the answer. Keep in mind:

• The note Connect writes lists secret names. Commit CLAUDE.md or AGENTS.md to a public repository and those names, which hint at the services you use, become public.
• A command given a secret holds it while it runs. Output scrubbing is a safety net: an encoded or split-up value can get past it.
• Pocket-Vault is not a sandbox: a program already running as you can read what you can read. Nor is it a password manager for your logins, and it has no bulk export.

Troubleshooting and help

Messages

Common questions

• A tool is refused one secret. It is probably High or Critical and newer than your last connect. Connect the project again.
• Tools stopped working after Pocket-Vault was updated. Programs whose files change are blocked until allowed again, including those inside Pocket-Vault. Connect your tools again.
• How do I change a secret’s risk level? Delete it and add it again, or write a rule for it on Rules.
• A scan row shows an error. That file was not stored — say, an unusable SSH key, a file over 1 MB, or the GitHub CLI’s token file, which the scan lists but cannot import. The rest still import. If the report says stopped early, there was more to see, scan a narrower folder.

Getting help

For questions, problems, or a security concern, email us. Never include a secret’s value.