Secrets: for your app and for your agent

Runs on: your Mac, the box and GitHub Actions.

You have two kinds of secrets, and they need the same care:

• App secrets. Your API uses them: the database password, the key that signs login tokens, the Sign in with Apple key, the RevenueCat webhook secret, the AI provider key.
• Agent secrets. Your coding agent uses them to do the work for you: the App Store Connect API key, the Expo token, the Cloudflare token, the kie.ai key.

Both stay out of git and out of the chat. This guide helps you pick one place for them, and set it up so an agent can read a secret without ever seeing your other passwords.

The rules, whatever tool you pick

• Never commit a secret. Put .env and .env.* in .gitignore before the first secret goes in.
• Never paste a secret into the chat with your agent. The chat is saved in transcripts and logs. Give the agent a reference instead (a name like KIE_AI_API_KEY, or op://agent-secrets/kie/credential). The skills read the value themselves and never print it.
• EXPO_PUBLIC_* values are not secret. They are built into the app, and anyone can read them from the download. A key that costs money or grants access belongs on your server, never in the app. ship-ios:app-store-ready checks the app for this.
• Staging gets its own values. A staging bug must not be able to spend production’s money or sign tokens production accepts.
• If a secret leaks, rotate it first. Make a new key and revoke the old one. Cleaning git history comes after, because a pushed secret is already public.

Pick a tool

Prices checked on 2026-09-28.

A simple default: if you already pay for 1Password, use it for both kinds. If not, start with .env files on your Mac, and move the app secrets to Doppler when you add staging or GitHub Actions.

How the skills read a secret

Whatever tool you pick, the skills look in three places, in this order (CONFIG.md, “Secrets”):

1. The environment. Start your agent through your tool, and it has every secret: doppler run -- claude, op run --env-file=agent.env -- claude, infisical run -- claude, bws run -- claude. You approve a prompt once, when it starts, never in the middle of a run. This works with any tool.
2. Your command in the onebox config (~/.config/onebox/config.json), secrets.command: one shell command that prints a secret, with {ref} where its name goes. "secrets": { "tool": "doppler" } and "secrets": { "tool": "1password" } are ready-made commands.
3. A .env file, the nearest one walking up from the folder.

1Password: a separate vault for your agent

Plain op asks for Touch ID through the 1Password app. In an agent run nobody answers that prompt, so the run hangs. A service account reads without a prompt. It can only see the vaults you give it, and 1Password never lets it see your Personal or Private vault. So you give agents their own vault, with only what they need.

Service accounts work on Families, Teams and Business plans. On an Individual plan, check your account settings first.

1. Make a vault called agent-secrets. Move or copy in only the secrets agents need: the App Store Connect key, the Expo token, the Cloudflare token, API keys. Leave everything else where it is.

2. Make a service account in the 1Password web app, under Developer, then Service accounts. Give it read access to agent-secrets only. Copy the token. 1Password shows it once.

3. Store the token in the macOS Keychain, not in a file or a shell profile:

   security add-generic-password -s agent-op -a service-account-token -w

   It asks for the token. Paste it there, not in the chat.

4. Give agents a helper for their own commands. It uses the token for one command only. Put it in ~/.zshenv, so the shells agents start also have it:

   opa() { OP_SERVICE_ACCOUNT_TOKEN="$(security find-generic-password -s agent-op -a service-account-token -w)" op "$@"; }

   Do not export OP_SERVICE_ACCOUNT_TOKEN globally. Your own op would then see only the agent vault.

5. Tell your agent the rule. Add this to AGENTS.md or CLAUDE.md:

   Secrets: read them with `opa read "op://agent-secrets/<item>/<field>"`,
   never with plain `op`. Never print a secret. Put it in a variable or pipe
   it to the command. If an item is not in agent-secrets, ask me to move it.

6. Point the onebox config at it. The skills’ scripts run in /bin/sh, where opa does not exist, so give them the same command in full:

   "secrets": { "command": "OP_SERVICE_ACCOUNT_TOKEN=$(security find-generic-password -s agent-op -a service-account-token -w) op read {ref}" }

   Then use op://agent-secrets/... references for each key. Or start your agent with op run, and keep plain names.

On the box and in GitHub Actions there is no Keychain. Use a second service account for each, so you can revoke one without breaking the others:

• The box: keep its token in a root-only file (chmod 600) and read it in the deploy step.
• GitHub Actions: save the token as the repository secret OP_SERVICE_ACCOUNT_TOKEN and load secrets with 1Password’s load-secrets-action.

Doppler: one config per environment

1. Make a project for the app, with the configs dev, stg and prd.
2. On your Mac, run doppler login once, then doppler setup in the repo. After that, agents read without a prompt: doppler secrets get NAME --plain -p <project> -c dev.
3. For the box and GitHub Actions, make a service token per config (doppler configs tokens create). A token for stg cannot read prd.
4. Set "secrets": { "tool": "doppler", "doppler": { "project": "<project>", "config": "dev" } } in the onebox config. Or start your agent with doppler run -- claude: then every secret is in its environment, and the skills need no config.

Where the values go

Check it works

• git status never shows a .env file.
• With 1Password: opa vault list shows only agent-secrets, and your own op vault list still shows all your vaults.
• Your agent can run a skill that needs a key, and the key never appears in the chat or in the terminal output.
• Staging and production have different database passwords and signing keys.

Common errors

• The agent hangs on a 1Password command. It used plain op, which waits for Touch ID. Use opa.
• A skill says “the secrets command … did not answer in 60 s”. Your command waits for a prompt, such as Touch ID. Use the service-account command (1Password, step 6), or start the agent through your tool.
• Your own op shows only one vault. OP_SERVICE_ACCOUNT_TOKEN is exported somewhere in your shell profile. Remove the export and keep the opa function.
• “Rate limit exceeded” from 1Password. Service accounts have hourly and daily limits. Read a secret once into a variable, not inside a loop.
• A secret was committed. Rotate it now, then remove it from history. Removing it from history alone does not help: it may already be copied.

Wrong or out of date? Fix it on GitHub.