Secret card: save the value into the project's .env

[shootingallday]

What I want

Let an agent's secret card (request_secret, added in #15907) save the value into a file in the project, such as .env, instead of only producing a one-use secretRef for webhook signatures.

Why

Most secrets an agent asks me for are app keys: a Stripe key, a Supabase key, a Linear token. The app reads them from .env. Today the card can't help with any of those, because a secretRef only feeds signature.secretRef on a scheduled task and expires after 24 hours. So I keep a small CLI that reads hidden input in my terminal and writes NAME=value into .env. That needs me at the PC. The card works from my phone, which is where I usually am when an agent needs a key.

Smallest version I can think of

An optional target on request_secret:

{ "label": "Stripe secret key", "reason": "...", "saveTo": { "name": "STRIPE_SECRET_KEY", "file": ".env" } }

When the user saves the card, the server:

• writes NAME=value to the file, replacing an existing NAME= line, in one atomic write;
• resolves file inside the project's workspace root and refuses anything outside it;
• returns { saved: true, name, file, length, gitignored } and never the value.

Everything else stays as it is: the same card, masking, decline, and the answered-once rule. No secretRef is minted when saveTo is set.

Open choice

Where the file lands. I'd write to the project's main workspace root, not the thread's worktree, since worktrees get removed and a key saved there would go with them. A project setup script (or #6905's .worktreeinclude) can copy .env into new worktrees.

Related

• feat: agents ask the user for a secret through a private card #15907 added the card
• [Feature]: Per-project environment variables #6715 per-project environment variables
• [Feature]: Support .worktreeinclude when creating worktrees #6905 .worktreeinclude

[RostyslavDzhohola]

+1, I hit this exact gap this week, with one twist: the file I needed lives outside the project.

An agent setting up a webhook bridge needed GROK_BOT_WEBHOOK_URL and GROK_BOT_WEBHOOK_AUTH in ~/.config/grokbot/webhook.env (mode 600). request_secret showed the right private card, but the secretRef it returned can only go to schedule_task's signature.secretRef, so there was nowhere to put the value. The workaround was a small macOS AppleScript app. It opens hidden-input dialogs, accepts the header with or without the Authorization: prefix, writes the env file with mode 600, sends a test ping, and shows success or the HTTP status. The values never reached the model. It works, but every user shouldn't need to write their own app for this, and it doesn't work from mobile or on a remote host.

Demo: video to follow in an edit.

Suggested additions to the saveTo proposal

• Allow targets outside the workspace, with the user's approval on the card. Many secrets belong in user-level config (~/.config/<tool>/*.env), not the repo. The card should show the exact resolved path, with ~ expanded on the server, before the user saves. A path inside the workspace could keep the current rule, and anything outside it would get a clear "outside this project" label.
• Several keys per card, for example saveTo: { file, entries: [{ name: "URL" }, { name: "AUTH" }] }. Related values (URL plus auth header) are often needed together, and asking twice is clumsy.
• Safe writes: create new files as 0600 and keep the existing mode on replace (see [Bug]: writeFileStringAtomically widens a file's mode on replace and is not crash-durable #14967). Don't follow symlinks. Refuse a target that isn't a regular file. Write atomically. Replace NAME= lines and leave the rest of the file unchanged.
• The agent only gets a confirmation: {saved, file, names, created|updated}. Never the value or its length (length can hint at the key type). No value goes into turn items, projections or logs, which matches how secret_request already records only the status.

Why this fits the current design: SecretRequests.answer already receives the value on the server, checks that the asking run is still active, and enforces that a card is answered once. A saveTo branch could write the file there instead of minting a ref, and return the result through request_secret. The card would stay the same on web and mobile, apart from showing the target path. Webhook signatures still need a ref, so secretRef would stay as it is.

Happy to help implement this if the direction and scope get a maintainer 👍.

[RostyslavDzhohola]

I built a quick prototype to see how this feels in the app. It's a local branch, not a PR (waiting on direction here first).

request_secret takes an optional saveTo: { file, names }. Before anything is written, the card shows the resolved path, flags a path outside the project, and gives one masked field per variable:

Narrow layout:

After saving, the card collapses to "Saved to ~/.config/acme-bot/webhook.env". The agent's tool result is only { "status": "saved", "savedTo": { "file": "…/webhook.env", "names": ["ACME_BOT_WEBHOOK_URL", "ACME_BOT_WEBHOOK_AUTH"] } }. It never sees the values; here it checks the mode and the names (username blacked out):

What the prototype does:

• ~, project-relative paths and symlinks are resolved on the server when the agent asks, so the card shows the file that will really be written, and "outside this project" is judged on the real path. A link that shows up at the file or a parent folder after that is refused, not followed.
• The file ends up mode 600 (a new folder 700). An existing looser file is tightened, never loosened.
• Existing NAME= lines are replaced and the rest of the file is kept. Values with spaces or $ are single-quoted, so dotenv and source both read them literally.
• No secretRef is minted for these cards, so nothing is left in T3's secret store to expire.
• An older client that can't show the target file gets "Update the app" instead of writing blind.
• Contracts, SecretRequests, the MCP tool and the web card, about 480 lines with tests. Mobile would need the same card change.

Known gaps a real PR would close: a per-file lock so two cards writing the same file can't drop each other's lines, multiline-aware replacement of quoted values, and recording the save and the write as one recoverable step.

Happy to open it as a PR if the direction works for a maintainer.