Use Valkeyra with coding agents

Coding agents (for example Claude Code, Codex, and other agents that read AGENTS.md) run commands for you. Many commands need an API key. Valkeyra lets the command get the key without the agent seeing it.

The short version

Use Valkeyra with coding agents

Valkeyra protects your keys without these rules. Values never print to a terminal. A coding agent gets values only through `valkeyra run`, which puts them in the environment of one command and masks them in its output. Each reveal, copy, and change needs Touch ID or Face ID. The Valkeyra windows are hidden from screenshots and screen sharing, and their Show, Copy, and Install buttons work only with a real click. Copied values stay on this Mac, are marked as concealed, and are cleared after 60 seconds. Notes never go to the CLI.

The rules are an extra layer. They tell an agent what not to do, and in Claude Code the deny rules stop the most common wrong commands before they run.

Agent setup (Valkeyra menu > Agent Setup) installs the rules:
- Claude Code: a rule block in ~/.claude/CLAUDE.md and deny rules in ~/.claude/settings.json.
- Codex and other agents: the same rule block in AGENTS.md, in a folder that you pick. These agents get no deny rules.
You see the exact text and a diff of each file first. In the diff of settings.json, values that can be secrets (env, tokens, keys, headers, hook commands) show as ••••; your permission rules (allow and deny) show as they are, because they are rules, not secrets. Each changed file gets a backup next to the real file (for a link: next to the file that the link points to; name ends with .bak-valkeyra-<date>-<time>). Install needs Touch ID. Restart your agent after the install. Run Agent setup again after a Valkeyra update: it adds only what is missing and lists old rules for you to remove.

In Terminal, `valkeyra agent-rules` prints the same text and rules. It does not install anything.

What the rules cannot do:
- An agent can ignore the rule text. Only the deny rules of Claude Code are enforced, and they match command patterns: a script or another program can still run a forbidden command.
- Codex and other agents get the text only.
- A command that you start with `valkeyra run` gets the values. It can print, send, or keep them, and any process of your user can read its environment while it runs. Masking hides only exact values in its output. Run only commands that you trust.
- An agent that you gave Accessibility or screen-recording permission can see and control other apps. Valkeyra refuses scripted clicks on its Show, Copy, and Install buttons, but do not give coding agents these permissions.
- The rules cover the agents that you set up. Set up each new agent too.

Example: .env.valkeyra

# ENV_VAR=vkr://<name>
OPENAI_API_KEY=vkr://shop/openai_api_key
DATABASE_URL=vkr://shop/database_url

Then the agent runs:

valkeyra run -- npm test

Valkeyra shows the request (the program, the folder, the full command, and the key names). After you approve, npm test starts with the two variables set. Output that contains a value is masked. You can approve once, or for a short time (a grant, 10 minutes by default) for the same command in the same terminal.

Other ways to give a key to one command:

valkeyra run --only openai_api_key=OPENAI_API_KEY -- ./script.sh   # no file needed
valkeyra run --fd DB_PASS=3 -- tool --password-fd 3                # a pipe, not the environment

Agent setup (Mac)

Agent Setup is in the Valkeyra menu (and is the last, optional step of the "Set up Valkeyra" window). It:

  1. Shows the exact text that it will add for each agent you choose: Claude Code (~/.claude/CLAUDE.md and ~/.claude/settings.json) and AGENTS.md in a folder that you pick (text only: other agents have no deny-rule file).
  2. Shows a diff of each file and where the backup goes.
  3. Installs only after you click Install and approve with Touch ID. It makes a backup of each file first and never removes your own rules.

valkeyra agent-rules prints the same text and deny rules in Terminal. It does not install anything. Agents may not open Agent setup or change these files.

What the rules do

The product works without the rules. These controls are in the apps:

The rules are an extra layer. They tell the agent not to read values, .env files, the keychain, the clipboard, or the environment, and not to run Valkeyra commands that only you should run.

Limits

Valkeyra protects against accidental leaks of a key into an agent's context and against a request that you did not mean to approve. Know these limits: