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

# Environment Variables

> Environment variables reference for ChatbotX.

All configuration is done through environment variables. Changes take effect only after restarting the affected service.

<Tip>
  Copy `.env.example` from the repository root as a starting point — defaults are pre-configured for local development.
</Tip>

***

## App

### `NEXT_PUBLIC_ENVIRONMENT`

```bash theme={null}
NEXT_PUBLIC_ENVIRONMENT=dev
```

Runtime environment. Controls behavior such as logging verbosity and debug tooling.

**Allowed values:** `dev`, `prod` — **Default:** `dev`

***

## URLs

### `NEXT_PUBLIC_BUILDER_URL`

```bash theme={null}
NEXT_PUBLIC_BUILDER_URL=https://builder.yourdomain.com
```

Public-facing URL of the Builder service. Used by the browser to make API calls and by other services to construct absolute URLs. **Required.**

***

### `NEXT_PUBLIC_PARTYSOCKET_URL`

```bash theme={null}
NEXT_PUBLIC_PARTYSOCKET_URL=https://ws.yourdomain.com
```

Public-facing URL of the PartySocket WebSocket server. Used by the browser to establish realtime connections. **Required.**

***

### `NEXT_PUBLIC_ASSET_URL`

```bash theme={null}
NEXT_PUBLIC_ASSET_URL=https://cdn.yourdomain.com/chatbotx/
```

Base URL for serving user-uploaded files and generated assets from storage. Should point to the public bucket prefix.

***

## Authentication

### `BETTER_AUTH_SECRET`

```bash theme={null}
BETTER_AUTH_SECRET=your-secret-here
```

Secret key used to sign and verify authentication tokens. Generate with:

```bash theme={null}
openssl rand -base64 32
```

**Required.** Keep this secret — rotating it invalidates all existing sessions.

***

### `BETTER_AUTH_URL`

```bash theme={null}
BETTER_AUTH_URL=https://builder.yourdomain.com
```

Base URL of the authentication server. Must match `NEXT_PUBLIC_BUILDER_URL` in most deployments. **Required.**

***

## Database

### `DATABASE_URL`

```bash theme={null}
DATABASE_URL=postgresql://user:password@localhost:5432/chatbotx?schema=public
```

PostgreSQL connection URL. **Required.** The database must be reachable from all three services (Builder, Worker).

***

## Redis

### `REDIS_URL`

```bash theme={null}
REDIS_URL=redis://localhost:6379
```

Primary Redis connection URL. Used as the default for all Redis roles (cache, queue, pub/sub) unless overridden by the variables below. **Required.**

***

### `REDIS_CACHE_URL`

```bash theme={null}
REDIS_CACHE_URL=redis://localhost:6380
```

Dedicated Redis instance for caching. Falls back to `REDIS_URL` when not set.

***

### `REDIS_QUEUE_URL`

```bash theme={null}
REDIS_QUEUE_URL=redis://localhost:6381
```

Dedicated Redis instance for BullMQ job queues. Falls back to `REDIS_URL` when not set.

***

### `REDIS_SEQUENCE_URL`

```bash theme={null}
REDIS_SEQUENCE_URL=redis://localhost:6382
```

Dedicated Redis instance for sequence scheduling. Falls back to `REDIS_URL` when not set.

***

### S3-compatible storage

Compatible with AWS S3, RustFS, MinIO, Cloudflare R2, and any S3-compatible provider.

#### `S3_ENDPOINT`

```bash theme={null}
S3_ENDPOINT=https://s3.amazonaws.com
# or for self-hosted:
S3_ENDPOINT=http://localhost:9000
```

S3 API endpoint URL. Required for non-AWS providers.

#### `S3_ACCESS_KEY_ID`

```bash theme={null}
S3_ACCESS_KEY_ID=your-access-key
```

S3 access key ID.

#### `S3_SECRET_ACCESS_KEY`

```bash theme={null}
S3_SECRET_ACCESS_KEY=your-secret-key
```

S3 secret access key.

#### `S3_REGION`

```bash theme={null}
S3_REGION=us-east-1
```

S3 bucket region.

#### `S3_BUCKET`

```bash theme={null}
S3_BUCKET=chatbotx
```

S3 bucket name.

***

## Email

### `SMTP_SERVER`

```bash theme={null}
SMTP_SERVER=smtp://username:password@smtp.yourdomain.com:587
```

SMTP connection URL for outgoing email. **Required.** Use `smtp://` for plain/STARTTLS and `smtps://` for implicit TLS.

For local development, [MailHog](http://localhost:8025) is included in the Docker Compose stack:

```bash theme={null}
SMTP_SERVER=smtp://localhost:1025
```

***

### `NEXT_PUBLIC_SMTP_FROM`

```bash theme={null}
NEXT_PUBLIC_SMTP_FROM=no-reply@yourdomain.com
```

Email address shown in the `From` field of outgoing messages. **Required.**

***

## Realtime (PartySocket)

### `REALTIME_API_KEY`

```bash theme={null}
REALTIME_API_KEY=your-api-key
```

Shared secret used by the Builder and Worker to authenticate requests to the PartySocket service. Generate with:

```bash theme={null}
openssl rand -hex 32
```

**Required.** Must be the same value across all services.

***

## Worker

### `SCHEDULER_BUCKET_RANGE`

```bash theme={null}
SCHEDULER_BUCKET_RANGE=0-255
```

Hash bucket range this worker instance is responsible for in the sequence scheduler. For a single worker, use `0-255` (the full range). Split across replicas for horizontal scaling — e.g. `0-127` and `128-255` for two workers.

**Default:** `0-255`

***

## Social Media keys

See the "channels" section of the documentation for the channel you want to configure, for details about how to set that up.