.env.example

MATRIX_HOMESERVER=https://matrix.biglone.tech
MATRIX_USER_ID=@codeharbor-bot:example.com
MATRIX_ACCESS_TOKEN=
# Optional comma-separated Matrix sender ids to ignore (recommended for multi-bot rooms to prevent bot loops).
# Example: MATRIX_BOT_USER_IDS=@dev-main:example.com,@review-guard:example.com
MATRIX_BOT_USER_IDS=

# Optional explicit trigger in groups; can be empty to disable prefix trigger.
MATRIX_COMMAND_PREFIX=!code
# Bot output language: zh | en
OUTPUT_LANGUAGE=zh

# AI CLI provider: codex | claude | gemini
AI_CLI_PROVIDER=codex
# Executable path for selected provider (for example: codex / claude / gemini / /abs/path/to/bin)
CODEX_BIN=codex
CODEX_MODEL=
CODEX_WORKDIR=/Users/biglone/workspace
CODEX_DANGEROUS_BYPASS=false
# Base timeout for one backend execution.
# Note: /agents and /autodev use at least 1800000ms per role to avoid large-task timeout loops.
CODEX_EXEC_TIMEOUT_MS=600000
CODEX_SANDBOX_MODE=
CODEX_APPROVAL_POLICY=
# Optional extra CLI args, space separated (example: --search --no-alt-screen)
CODEX_EXTRA_ARGS=
# Optional JSON object for additional environment variables passed to codex child process.
CODEX_EXTRA_ENV_JSON=

# Multi-agent workflow (Phase B, opt-in).
AGENT_WORKFLOW_ENABLED=false
# Auto-repair rounds after reviewer rejects output.
AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS=1
# Optional prompt context budget guards (chars).
# Leave empty (or <=0) to disable truncation and keep full context.
# AGENT_WORKFLOW_PLAN_CONTEXT_MAX_CHARS=
# AGENT_WORKFLOW_OUTPUT_CONTEXT_MAX_CHARS=
# AGENT_WORKFLOW_FEEDBACK_CONTEXT_MAX_CHARS=
# Role skill injection (Planner / Executor / Reviewer).
AGENT_WORKFLOW_ROLE_SKILLS_ENABLED=true
# summary | progressive | full
AGENT_WORKFLOW_ROLE_SKILLS_MODE=progressive
# Optional max chars for injected [role_skills] block.
# AGENT_WORKFLOW_ROLE_SKILLS_MAX_CHARS=2400
# Optional comma-separated skill roots (default: ~/.codex/skills).
# AGENT_WORKFLOW_ROLE_SKILLS_ROOTS=
# Optional JSON role assignments:
# AGENT_WORKFLOW_ROLE_SKILLS_ASSIGNMENTS_JSON={"planner":["task-planner","builtin-planner-core"],"executor":["autonomous-dev","builtin-executor-core"],"reviewer":["code-reviewer","builtin-reviewer-core"]}
# AutoDev loop guardrails (for /autodev run without task id).
# Set to 0 for unlimited.
AUTODEV_LOOP_MAX_RUNS=20
AUTODEV_LOOP_MAX_MINUTES=120
# Auto commit on reviewer APPROVED (when repo is clean).
AUTODEV_AUTO_COMMIT=true
# AutoDev git commit author identity (fallback to defaults when empty).
AUTODEV_GIT_AUTHOR_NAME=CodeHarbor AutoDev
AUTODEV_GIT_AUTHOR_EMAIL=autodev@codeharbor.local
# Auto release after mapped "big feature" task is completed and auto-committed.
# Mapping source: TASK_LIST.md table rows where column-1=taskId and column-2=semver (for example: T8.4 | v0.1.55).
AUTODEV_AUTO_RELEASE_ENABLED=true
# Auto push release commit after local release commit is created.
AUTODEV_AUTO_RELEASE_PUSH=false
# Persist each /autodev run execution archive to local JSON files.
AUTODEV_RUN_ARCHIVE_ENABLED=true
# Relative to CODEX_WORKDIR (or absolute path) when archive is enabled.
AUTODEV_RUN_ARCHIVE_DIR=.codeharbor/autodev-runs
# Strict completion gate validation mode (fail-closed without structured validation evidence).
AUTODEV_VALIDATION_STRICT=false
# Send a second-pass review handoff message when AutoDev run completes.
AUTODEV_SECONDARY_REVIEW_ENABLED=false
# Mention target for secondary review handoff (for example: @review-guard).
AUTODEV_SECONDARY_REVIEW_TARGET=@review-guard
# When true, only send handoff after completion gate passes.
AUTODEV_SECONDARY_REVIEW_REQUIRE_GATE_PASSED=true
# Echo planner/executor/reviewer full stage output to Matrix during /autodev run.
AUTODEV_STAGE_OUTPUT_ECHO_ENABLED=true
# Mark task as blocked (🚫) when same task fails consecutively N times.
AUTODEV_MAX_CONSECUTIVE_FAILURES=3
# Bot profiles apply default retire behavior: when true, apply will auto-retire legacy single-instance units if install succeeds.
BOT_PROFILES_AUTO_RETIRE_DEFAULT_SINGLE_INSTANCE=false

# SQLite state database path.
STATE_DB_PATH=data/state.db
# Legacy JSON path for one-time migration import.
STATE_PATH=data/state.json

MAX_PROCESSED_EVENTS_PER_SESSION=200
MAX_SESSION_AGE_DAYS=30
MAX_SESSIONS=5000
REPLY_CHUNK_SIZE=3500

MATRIX_PROGRESS_UPDATES=true
MATRIX_PROGRESS_MIN_INTERVAL_MS=2500
# progress notice delivery mode: upsert | timeline
MATRIX_PROGRESS_DELIVERY_MODE=upsert
MATRIX_TYPING_TIMEOUT_MS=10000
# show rich-message badge headers ("CodeHarbor 提示" / "CodeHarbor AI 回复")
MATRIX_NOTICE_BADGE_ENABLED=true
SESSION_ACTIVE_WINDOW_MINUTES=20
# Optional Matrix admin users (comma-separated mxid list).
# Used as /upgrade permission fallback when MATRIX_UPGRADE_ALLOWED_USERS is empty.
MATRIX_ADMIN_USERS=
# Optional Matrix user allowlist for /upgrade command (comma-separated mxid list).
# Higher priority than MATRIX_ADMIN_USERS; when both are empty any DM user can trigger /upgrade.
MATRIX_UPGRADE_ALLOWED_USERS=
# Optional launchd labels used on macOS upgrade/postinstall restart flows.
CODEHARBOR_LAUNCHD_MAIN_LABEL=com.codeharbor.main
CODEHARBOR_LAUNCHD_ADMIN_LABEL=com.codeharbor.admin
# Package version update check (used by /status, /version, and Admin health app row).
PACKAGE_UPDATE_CHECK_ENABLED=true
PACKAGE_UPDATE_CHECK_TIMEOUT_MS=3000
# Cache ttl for update check results (default 6h).
PACKAGE_UPDATE_CHECK_TTL_MS=21600000

# Group trigger defaults.
GROUP_DIRECT_MODE_ENABLED=false
GROUP_TRIGGER_ALLOW_MENTION=true
GROUP_TRIGGER_ALLOW_REPLY=true
GROUP_TRIGGER_ALLOW_ACTIVE_WINDOW=true
GROUP_TRIGGER_ALLOW_PREFIX=true

# Optional room-level trigger overrides (JSON object).
# ROOM_TRIGGER_POLICY_JSON={"!room:example.com":{"allowMention":true,"allowReply":true,"allowActiveWindow":false,"allowPrefix":false}}
ROOM_TRIGGER_POLICY_JSON=

# One-shot conversation bridge injected after /backend switch.
CONTEXT_BRIDGE_HISTORY_LIMIT=16
CONTEXT_BRIDGE_MAX_CHARS=8000

# Rate limiting / anti-abuse.
RATE_LIMIT_WINDOW_SECONDS=60
RATE_LIMIT_MAX_REQUESTS_PER_USER=20
RATE_LIMIT_MAX_REQUESTS_PER_ROOM=120
RATE_LIMIT_MAX_CONCURRENT_GLOBAL=8
RATE_LIMIT_MAX_CONCURRENT_PER_USER=1
RATE_LIMIT_MAX_CONCURRENT_PER_ROOM=4
# Shared limiter backend: `local` (default) or `redis`.
RATE_LIMIT_SHARED_MODE=local
# Required when RATE_LIMIT_SHARED_MODE=redis (supports redis:// and rediss://).
RATE_LIMIT_SHARED_REDIS_URL=
RATE_LIMIT_SHARED_REDIS_KEY_PREFIX=codeharbor:rate-limit:v1
RATE_LIMIT_SHARED_REDIS_COMMAND_TIMEOUT_MS=150
# Safety TTL for distributed concurrency counters (milliseconds).
RATE_LIMIT_SHARED_REDIS_CONCURRENCY_TTL_MS=1800000
# Fallback to local limiter when Redis is unavailable.
RATE_LIMIT_SHARED_FALLBACK_TO_LOCAL=true

# CLI compatibility mode (IM shell approximation of codex CLI).
CLI_COMPAT_MODE=false
CLI_COMPAT_PASSTHROUGH_EVENTS=true
CLI_COMPAT_PRESERVE_WHITESPACE=true
CLI_COMPAT_DISABLE_REPLY_CHUNK_SPLIT=false
CLI_COMPAT_PROGRESS_THROTTLE_MS=300
CLI_COMPAT_FETCH_MEDIA=true
# Image guardrails (applies to Matrix m.image attachments).
CLI_COMPAT_IMAGE_MAX_BYTES=10485760
CLI_COMPAT_IMAGE_MAX_COUNT=4
CLI_COMPAT_IMAGE_ALLOWED_MIME_TYPES=image/png,image/jpeg,image/webp,image/gif
# Optional audio transcription for Matrix m.audio attachments.
CLI_COMPAT_TRANSCRIBE_AUDIO=false
CLI_COMPAT_AUDIO_TRANSCRIBE_MODEL=gpt-4o-mini-transcribe
CLI_COMPAT_AUDIO_TRANSCRIBE_TIMEOUT_MS=120000
CLI_COMPAT_AUDIO_TRANSCRIBE_MAX_CHARS=6000
CLI_COMPAT_AUDIO_TRANSCRIBE_MAX_RETRIES=1
CLI_COMPAT_AUDIO_TRANSCRIBE_RETRY_DELAY_MS=800
# Skip transcription when audio file is larger than this limit (bytes). Default: 25MB.
CLI_COMPAT_AUDIO_TRANSCRIBE_MAX_BYTES=26214400
# Optional local whisper command. Use {input} placeholder for the audio file path.
# Example:
# CLI_COMPAT_AUDIO_LOCAL_WHISPER_COMMAND=codeharbor-whisper-transcribe --input {input} --model small
CLI_COMPAT_AUDIO_LOCAL_WHISPER_COMMAND=
CLI_COMPAT_AUDIO_LOCAL_WHISPER_TIMEOUT_MS=180000
# Optional JSONL output path for executed prompt recording (for replay benchmarking).
CLI_COMPAT_RECORD_PATH=

DOCTOR_HTTP_TIMEOUT_MS=10000

# Task API server (platform integration entrypoint).
API_ENABLED=false
API_BIND_HOST=127.0.0.1
API_PORT=8788
# Required when API_ENABLED=true. Used by Authorization: Bearer <API_TOKEN>.
API_TOKEN=
# Optional API token scopes (JSON array). Default behavior allows submit+query (`tasks.submit`, `tasks.read`).
# Example for read-only API token:
# API_TOKEN_SCOPES_JSON=["tasks.read.api"]
API_TOKEN_SCOPES_JSON=
# Optional webhook secret. Enables POST /api/webhooks/:source signature validation when set.
API_WEBHOOK_SECRET=
# Allowed timestamp drift for webhook signature validation (seconds).
API_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS=300
# Optional outbound integration dispatch for API/webhook task lifecycle events.
EXTERNAL_INTEGRATION_ENABLED=false
# Generic lifecycle callback endpoint (`queued/executing/retrying/completed/failed`).
EXTERNAL_NOTIFY_WEBHOOK_URL=
# Optional ticket status callback endpoint (only for ticket-source tasks).
EXTERNAL_TICKET_WEBHOOK_URL=
# Shared delivery timeout/retry settings for outbound integration callbacks.
EXTERNAL_INTEGRATION_TIMEOUT_MS=3000
EXTERNAL_INTEGRATION_MAX_RETRIES=1
EXTERNAL_INTEGRATION_RETRY_DELAY_MS=500
# Optional bearer token attached to outbound integration requests.
EXTERNAL_INTEGRATION_AUTH_TOKEN=

# Admin API server (for config UI/backend).
ADMIN_BIND_HOST=127.0.0.1
ADMIN_PORT=8787
# Token protection for /api/admin/* endpoints.
# Strongly recommended for any non-localhost access.
# Required when exposing admin via reverse proxy/tunnel/public domain.
ADMIN_TOKEN=
# Optional multi-token RBAC (JSON array).
# Each item: {"token":"...","role":"admin|viewer","actor":"ops-name","scopes":["admin.read.audit"]}
# - scopes is optional. When omitted, role default scopes are used.
# - supports wildcard pattern: "admin.read.*" or "*"
# Example:
# ADMIN_TOKENS_JSON=[{"token":"admin-secret","role":"admin","actor":"ops-admin"},{"token":"viewer-secret","role":"viewer","actor":"ops-audit","scopes":["admin.read.auth","admin.read.audit"]}]
# Rotate helper:
# ./scripts/rotate-admin-token.sh --target rbac --role admin --actor ops-admin
ADMIN_TOKENS_JSON=
# Optional IP allowlist (comma-separated, for example: 127.0.0.1,192.168.1.10).
ADMIN_IP_ALLOWLIST=
# Optional browser origin allowlist for CORS (comma-separated).
# Example: https://admin.example.com,https://ops.example.com
ADMIN_ALLOWED_ORIGINS=

LOG_LEVEL=info