Secrets & Setup Instructions

Watchfire lets you provide agents with instructions for accessing external services — API keys, CLI tools, environment variables, and authentication details. These are injected into the agent's system prompt automatically.

How It Works

Secrets are stored in a plain Markdown file at:

.watchfire/secrets/instructions.md

When an agent session starts, Watchfire reads this file and injects its contents into the agent's system prompt under a "Secrets & Setup Instructions" section. The agent can then use this information to authenticate with services, set up environment variables, or use pre-configured CLI tools.

Setup

The secrets file is created automatically when you run watchfire init. Edit it with your project-specific instructions:

## CLI Tools

- Firebase CLI is authenticated. Use `firebase deploy` directly.
- AWS CLI is configured with the staging profile: `aws --profile staging`.

## Environment Variables

- `DATABASE_URL` is set in `.env.local` — do not commit this file.
- `STRIPE_TEST_KEY` is `sk_test_abc123` — use for all payment integration.

## API Keys

- OpenAI API key: `sk-proj-...` (org: my-org)
- Use the test Stripe key above for checkout features.

## Notes

- Always use the staging environment for testing.
- Never deploy to production without explicit approval.

Security

• The .watchfire/ directory is gitignored by default — secrets never enter version control.
• The sandbox blocks access to ~/.ssh, ~/.aws, ~/.gnupg, and .env files. Use the secrets file to tell agents what they need instead of relying on system-level credentials.
• Secrets are only injected into the agent's system prompt at session start. They are not written to disk inside the worktree.

GUI Support

The Watchfire GUI includes a Secrets tab where you can edit instructions.md directly. Changes are saved automatically.

See also

• Security — how secret storage fits into the broader threat model, alongside the sandbox, signature verification, and network exposure.