.env.example

# cli-bridge configuration — copy to .env and edit.

# --- Network ---
# Default binds to 127.0.0.1 (localhost only). Override ONLY if you know
# what you're doing and have a bearer check in place (BRIDGE_BEARER).
BRIDGE_HOST=127.0.0.1
# 3344 chosen to dodge common dev/service collisions (8787, 4098, etc.)
BRIDGE_PORT=3344

# When BRIDGE_HOST is anything other than 127.0.0.1 / ::1 / localhost, the
# server REFUSES to start without BRIDGE_BEARER set.
# Generate with: openssl rand -hex 32
# BRIDGE_BEARER=

# --- Storage ---
BRIDGE_DATA_DIR=./data

# --- Backends ---
# Comma-separated. Model ids are `<harness>/<model>` — the harness name
# here is what matches the id prefix. Unknown or missing-CLI backends
# are reported by /health with state=unavailable.
#
# Harnesses:
#   claude      — Claude Code CLI, real Anthropic
#   claudish    — Claude Code CLI + claudish proxy (ANTHROPIC_BASE_URL override)
#   kimi        — Kimi Code CLI (Moonshot subscription)
#   gemini      — Gemini CLI (Google subscription/API auth)
#   sandbox     — Tangle sandbox-api + AgentProfile catalog (profiles/*.json)
#   codex       — OpenAI Codex CLI
#   opencode    — opencode CLI (multi-provider; vehicle for Kimi Code via plugin)
#   factory     — Factory Droid (stub)
#   amp         — Sourcegraph Amp (stub)
#   forge       — OSS Forge (stub)
#   passthrough — direct vendor API call (openai/, anthropic/, moonshot/, zai/)
BRIDGE_BACKENDS=claude,kimi,gemini,sandbox,passthrough

# --- CLI timeouts (applies to all backends unless overridden) ---
# CLI_TIMEOUT_MS=300000

# --- Host admission / process caps ---
# Outer HTTP admission cap. Requests above maxActive wait in-process up to
# queue timeout; above maxQueue fail with 503 instead of spawning more CLIs.
# BRIDGE_HOST_CHAT_MAX_ACTIVE=8
# BRIDGE_HOST_CHAT_MAX_QUEUE=16
# BRIDGE_HOST_CHAT_QUEUE_TIMEOUT_MS=30000

# Durable-run replay and idempotency retention (process-local).
# BRIDGE_RUN_MAX_REPLAY_DELTAS=10000
# BRIDGE_RUN_REPLAY_RETENTION_MS=60000
# BRIDGE_RUN_IDENTITY_RETENTION_MS=86400000

# Raw host executor cap. Used directly by backends that cannot run in a
# systemd scope and as fallback when systemd-run is unavailable.
# BRIDGE_HOST_MAX_CONCURRENCY=4
# BRIDGE_HOST_ACQUIRE_DEADLINE_MS=60000

# Scoped host executor cap. Claude/Kimi/Pi default here on Linux: every
# CLI lives in its own transient systemd scope with cgroup memory/task/runtime
# ceilings and is killed as a whole on release.
# CLI_BRIDGE_SCOPE_MAX_CONCURRENCY=4
# CLI_BRIDGE_SCOPE_ACQUIRE_DEADLINE_MS=60000
# CLI_BRIDGE_SCOPE_TASKS_MAX=128
# CLI_BRIDGE_SCOPE_MEMORY_MAX=3G
# CLI_BRIDGE_SCOPE_RUNTIME_MAX_SEC=7200

# --- claude / claudish ---
# CLAUDE_BIN=/usr/local/bin/claude
# CLAUDE_TIMEOUT_MS=300000

# --- Per-backend executor (parallel mode via Docker pool) ---
# Every subprocess backend (claude, kimi, gemini, codex, opencode) supports an
# optional Docker executor. 'host' (default) spawns the CLI on the host.
# 'docker' provisions a pool of pre-warmed containers and dispatches
# each chat() via `docker exec` — required when serving N concurrent
# chat() calls without FS / OAuth race conditions.
#
# Set BRIDGE_DEFAULT_EXECUTOR for a global default, or override per
# backend via <NAME>_EXECUTOR.
#
# Build the shared runtime image once — it has all coding CLIs installed:
#   docker build -f docker/Dockerfile.cli-runtime -t cli-bridge-cli-runtime:latest .
# Or build a smaller subset image:
#   docker build -f docker/Dockerfile.cli-runtime --build-arg CLI_BRIDGE_HARNESSES=codex,gemini -t cli-bridge-cli-runtime:codex-gemini .
# Per-backend <NAME>_DOCKER_IMAGE env override is allowed if you want a
# leaner per-backend image for a specific deployment.
#
# Per-backend env keys (replace <NAME> with CLAUDE / KIMI / GEMINI / CODEX / OPENCODE):
#   <NAME>_EXECUTOR=host|docker
#   <NAME>_DOCKER_IMAGE=<image-tag>
#   <NAME>_DOCKER_POOL_SIZE=<n>
#   <NAME>_DOCKER_NAME_PREFIX=<container-name-prefix>
#   <NAME>_DOCKER_OAUTH_MOUNT=share|per-slot
#   <NAME>_DOCKER_HOST_CONFIG_DIR=<host path>      # share mode bind source
#   <NAME>_DOCKER_CONTAINER_CONFIG_DIR=<container path>  # bind target inside container
#   <NAME>_DOCKER_WORKSPACE_ROOT=<absolute host path>    # optional rw bind at the same container path
#   <NAME>_DOCKER_NETWORK=<existing Docker network name> # optional; shared by every pool slot
#
# OAuth modes:
#   share    — bind-mount the host config dir across all slots. Simpler;
#              concurrent token-refresh can race on the same session DB.
#   per-slot — each slot gets its own named docker volume. Full isolation;
#              requires one `<cli> /login` per slot on first run.
#
# BRIDGE_DEFAULT_EXECUTOR=host
# CLAUDE_EXECUTOR=docker
# CLAUDE_DOCKER_POOL_SIZE=4
# CLAUDE_DOCKER_OAUTH_MOUNT=share
# CLAUDE_DOCKER_WORKSPACE_ROOT=/tmp/cli-bridge-workspaces
# CLAUDE_DOCKER_NETWORK=research-services
#
# net-jail — deny-by-default EGRESS for worker containers, the network sibling
# of WORKER_FS_JAIL. Workers run on an internal Docker network with no route off
# it and reach only an allowlist that always contains the backend's own model
# endpoint (derived from the configured base URL — you do not name it here).
#
# Docker only. Set alongside a host-executed backend and the bridge REFUSES to
# start: a host-spawned CLI shares this machine's network namespace and any
# proxy variable it is given can be unset, so accepting the setting would report
# a policy that is not applied. Mutually exclusive with <NAME>_DOCKER_NETWORK.
#
# Requires iptables in the runtime image: each jailed container gets a
# deny-by-default packet filter in its own network namespace, without which the
# Docker host stays reachable on-link from inside the jail. Rebuild the image
# (pnpm docker:build:runtime) before turning this on for the first time; a
# backend whose image cannot enforce the filter refuses to start.
#
# WORKER_NET_JAIL=1                  # shorthand for BRIDGE_NET_JAIL_MODE=net-jail
# BRIDGE_NET_JAIL_MODE=off|net-jail
# BRIDGE_NET_JAIL_ALLOW=registry.npmjs.org,internal-svc.example:8443
#
# KIMI_EXECUTOR=docker
# KIMI_DOCKER_POOL_SIZE=2
# GEMINI_EXECUTOR=host
# CODEX_EXECUTOR=host
# OPENCODE_EXECUTOR=host
#
# Topology note: cli-bridge itself should run as a HOST process when
# you want the executor to spawn pool containers. If you run cli-bridge
# inside a container (compose.yml), mount /var/run/docker.sock so the
# bridge can drive the host docker daemon to spawn its pool as siblings;
# see README "Parallel mode (Docker pool)".

# URL of a running claudish proxy. Only required if `claudish` is in
# BRIDGE_BACKENDS. https://github.com/MadAppGang/claudish
# CLAUDISH_URL=http://127.0.0.1:3456

# --- codex ---
# CODEX_BIN=codex
# CODEX_TIMEOUT_MS=300000

# --- opencode ---
# OPENCODE_BIN=opencode
# OPENCODE_TIMEOUT_MS=300000

# --- kimi ---
# KIMI_BIN=kimi
# KIMI_TIMEOUT_MS=300000

# --- gemini ---
# Install official package only: npm install -g @google/gemini-cli
# GEMINI_BIN=gemini
# GEMINI_TIMEOUT_MS=300000
# GEMINI_APPROVAL_MODE=yolo
# GEMINI_SANDBOX=false

# --- factory / amp / forge (stubs) ---
# FACTORY_BIN=droid
# AMP_BIN=amp
# FORGE_BIN=forge

# --- Sandbox ---
# SANDBOX_API_URL=https://sandbox.tangle.tools
# SANDBOX_API_KEY=
# SANDBOX_PROFILES_DIR=./profiles
# SANDBOX_TIMEOUT_MS=300000

# --- Passthrough provider keys ---
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# MOONSHOT_API_KEY=
# ZAI_API_KEY=

# --- /cad/render (OpenSCAD → STL/PNG/GLB) ---
# Wall-clock budget for a single render (default 60_000 ms). Covers
# stl + png + glb steps combined.
# CAD_RENDER_TIMEOUT_MS=60000
# Requires `openscad` on $PATH (hardware profile in agent-dev-container).
# GLB output additionally requires `python3` + `trimesh`; if absent, GLB
# is omitted with a warning rather than failing the request.

# --- /v1/images/generations (OpenAI-compatible image gen) ---
# Default model: gpt-image-2. OpenAI-shaped body forwarded verbatim to
# upstream, OpenAI-shaped response returned to caller. Dispatch:
#   1. TANGLE_API_KEY set → forward to ${TANGLE_ROUTER_URL or
#      https://router.tangle.tools/v1}/images/generations
#   2. else OPENAI_API_KEY set → forward to https://api.openai.com/v1/...
#   3. else → 503 no_image_backend
# Override the router base for staging tangle-router instances:
# TANGLE_ROUTER_URL=https://router-staging.tangle.tools/v1