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

# Configuration

> Environment variables and config file reference for MeepaChat

MeepaChat is configured via a YAML file and environment variables. Environment variables always take precedence over the config file.

## Config File Location

MeepaChat searches for a config file in this order:

1. `$MEEPA_CONFIG_PATH` — if set, only this path is checked
2. `~/.meepachat/config.yaml` — primary location (written by `meepachat init`)
3. `/etc/meepa/config.yaml` — system-wide location

`meepachat init` writes the config to `~/.meepachat/config.yaml` automatically.

## Precedence

```
environment variables  (highest)
    ↓
~/.meepachat/config.yaml
    ↓
built-in defaults      (lowest)
```

## Server

<ParamField path="PORT" type="integer" default="8091">
  HTTP port the server listens on. Can also be set via `meepachat start --port N`.
</ParamField>

<ParamField path="BIND" type="string" default="(all interfaces)">
  Network address to bind to. Can also be set via `meepachat start --bind ADDR`.
</ParamField>

<ParamField path="BASE_URL" type="string">
  Public URL of the server (e.g. `https://chat.example.com`). Required for invite links and email links to work correctly. Also controls whether session cookies are set with the `Secure` flag — set this to an `https://` URL in production.
</ParamField>

<ParamField path="LOG_FORMAT" type="string" default="text">
  Log output format. `text` for human-readable output, `json` for structured logs.
</ParamField>

**Config file equivalent:**

```yaml theme={null}
port: 8091
bind: ""
domain: https://chat.example.com
```

***

## Database

<ParamField path="DATABASE_URL" type="string" default="postgres://meepachat:meepachat@db:5432/meepachat?sslmode=disable">
  PostgreSQL connection string. MeepaChat runs migrations automatically on startup.
</ParamField>

<ParamField path="REDIS_URL" type="string" default="redis://redis:6379/0">
  Redis connection string. Used for WebSocket pub/sub when running multiple server instances. Optional — omit to run without Redis (single instance only).
</ParamField>

**Config file equivalent:**

```yaml theme={null}
database_url: postgres://user:pass@localhost:5432/meepachat?sslmode=disable
redis_url: redis://localhost:6379/0
```

***

## Authentication

<ParamField path="BETTER_AUTH_URL" type="string">
  URL of the auth service. Set by `meepachat init`.
</ParamField>

<ParamField path="BETTER_AUTH_SECRET" type="string">
  Shared secret for the auth service. Must match the value configured in the auth sidecar.
</ParamField>

<ParamField path="OPEN_REGISTRATION" type="boolean" default="true">
  When `false`, new users must have a valid invite link to register. The first user is always exempt and becomes admin.
</ParamField>

<ParamField path="REQUIRE_EMAIL_VERIFICATION" type="boolean" default="false">
  When `true`, users must verify their email address before they can log in. Requires SMTP to be configured.
</ParamField>

**Config file equivalent:**

```yaml theme={null}
open_registration: false

better_auth:
  url: http://localhost:8093
  secret: your-secret-here
```

***

## File Storage

MeepaChat stores uploads in S3-compatible storage. If no S3 endpoint is configured, files are stored on the local filesystem.

<ParamField path="S3_ENDPOINT" type="string">
  S3-compatible endpoint URL. Omit the `https://` scheme — set `S3_USE_SSL=true` separately.

  Examples: `localhost:9010` (MinIO), `your-account.r2.cloudflarestorage.com` (Cloudflare R2), `s3.amazonaws.com` (AWS S3).
</ParamField>

<ParamField path="S3_ACCESS_KEY" type="string">
  S3 access key ID.
</ParamField>

<ParamField path="S3_SECRET_KEY" type="string">
  S3 secret access key.
</ParamField>

<ParamField path="S3_BUCKET" type="string" default="meepachat">
  S3 bucket name. The bucket must already exist.
</ParamField>

<ParamField path="S3_REGION" type="string">
  S3 region. Required for AWS S3. Optional for MinIO and Cloudflare R2.
</ParamField>

<ParamField path="S3_USE_SSL" type="boolean" default="false">
  Enable TLS when connecting to the S3 endpoint. Set to `true` for any public S3 service.
</ParamField>

<ParamField path="UPLOAD_DIR" type="string" default="/data/uploads">
  Local directory for file uploads when S3 is not configured. Also used as a temporary staging area when S3 is enabled.
</ParamField>

<ParamField path="MAX_UPLOAD_SIZE" type="integer" default="20971520">
  Maximum file upload size in bytes. Default is 20 MB (20 × 1024 × 1024).
</ParamField>

**Config file equivalent:**

```yaml theme={null}
upload_dir: /data/uploads
max_upload_size: 20971520

storage:
  endpoint: your-account.r2.cloudflarestorage.com
  access_key: your-access-key
  secret_key: your-secret-key
  bucket: meepachat
  region: auto
  use_ssl: true
```

### MinIO (default)

`meepachat init` starts a local MinIO instance. No additional configuration needed for local deployments.

### Cloudflare R2

```yaml theme={null}
storage:
  endpoint: <account-id>.r2.cloudflarestorage.com
  access_key: <r2-access-key-id>
  secret_key: <r2-secret-access-key>
  bucket: meepachat
  region: auto
  use_ssl: true
```

### AWS S3

```yaml theme={null}
storage:
  endpoint: s3.amazonaws.com
  access_key: <aws-access-key-id>
  secret_key: <aws-secret-access-key>
  bucket: meepachat
  region: us-east-1
  use_ssl: true
```

<Note>
  Legacy `MINIO_*` environment variables (`MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET`, `MINIO_USE_SSL`) are still accepted as fallbacks when the corresponding `S3_*` variable is not set.
</Note>

***

## SMTP / Email

Email is used for invite links and email verification. Optional unless `REQUIRE_EMAIL_VERIFICATION=true`.

<ParamField path="SMTP_HOST" type="string">
  SMTP server hostname (e.g. `smtp.mailgun.org`, `smtp.gmail.com`).
</ParamField>

<ParamField path="SMTP_PORT" type="integer" default="587">
  SMTP port. 587 for STARTTLS (recommended), 465 for TLS, 25 for unencrypted.
</ParamField>

<ParamField path="SMTP_USER" type="string">
  SMTP username.
</ParamField>

<ParamField path="SMTP_PASS" type="string">
  SMTP password.
</ParamField>

<ParamField path="SMTP_FROM" type="string">
  From address for outgoing email (e.g. `chat@example.com`).
</ParamField>

**Config file equivalent:**

```yaml theme={null}
smtp:
  host: smtp.mailgun.org
  port: 587
  user: postmaster@mg.example.com
  pass: your-smtp-password
  from: chat@example.com
```

***

## Push Notifications

### Web Push (VAPID)

Browser push notifications use VAPID keys. Generate them once and store them permanently — changing keys will break existing browser subscriptions.

<ParamField path="VAPID_PUBLIC_KEY" type="string">
  Base64url-encoded ECDSA P-256 public key.
</ParamField>

<ParamField path="VAPID_PRIVATE_KEY" type="string">
  Base64url-encoded ECDSA P-256 private key.
</ParamField>

<ParamField path="VAPID_SUBJECT" type="string">
  Contact URL or `mailto:` address identifying the push server (e.g. `mailto:admin@example.com`).
</ParamField>

Generate VAPID keys:

```bash theme={null}
npx web-push generate-vapid-keys
```

**Config file equivalent:**

```yaml theme={null}
push:
  vapid_public_key: BxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA
  vapid_private_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  vapid_subject: mailto:admin@example.com
```

### FCM (Firebase Cloud Messaging)

Required for push notifications on iOS and Android mobile apps.

<ParamField path="FCM_CREDENTIALS_FILE" type="string">
  Path to a Firebase service account JSON file. Download from Firebase Console → Project Settings → Service accounts.
</ParamField>

**Config file equivalent:**

```yaml theme={null}
push:
  fcm_credentials_file: /etc/meepachat/firebase-credentials.json
```

***

## Sessions

<ParamField path="SESSION_TTL" type="duration" default="720h">
  How long login sessions remain valid. Accepts Go duration strings: `720h` (30 days), `168h` (7 days), `24h` (1 day).
</ParamField>

**Config file equivalent:**

```yaml theme={null}
session_ttl: 720h
```

***

## CORS

<ParamField path="CORS_ORIGINS" type="string">
  Comma-separated list of allowed CORS origins. When not set, only same-origin requests are permitted.

  Example: `https://chat.example.com,https://app.example.com`
</ParamField>

***

## Search

<ParamField path="TIKA_URL" type="string">
  URL of an Apache Tika server for full-text extraction from uploaded files (PDF, Office docs, etc.). Optional — omit to skip content indexing of attachments.

  Example: `http://localhost:9998`
</ParamField>

**Config file equivalent:**

```yaml theme={null}
tika_url: http://localhost:9998
```

***

## Auto-Update

<ParamField path="MEEPA_AUTO_UPDATE" type="boolean" default="false">
  When `true`, the server checks for updates every 6 hours and restarts automatically if a new version is available. Connected clients receive an `update_restarting` WebSocket event before the restart.
</ParamField>

**Config file equivalent:**

```yaml theme={null}
auto_update: true
```

***

## MeepaGateway Integration

<ParamField path="GATEWAY_API_URL" type="string">
  URL of a running [MeepaGateway](/gateway/introduction) instance. When set, MeepaChat proxies credential action card confirmations to the gateway so agents can store logins, API keys, and passwords through interactive chat forms.

  Example: `http://localhost:63372`
</ParamField>

**Config file equivalent:**

```yaml theme={null}
gateway_api_url: http://localhost:63372
```

<Note>
  Without this setting, credential action cards will render in chat but confirmations will fail with a 404. See the [MeepaGateway integration guide](/meepachat/integrations/meepagateway) for full setup instructions.
</Note>

***

## Complete Config File Example

```yaml theme={null}
# ~/.meepachat/config.yaml

setup_complete: true
domain: https://chat.example.com
port: 8091

database_url: postgres://meepachat:secret@localhost:5432/meepachat?sslmode=disable
redis_url: redis://localhost:6379/0

open_registration: false
session_ttl: 720h

better_auth:
  url: http://localhost:8093
  secret: your-better-auth-secret

storage:
  endpoint: your-account.r2.cloudflarestorage.com
  access_key: your-access-key
  secret_key: your-secret-key
  bucket: meepachat
  region: auto
  use_ssl: true

smtp:
  host: smtp.mailgun.org
  port: 587
  user: postmaster@mg.example.com
  pass: your-smtp-password
  from: chat@example.com

push:
  vapid_public_key: BxxxxA
  vapid_private_key: xxxxx
  vapid_subject: mailto:admin@example.com
  fcm_credentials_file: /etc/meepachat/firebase-credentials.json

auto_update: true

gateway_api_url: http://localhost:63372
```