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

PORT · integer · default: "8091"

HTTP port the server listens on. Can also be set via meepachat start --port N.

BIND · string · default: "(all interfaces)"

Network address to bind to. Can also be set via meepachat start --bind ADDR.

BASE_URL · 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.

LOG_FORMAT · string · default: "text"

Log output format. text for human-readable output, json for structured logs.

Config file equivalent:

port: 8091
bind: ""
domain: https://chat.example.com

---

Database

DATABASE_URL · string

PostgreSQL connection string. MeepaChat runs migrations automatically on startup.

REDIS_URL · 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).

Config file equivalent:

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

---

Authentication

BETTER_AUTH_URL · string

URL of the auth service. Set by meepachat init.

BETTER_AUTH_SECRET · string

Shared secret for the auth service. Must match the value configured in the auth sidecar.

OPEN_REGISTRATION · boolean · default: "true"

When false, new users must have a valid invite link to register. The first user is always exempt and becomes admin.

REQUIRE_EMAIL_VERIFICATION · boolean · default: "false"

When true, users must verify their email address before they can log in. Requires SMTP to be configured.

Config file equivalent:

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.

S3_ENDPOINT · 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).

S3_ACCESS_KEY · string

S3 access key ID.

S3_SECRET_KEY · string

S3 secret access key.

S3_BUCKET · string · default: "meepachat"

S3 bucket name. The bucket must already exist.

S3_REGION · string

S3 region. Required for AWS S3. Optional for MinIO and Cloudflare R2.

S3_USE_SSL · boolean · default: "false"

Enable TLS when connecting to the S3 endpoint. Set to true for any public S3 service.

UPLOAD_DIR · 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.

MAX_UPLOAD_SIZE · integer · default: "20971520"

Maximum file upload size in bytes. Default is 20 MB (20 × 1024 × 1024).

Config file equivalent:

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

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

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

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.

---

SMTP / Email

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

SMTP_HOST · string

SMTP server hostname (e.g. smtp.mailgun.org, smtp.gmail.com).

SMTP_PORT · integer · default: "587"

SMTP port. 587 for STARTTLS (recommended), 465 for TLS, 25 for unencrypted.

SMTP_USER · string

SMTP username.

SMTP_PASS · string

SMTP password.

SMTP_FROM · string

From address for outgoing email (e.g. [e-mail]).

Config file equivalent:

smtp:
  host: smtp.mailgun.org
  port: 587
  user: [e-mail]
  pass: your-smtp-password
  from: [e-mail]

---

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.

VAPID_PUBLIC_KEY · string

Base64url-encoded ECDSA P-256 public key.

VAPID_PRIVATE_KEY · string

Base64url-encoded ECDSA P-256 private key.

VAPID_SUBJECT · string

Contact URL or mailto: address identifying the push server (e.g. mailto:[e-mail]).

Generate VAPID keys:

npx web-push generate-vapid-keys

Config file equivalent:

push:
  vapid_public_key: BxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA
  vapid_private_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  vapid_subject: mailto:[e-mail]

FCM (Firebase Cloud Messaging)

Required for push notifications on iOS and Android mobile apps.

FCM_CREDENTIALS_FILE · string

Path to a Firebase service account JSON file. Download from Firebase Console → Project Settings → Service accounts.

Config file equivalent:

push:
  fcm_credentials_file: /etc/meepachat/firebase-credentials.json

---

Sessions

SESSION_TTL · duration · default: "720h"

How long login sessions remain valid. Accepts Go duration strings: 720h (30 days), 168h (7 days), 24h (1 day).

Config file equivalent:

session_ttl: 720h

---

CORS

CORS_ORIGINS · 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

---

Search

TIKA_URL · 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

Config file equivalent:

tika_url: http://localhost:9998

---

Auto-Update

MEEPA_AUTO_UPDATE · 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.

Config file equivalent:

auto_update: true

---

MeepaGateway Integration

GATEWAY_API_URL · string

URL of a running MeepaGateway 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

Config file equivalent:

gateway_api_url: http://localhost:63372

Without this setting, credential action cards will render in chat but confirmations will fail with a 404. See the MeepaGateway integration guide for full setup instructions.

---

Complete Config File Example

# ~/.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: [e-mail]
  pass: your-smtp-password
  from: [e-mail]

push:
  vapid_public_key: BxxxxA
  vapid_private_key: xxxxx
  vapid_subject: mailto:[e-mail]
  fcm_credentials_file: /etc/meepachat/firebase-credentials.json

auto_update: true

gateway_api_url: http://localhost:63372