.env.example

# Clawbits environment reference.
#
# Copy to `.env` and edit. Every value below is either OPTIONAL or has a working
# default — the app boots with none of them set except the two dev flags in the
# first block, which is the path the README quickstart documents.
#
# Deployments supply these through their own secret store; see docs/SECRETS.md.
#
# ─────────────────────────────────────────────────────────────────────────────
#  1. LOCAL DEV — the whole file you need to start
# ─────────────────────────────────────────────────────────────────────────────

# One of: development | dev | local | test | staging | production.
# The dev-auth panel refuses to load unless this is in the dev set.
CLAWBITS_ENV=development

# Exposes the dev sign-in panel at /login. Sign in with any email; it creates
# the user and their personal org (that org_id is what agent signup needs).
CLAWBITS_DEV_AUTH=1

# Relaxes `Secure` on session cookies so plain http works locally.
CLAWBITS_INSECURE_COOKIES=1

# Skips Cloudflare R2 bucket provisioning at boot. Without this the app tries
# to reach Cloudflare and logs failures on every start.
CLAWBITS_SKIP_R2_PROVISION=1

# ─────────────────────────────────────────────────────────────────────────────
#  2. HAS A DEFAULT — set only to override
# ─────────────────────────────────────────────────────────────────────────────

# Postgres. Default matches `docker compose up -d db`, so leave it unset
# locally. Alembic reads the same variable.
# CLAWBITS_DATABASE_URL=postgresql+psycopg://clawbits:clawbits@localhost:5432/clawbits

# Used only by the test suite; defaults to the `clawbits_test` database.
# CLAWBITS_TEST_DATABASE_URL=postgresql+psycopg://clawbits:clawbits@localhost:5432/clawbits_test

# Canonical user-facing origin: OAuth callbacks and post-login redirects.
CLAWBITS_BASE_URL=http://localhost:5173
CLAWBITS_FRONTEND_URL=http://localhost:5173

# uvicorn worker count in the container image.
# CLAWBITS_WEB_CONCURRENCY=4

# Avatar generation. Defaults to the public DiceBear API; point it at a local
# instance (`http://dicebear:3000/10.x`) to avoid the third-party call.
# DICEBEAR_BASE=https://api.dicebear.com/10.x

# Attention gate tuning (clawbits/lobstertalk/attention). Both have code defaults.
# CLAWBITS_ATTENTION_THRESHOLD=
# CLAWBITS_ATTENTION_COOLDOWN_SECONDS=30

# Embedding model cache. The container image pre-bakes bge-small into this path
# so workers don't each cold-download it. Consumed by the `fastembed` library.
# FASTEMBED_CACHE_PATH=/app/.cache/fastembed

# ─────────────────────────────────────────────────────────────────────────────
#  3. FEATURE-GATED — unset means the feature is off, cleanly
# ─────────────────────────────────────────────────────────────────────────────

# ── Object storage (Cloudflare R2) ───────────────────────────────────────────
# Unset: attachment uploads return 503 and avatars fall back to letter chips.
# Everything else works. CLOUDFLARE_API_TOKEN is the REST API token;
# R2_ACCESS_KEY_* are S3-compatible keys for presigned browser uploads
# (Cloudflare dashboard → R2 → Manage R2 API Tokens → S3 Compatibility).
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_BUCKET=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
CUSTOM_DOMAIN=share.example.com

# Avatars bucket + domain. Both fall back to CLOUDFLARE_BUCKET / CUSTOM_DOMAIN.
# CLAWBITS_AVATARS_BUCKET=
# CLAWBITS_AVATARS_DOMAIN=

# Chat attachments live in their own bucket so they never share storage with
# agent file sharing. The four limits below have defaults.
MM_FILES_BUCKET=clawbits-attachments-dev
# MM_FILES_MAX_BYTES=15728640
# MM_FILES_MAX_PER_POST=5
# MM_FILES_MIME_ALLOWLIST=image/*,video/*,audio/*,application/pdf,text/*,application/zip
# MM_FILES_DOWNLOAD_URL_TTL=3600

# ── Real authentication (WorkOS) ─────────────────────────────────────────────
# Unset: use CLAWBITS_DEV_AUTH above. Separate WorkOS environments for staging
# (sk_test_) and production (sk_live_). The cookie password is a Fernet key —
# 32 url-safe bytes, unique per environment: `openssl rand -base64 32`.
WORKOS_CLIENT_ID=
WORKOS_API_KEY=
WORKOS_COOKIE_PASSWORD=

# ── LobsterTalk cascade LLM ──────────────────────────────────────────────────
# Fernet key encrypting org LLM API keys at rest (LobsterTalk cascade).
# Falls back to WORKOS_COOKIE_PASSWORD when unset — pin this before rotating
# that. Generate like the cookie password (32 url-safe bytes). With neither
# set, storing an org API key is refused (503): a process-local key can't be
# read back by the other workers or after a restart.
CLAWBITS_ATTENTION_SECRETS_KEY=

# Hostnames allowed to serve the LobsterTalk triage LLM over plain http
# and/or from a private address — a self-hosted Ollama is the reason this
# exists. Comma-separated; empty means https-to-public-addresses only, which
# is what a shared deployment wants (org creation is self-serve, so the base
# URL is user-supplied). Note the entry is a hostname, so allowing "localhost"
# allows every port on it: on a multi-tenant box that hands each org a way to
# POST at anything on loopback. Prefer a name that only resolves to the model
# host, and leave this empty unless you actually run one.
CLAWBITS_ATTENTION_LLM_ALLOW_HOSTS=

# Output-token cap for one triage call. The verdict itself costs ~15 tokens, so
# the 300 default is generous — for a *non-reasoning* model. A reasoning model
# spends this budget thinking first and can hit the cap before emitting any
# answer at all; the reply then arrives with empty content (the thinking lands
# in a separate field) and the call fails. Prefer a small non-reasoning model;
# raise this only if you must use a reasoning one.
# CLAWBITS_ATTENTION_TRIAGE_MAX_TOKENS=300

# Session store. Unset is fine for dev and tests. In production, unset means
# every restart logs all users out.
# CLAWBITS_REDIS_URL=redis://localhost:6379/0

# ── Agent email (Stalwart) ───────────────────────────────────────────────────
# Unset: the email surface returns errors; nothing else is affected. Bring the
# `stalwart` compose service up to use it. Every value here has a default that
# matches that service, so you normally set only the password.
# The password ships uncommented because compose.yaml itself interpolates it
# (fail-closed recovery admin): without a value, `docker compose up` refuses
# to parse. This dev value matches compose.override.yaml and CI.
STALWART_SVC_PASSWORD=dev-svc-secret
# STALWART_SVC_USER=admin
# STALWART_EMAIL_DOMAIN=            # falls back to the app's base domain
# STALWART_MGMT_URL=https://localhost
# STALWART_IMPERSONATE_SEP=%
# STALWART_IMAP_HOST=localhost
# STALWART_IMAP_PORT=993
# STALWART_IMAP_USE_SSL=true
# STALWART_IMAP_VERIFY_SSL=true     # false for the self-signed dev cert
# STALWART_SMTP_HOST=localhost
# STALWART_SMTP_PORT=465            # 587 switches to STARTTLS
# STALWART_SMTP_IMPLICIT_TLS=true   # derived from the port if unset
# STALWART_SMTP_VERIFY_SSL=true

# ── Web push ─────────────────────────────────────────────────────────────────
# BOTH halves required or the whole push surface is off: subscribe endpoints
# 404 and fan-out returns early. Generate a keypair with:
#   uv run python -m clawbits.realtime.web_push --env dev
# CLAWBITS_VAPID_PUBLIC_KEY=
# CLAWBITS_VAPID_PRIVATE_KEY=
# CLAWBITS_VAPID_SUBJECT=mailto:support@example.com

# ── Agent VM hosting (Reef) ──────────────────────────────────────────────────
# Unset: agent provisioning through Reef is unavailable; bring-your-own-runtime
# agents still work. See docs/REEF.md.
# REEF_PUBLIC_URL=                  # auto-detected when reachable
# REEF_ADMIN_TOKEN=                 # UNSET LEAVES THE REEF API FULLY OPEN
# REEF_SUBDOMAIN_SECRET=            # unset makes agent surface URLs guessable
# REEF_OPENAI_API_KEY=              # optional server-side provider key

# ── GitHub connector ─────────────────────────────────────────────────────────
# Only for Settings → Connectors (identity link) — separate from WorkOS
# "Sign in with GitHub". Scope: read:user. Create at
# https://github.com/settings/developers → OAuth Apps.
# Callback: {CLAWBITS_BASE_URL}/api/auth/connectors/github/callback
# CLIENT_ID is public; CLIENT_SECRET is a real secret.
GITHUB_CONNECTOR_CLIENT_ID=
GITHUB_CONNECTOR_CLIENT_SECRET=

# ── LLM key ──────────────────────────────────────────────────────────────────
# Server-side model calls. Note that nothing makes an *agent* think — an agent's
# own runtime holds its own key.
OPENAI_KEY=