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

# Self-hosted configuration: Environment variables

> Environment variables, authentication modes, and networking options for the self-hosted Buckle image. Configure URLs, secrets, and sign-in.

All configuration for the self-hosted images is passed as environment variables. This page covers both editions; variables that only apply to the Enterprise image (`trybuckle/slim`) are marked. The [full environment variable reference](/docs/reference/environment-variables.md) covers the gateway and CLI more broadly.

## Core

| Variable | Default | Description |
| - | - | - |
| `DATABASE_URL` | - | PostgreSQL connection string. Required. |
| `APP_URL` | `http://localhost:10254` | The public URL of your instance. Used in links and as the base for OAuth callback URLs. Set it to your real `https://` URL in production. |
| `BUCKLE_ORG_API_KEY` | Generated on first start | **Enterprise image only.** The organization API key seeded at startup. Format: `oc_org_` + 64 lowercase hex characters (`oc_org_$(openssl rand -hex 32)`). A malformed value fails startup loudly rather than being replaced. |
| `BUCKLE_ORG_API_KEY_FILE` | - | **Enterprise image only.** Path to a file containing the organization API key. Use with Docker or Kubernetes secrets instead of putting the key in the environment. |
| `SECRET_ENCRYPTION_KEY` | Generated by setup | AES-256-GCM key for the secret store. Generated by `pnpm run setup` / the install script. Keep it safe and store it in your secrets manager — it encrypts your stored secrets. |
| `GATEWAY_INTERNAL_SECRET` | Generated by setup | Authenticates the gateway to the API server. |
| `BETTER_AUTH_SECRET` | Generated by setup | Signs session cookies. (Renamed from `NEXTAUTH_SECRET`; if your `.env` still sets the old name, rename it — everyone signs in again once.) |
| `LOG_LEVEL` | `info` | Log verbosity for the dashboard and API. |

> [!NOTE]
>
> If you don't set `BUCKLE_ORG_API_KEY`, the generated key is printed to the container logs exactly once, marked "Save it now — shown only once." Prefer setting it yourself so the credential is pinned and never appears in logs.

## Networking

| Variable | Default | Description |
| - | - | - |
| `GATEWAY_BASE_URL` | `host.docker.internal:10255` | The gateway address embedded in the proxy configuration that [`/v1/container-config`](/docs/self-hosting/connect-agents) hands to agents. The default works for agent containers on the same Docker host. Set it to a reachable host and port when agents run elsewhere. |
| `GATEWAY_PORT` | `10255` | The port the gateway listens on inside the container. |

The container exposes two ports: `10254` (dashboard and REST API) and `10255` (the gateway proxy agents connect to). Treat `10254` as an admin interface and expose `10255` wherever agents run.

## Authentication

The first visit asks you to **create an account** — email and password. That account owns the instance; after it exists, joining needs an invitation. Create it right away: until you do, whoever reaches the host first becomes the owner.

| Variable | Default | Description |
| - | - | - |
| `BETTER_AUTH_SECRET` | Generated by setup | Signs session cookies. Generate with `openssl rand -base64 32`. |
| `GOOGLE_CLIENT_ID` | - | Optional — adds a "Continue with Google" button beside the password form. |
| `GOOGLE_CLIENT_SECRET` | - | Optional — Google OAuth client secret. Redirect URI: `<API_URL>/auth/callback/google`. |

You can change your password any time from **Settings** > **Profile**, which also signs out every other session.

## Database

The compose files in the deploy guides bundle PostgreSQL. To use an external or managed database instead, drop the `postgres` service and point `DATABASE_URL` at your database:

```bash theme={null}
DATABASE_URL=postgresql://user:password@db.internal.example.com:5432/buckle
```

Migrations run automatically when the container starts, so the database user needs DDL privileges on the target database.

## App integrations

Self-hosted instances connect apps with **your own OAuth credentials**: create an OAuth app with each provider, then supply its client ID and secret in the dashboard or pre-configure it with environment variables. The [app credentials reference](/docs/self-hosting/app-credentials.md) lists the variables for every app. Register the callback URL as:

```
{APP_URL}/v1/apps/{provider}/callback
```

For example, `https://buckle.internal.example.com/v1/apps/github/callback`. Per-provider setup is covered in the [integration guides](/docs/integrations/app-connections.md).


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