> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotvibe.app/llms.txt
> Use this file to discover all available pages before exploring further.

# secrets

> Declare secrets your app needs — stored in the macOS Keychain, never in the package.

## Fields

| Field      | Type   | Required     | Description                                                            |
| ---------- | ------ | ------------ | ---------------------------------------------------------------------- |
| `name`     | string | **required** | Secret name (used as the environment variable name at injection)       |
| `required` | bool   | optional     | Whether the app refuses to start without this secret. Default: `false` |

## How secrets work

Secrets are never stored inside the immutable `.vibeapp` package in plaintext.

1. On first open, the host app detects missing required secrets
2. The user is prompted to enter each secret value
3. Secrets are stored in the **macOS Keychain**, scoped to the project instance
4. At service start, secrets are injected as environment variables

Secrets persist across app restarts. Deleting a project instance removes its Keychain entries.

## Example

```yaml theme={null}
secrets:
  - name: OPENAI_API_KEY
    required: true
  - name: AWS_SECRET_ACCESS_KEY
    required: false
  - name: STRIPE_SECRET_KEY
    required: true
```

At runtime, `OPENAI_API_KEY`, `AWS_SECRET_ACCESS_KEY`, and `STRIPE_SECRET_KEY` are available as environment variables in all services.

## Safety guarantees

* Secrets never appear in logs (the log collector redacts known secret names)
* Secrets never appear in snapshots (excluded from state copy)
* Secrets are isolated per project instance — not shared between instances of the same app
* Required secrets that are missing prevent the app from starting

<Note>
  For distributing apps with pre-configured secrets bundled inside, see [Package Encryption](/security/package-encryption). That approach wraps the entire package in AES-256-GCM and prompts for a password at open time.
</Note>