Helix Vault

Orchestrator cloud context (check before setup)

If HELIX_ORCHESTRATOR_RUN_ID or HELIX_SKILL_CREDENTIAL_FILE is set, this skill runs in Helix Console. This section takes precedence over local setup and browser instructions below.

• First call the plugin's bin/helix orchestrator-protocol (Windows: bin/helix.cmd orchestrator-protocol). It must print 1. Otherwise stop with an actionable request to update the Helix plugin/CLI; never run an older binary's setup commands.
• Use the normal helix <surface> up, push, state, and wait commands. The CLI selects cloud transport and the assigned project automatically. Keep the same slug within this task.
• Do not start local servers or Fleet, open a browser, curl localhost, use --local, log in, or change profiles/projects. Do not read or print the credential file. Do not remove the injected environment variables.
• up returns the Console session URL. Use that URL wherever the local instructions request Board/Fleet links. Events go to Console; human responses and gate approvals still come from the person through the normal wait protocol.
• On cloud or compatibility errors, report the error. Never fall back to local mode. Outside this context, follow the local behavior below unchanged.

You reference secrets. You never read them.

Vault is not a place to fetch secrets from — it is a broker that uses them on your behalf. A value goes into one command's environment at the moment it runs, and nowhere else. The command line, the tool output and the transcript never hold a plaintext value; the audit log holds the name and the fact it was used.

There is no reveal. Not for you, not for anyone. If you find yourself wanting the value itself, the answer is one of the two paths below, or the task changes.

Setup

Call the binary by its full path every time:

${CLAUDE_PLUGIN_ROOT}/bin/helix vault <verb> [flags]

On Windows, ${CLAUDE_PLUGIN_ROOT}\bin\helix.cmd in place of bin/helix; the rest of the command is the same.

Never put it in a shell variable or function. The skill pre-approves this command, and that approval stops matching past a variable assignment — wrap it and every call prompts instead. Prose below names commands as vault <verb>; run them with the full path.

First use creates a master key in the OS keychain. On a machine where the keychain prompts, the person will see a dialog — tell them it is coming rather than letting it surprise them.

--session is not needed: the session comes from the host, so a grant that covers "this session" genuinely does.

The one thing to do when you need a credential

${CLAUDE_PLUGIN_ROOT}/bin/helix vault need db/staging --reason "to run the pending migrations" --wait 300

Then stop. That is the point: you hit a wall, a request is now waiting for a person, and you are blocked behind it. The reason is in your own words and it is what the person reads when deciding.

Three answers come back:

Never ask the person to paste a secret into the conversation. That is the exact thing this exists to prevent — a value in the transcript is there forever. Point them at vault pending, or at the browser surface.

Using it — two paths, no third

Run a command with it:

${CLAUDE_PLUGIN_ROOT}/bin/helix vault run --with DATABASE_URL=db/staging -- ./migrate.sh

The value is in that process's environment and nowhere else. If the command prints it, the output is masked on the way back to you.

Get it into a file:

# write a template of names, never values
printf 'DATABASE_URL=${vault:db/staging}\nAPP_ENV=staging\n' > .env.template
${CLAUDE_PLUGIN_ROOT}/bin/helix vault render .env.template --out .env

The CLI does the substitution; the value never passes through you. It refuses to write anywhere git would pick up, and the file is destroyed when the session ends unless --keep is passed — which is itself recorded.

Anything neither path reaches is a case to raise with the person, not to route around.

What the person does

${CLAUDE_PLUGIN_ROOT}/bin/helix vault pending                     # the queue of blocked agents
printf %s '<value>' | ${CLAUDE_PLUGIN_ROOT}/bin/helix vault provide <req>    # answer one
${CLAUDE_PLUGIN_ROOT}/bin/helix vault decline <req> --reason "<why>"         # a real answer
${CLAUDE_PLUGIN_ROOT}/bin/helix vault list · show <name> · audit             # never a value, always a shape

Or in the browser, which is where this is meant to happen:

${CLAUDE_PLUGIN_ROOT}/bin/helix vault serve --port 4860

A value never goes on a command line — it is read from stdin, and --value is refused with the reason. If you are writing a command for a person to run, write the printf %s '…' | form.

Layers and grants

One vault per machine, at ~/.helix/vault — the same store and the same server whichever project you are in. The project is a scope inside the vault, named after the repo directory; nothing vault-related is ever written into a repo.

Secrets live at project, team or organisation; most specific wins. Inheritance is opt-in — a secret above your scope is invisible unless it has been granted to it. Nothing is reachable by accident, and specifically: a project asking for a name never resolves upward to a production credential it was never meant to touch.

A grant covers one session by default. Anything wider is a deliberate choice with a visible expiry. Revocation stops resolution immediately.

The audit log

Every resolution captures which agent, in which session, running which command, resolving which layer, granted by whom. vault audit reads it back. This is what makes "which agent touched the production database key, and when" answerable — it is the product, not a by-product, so do not paper over it.

Actions by a person are attributed to the account running them. Nobody is asked to type their own name on a machine with one person on it.

Hooks

vault hook install prints the settings.json fragment:

• PreToolUse rewrites shell commands to run inside a wrapper that masks this session's secrets out of their output. It rewrites nothing when the session holds no secrets, so ordinary sessions are untouched. Masking cannot be done afterwards — a post-tool hook can observe or block, but it cannot rewrite what you have already been shown.
• SessionEnd destroys the files this session rendered.

Sharp edges

• Only shell commands are shielded. Reading a rendered file directly reaches you unmasked. Those files are gitignored, mode 0600 and destroyed at session end, but the window exists — prefer run --with over rendering when you have the choice.
• A declined request stays declined for that session. Asking again returns the same refusal by design.
• A lost master key means the secrets are gone. There is no recovery and no backdoor. Say this before someone stores something they cannot afford to lose.
• Support has no view here. That belongs to the hosted console, where there are customers and employees. On this machine there is one person and their own key.