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

# Environment Variables

> All environment variables recognized by the Buckle gateway, CLI, and Docker image. Proxy config, auth, logging, and feature flags.

## Server configuration

All environment variables are optional for local development. The defaults provide a working setup out of the box.

| Variable | Default | Description |
| - | - | - |
| `DATABASE_URL` | Bundled PostgreSQL | PostgreSQL connection string. The Docker Compose setup includes PostgreSQL by default. |
| `SECRET_ENCRYPTION_KEY` | Auto-generated | AES-256-GCM encryption key for the secret store. Auto-generated on first run if not set. |
| `NEXTAUTH_SECRET` | - | Enables Google OAuth (multi-user mode). Without this, Buckle runs in single-user mode with no login required. |
| `GOOGLE_CLIENT_ID` | - | Google OAuth client ID. Required if `NEXTAUTH_SECRET` is set. |
| `GOOGLE_CLIENT_SECRET` | - | Google OAuth client secret. Required if `NEXTAUTH_SECRET` is set. |

### Single-user vs multi-user mode

By default, Buckle runs in **single-user mode** with no login screen. This is ideal for local development and personal use.

To enable **multi-user mode** with Google OAuth, set the three auth variables:

```bash theme={null}
NEXTAUTH_SECRET=your-random-secret
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
```

### Bring your own database

By default, the Docker Compose setup bundles a PostgreSQL instance. To use an external PostgreSQL instance instead:

```bash theme={null}
DATABASE_URL=postgresql://user:password@host:5432/buckle
```

## Telemetry

Self-hosted Buckle sends no telemetry by default. The gateway's analytics sink stays off unless both of these are set:

| Variable | Default | Description |
| - | - | - |
| `POSTHOG_API_KEY` | - | PostHog project key for gateway analytics. Leave unset on self-hosted deployments. |
| `POSTHOG_HOST` | - | PostHog host the gateway sends to. Analytics stay off unless this and `POSTHOG_API_KEY` are both set. |

See [Telemetry](/docs/reference/telemetry.md) for details on what is collected and where.

## CLI configuration variables

These variables configure the `buckle` CLI tool. Each one overrides the matching stored value, so they suit CI jobs and scripts where writing config files is awkward.

| Variable | Default | Description |
| - | - | - |
| `BUCKLE_API_KEY` | - | API key. Overrides the key stored by `buckle auth login`. |
| `BUCKLE_API_HOST` | `https://api.buckle.dev` | API base URL. Overrides `buckle config set api-host`. |
| `BUCKLE_PROJECT` | - | Active project slug. Overrides `buckle config set project`. |
| `BUCKLE_AGENT` | - | Agent identifier for `buckle run`. Overrides `buckle config set agent`. |
| `BUCKLE_ENV` | `production` | Set to `dev` for development mode |

### Development vs production

Setting `BUCKLE_ENV=dev` switches the CLI to development mode, which uses separate files and keychain entries so it never interferes with your production setup:

| Path / Key | Production | Development |
| - | - | - |
| Credentials directory | `~/.buckle/credentials` | `~/.buckle/credentials-dev` |
| Config file | `~/.buckle/config.json` | `~/.buckle/config-dev.json` |
| Keychain service name | `buckle-api-key` | `buckle-api-key-dev` |

## Variables set by `buckle run`

`buckle run` injects these into the wrapped agent process. They are not user-configurable:

| Variable | Description |
| - | - |
| `HTTPS_PROXY`, `HTTP_PROXY` | Route the agent's traffic through the gateway, carrying the agent's access token |
| `SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, `DENO_CERT` | Trust the gateway CA (all point at `~/.buckle/ca-bundle.pem`) |
| `BUCKLE_GATEWAY` | Set to `true` so agents and scripts can detect they run behind the gateway |
| `BUCKLE_GATEWAY_SKILL_PATH` | Path to the gateway skill file, set for commands without a dedicated integration |

See the [Coding Agents guide](/docs/guides/coding-agents.md) for what `buckle run` does end to end.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.