alezmad/claudemesh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da5103a31547902495ed33f09cdc667f79934008
claudemesh/docs/env-vars.md
Alejandro Gutiérrez 05729ad8a4
Some checks failed
CI / Lint (push) Has been cancelled
Details
CI / Typecheck (push) Has been cancelled
Details
CI / Broker tests (Postgres) (push) Has been cancelled
Details
CI / Docker build (linux/amd64) (push) Has been cancelled
Details
feat(ga): close remaining GA blockers (backcompat, HA prep, tests, docs) 
Backwards compat shim (task 27)
- requireCliAuth() falls back to body.user_id when BROKER_LEGACY_AUTH=1
  and no bearer present. Sets Deprecation + Warning headers + bumps a
  broker_legacy_auth_hits_total metric so operators can watch the
  legacy traffic drain to 0 before removing the shim.
- All handlers parse body BEFORE requireCliAuth so the fallback can
  read user_id out of it.

HA readiness (task 29)
- .artifacts/specs/2026-04-15-broker-ha-statelessness-audit.md
  documents every in-memory symbol and rollout plan (phase 0-4).
- packaging/docker-compose.ha-local.yml spins up 2 broker replicas
  behind Traefik sticky sessions for local smoke testing.
- apps/broker/src/audit.ts now wraps writes in a transaction that
  takes pg_advisory_xact_lock(meshId) and re-reads the tail hash
  inside the txn. Concurrent broker replicas can no longer fork the
  audit chain.

Deploy gate (task 30)
- /health stays permissive (200 even on transient DB blips) so
  Docker doesn't kill the container on a glitch.
- New /health/ready checks DB + optional EXPECTED_MIGRATION pin,
  returns 503 if either fails. External deploy gate can poll this
  and refuse to promote a broken deploy.

Metrics dashboard (task 32)
- packaging/grafana/claudemesh-broker.json: ready-to-import Grafana
  dashboard covering active conns, queue depth, routed/rejected
  rates, grant drops, legacy-auth hits, conn rejects.

Tests (task 28)
- audit-canonical.test.ts (4 tests) pins canonical JSON semantics.
- grants-enforcement.test.ts (6 tests) covers the member-then-
  session-pubkey lookup with default/explicit/blocked branches.

Docs (task 34)
- docs/env-vars.md catalogues every env var the broker + CLI read.

Crypto review prep (task 35)
- .artifacts/specs/2026-04-15-crypto-review-packet.md: reviewer
  brief, threat model, scope, test coverage list, deliverables.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 23:51:28 +01:00

3.9 KiB
Raw Blame History

claudemesh environment variables

Reference for every env var the broker and CLI read.

Broker (apps/broker)

Required in production

Var Purpose
DATABASE_URL Postgres connection string. Must reach the mesh schema.
BROKER_ENCRYPTION_KEY 64 hex chars (32 bytes) for AES-256-GCM at-rest encryption of MCP env vars. Broker refuses to start in production if missing or malformed. Never log the value. Generate with openssl rand -hex 32.

Optional

Var Default Purpose
BROKER_PORT 7900 HTTP/WS listen port.
BROKER_PUBLIC_URL https://ic.claudemesh.com Public base for webhook URL generation and similar.
BROKER_WS_URL wss://ic.claudemesh.com/ws Public WS URL announced to integrations (Telegram bridge).
APP_URL https://claudemesh.com Web-app base for invite short URLs (/i/<code>).
EMAIL_FROM noreply@claudemesh.com Sender address for Postmark invite emails.
POSTMARK_API_KEY — Postmark server token. Set this or RESEND_API_KEY to enable email invites.
RESEND_API_KEY — Resend API key (alternative to Postmark).
MAX_MESSAGE_BYTES 65536 Hard cap on nonce+ciphertext+targetSpec in a send.
MAX_CONNECTIONS_PER_MESH varies Per-mesh connection cap.
STATUS_TTL_SECONDS 60 How long a presence can stay "working" before being swept back to idle.
HOOK_RATE_LIMIT_PER_MIN — TokenBucket refill rate for /hook/set-status.
HOOK_FRESH_WINDOW_SECONDS — How long a hook-set status takes precedence over the JSONL fallback.
MAX_SERVICES_PER_MESH varies Cap on deployed MCP services per mesh.
BROKER_INVITE_V2_ENABLED unset (disabled) Flip to 1 to accept POST /invites/:code/claim. Broken until the ed25519 binding step lands — see .artifacts/specs/2026-04-15-invite-v2-cli-migration.md.
BROKER_LEGACY_AUTH unset (disabled) Flip to 1 to accept pre-alpha.36 CLIs that send user_id in body instead of Bearer. Metered via broker_legacy_auth_hits_total; target removal once hits reach ~0.
EXPECTED_MIGRATION unset SHA of the newest applied migration to require on GET /health/ready. If set and the DB doesn't contain it, readiness fails → Coolify will not promote the deploy.
NODE_ENV — Setting to production enables fail-fast on missing BROKER_ENCRYPTION_KEY.

CLI (apps/cli)

Var Default Purpose
CLAUDEMESH_BROKER_URL wss://ic.claudemesh.com/ws Override the broker WS URL (self-hosters, tests).
CLAUDEMESH_API_URL https://claudemesh.com Override the API base URL.
CLAUDEMESH_BROKER_HTTP derived from CLAUDEMESH_BROKER_URL Explicit HTTPS base used by claimInviteV2 — overrides the derivation rule.
CLAUDEMESH_CLAIM_URL derived Explicit URL template for the v2 claim endpoint. {code} is substituted.
CLAUDEMESH_CONFIG_DIR ~/.claudemesh Where config.json, auth.json, grants.json, peer-cache.json live.
CLAUDEMESH_DEBUG 0 Flip to 1 to see [claudemesh] stderr lines from MCP + WS client.
CLAUDEMESH_DISPLAY_NAME hostname Override for display_name in hello.
CLAUDEMESH_INVITE_V2 unset Flip to 1 to prefer the v2 invite claim flow (CLI-side gated — spec pending).

/install shell script (apps/web/src/app/install/route.ts)

Var Purpose
CLAUDEMESH_DIR Installer target dir. Defaults to $HOME/.claudemesh.
CLAUDEMESH_BIN Shim dir. Defaults to $HOME/.local/bin.

Secrets that should NEVER be logged

  • BROKER_ENCRYPTION_KEY — AES key; leaking it voids encryption-at-rest
  • POSTMARK_API_KEY, RESEND_API_KEY — email provider tokens
  • auth.session_token (CLI side) — bearer for all broker calls
  • mesh.owner_secret_key (broker side) — invite signing key
  • mesh.root_key (broker side) — symmetric mesh key
Reference in New Issue View Git Blame Copy Permalink