@nordbyte/nordrelay 0.4.1 → 0.5.1

package/.env.example

@@ -1,153 +1,244 @@
-# Required: bot token from BotFather.
-TELEGRAM_BOT_TOKEN=123456789:replace-me
-
-# Required: comma-separated Telegram user ids that may administer and use the bot.
-# A fresh install only accepts messages from these admin user ids.
-TELEGRAM_ADMIN_USER_IDS=123456789
-
-# Optional role controls. Add non-admin operators or read-only users here.
-# Admin user ids are automatically allowed and do not need to be repeated.
-TELEGRAM_ALLOWED_USER_IDS=
-TELEGRAM_READONLY_USER_IDS=
-# Optional granular permission policy per role. Permissions: inspect, sessions,
-# prompt, files, settings, auth, admin. Admin always keeps admin permission.
-TELEGRAM_ROLE_POLICIES_JSON=
-
-# Backward-compatible alternative for this connector. Private chat ids usually
-# match the Telegram user id; group chat ids may be negative.
-TELEGRAM_ALLOWED_CHAT_IDS=
+# NordRelay runtime config example.
+# Access is managed with NordRelay users, groups, linked Telegram identities, and enabled Telegram group chats.
+# Create the first admin with `nordrelay init` or `nordrelay user create-admin`.
 
-# Optional explicit override. Keep false for private bots.
-TELEGRAM_ALLOW_ANY_CHAT=false
+# Telegram
+# Required Telegram bot and transport settings.
+# BotFather token.
+TELEGRAM_BOT_TOKEN=123456789:replace-me
+# polling or webhook.
+# Options: polling, webhook
+TELEGRAM_TRANSPORT=polling
+# Public base URL for webhook mode.
+TELEGRAM_WEBHOOK_URL=
+# Local webhook bind host.
+TELEGRAM_WEBHOOK_HOST=127.0.0.1
+# Local webhook bind port.
+TELEGRAM_WEBHOOK_PORT=8080
+# Webhook request path.
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+# Optional Telegram webhook secret token.
+TELEGRAM_WEBHOOK_SECRET=
 
+# Agents
 # Agent access. Codex is enabled by default; Pi, Hermes, OpenClaw, and Claude Code are opt-in.
-# Pi requires the `pi` CLI from https://pi.dev/ on the host. Hermes uses
-# the Hermes API Server (`hermes gateway` with API_SERVER_ENABLED=true).
-# OpenClaw uses the OpenClaw Gateway WebSocket RPC endpoint.
-# Claude Code uses the Claude Agent SDK and the host `claude` CLI when present.
+# Allow Codex sessions.
 NORDRELAY_CODEX_ENABLED=true
+# Allow Pi sessions.
 NORDRELAY_PI_ENABLED=false
+# Allow Hermes sessions through the Hermes API Server.
 NORDRELAY_HERMES_ENABLED=false
+# Allow OpenClaw sessions through the OpenClaw Gateway.
 NORDRELAY_OPENCLAW_ENABLED=false
+# Allow Claude Code sessions through the Claude Agent SDK.
 NORDRELAY_CLAUDE_CODE_ENABLED=false
+# codex, pi, hermes, openclaw, or claude-code.
+# Options: codex, pi, hermes, openclaw, claude-code
 NORDRELAY_DEFAULT_AGENT=codex
 
-# Codex defaults for newly created or reattached Telegram sessions.
+# Codex
+# Codex defaults for newly created or reattached sessions.
+# Optional Codex SDK API key.
 CODEX_API_KEY=
+# Optional explicit Codex executable path.
 CODEX_CLI_PATH=
+# Force SDK-bundled CLI instead of host CLI.
 CODEX_USE_BUNDLED_CLI=false
+# Default model for new Codex threads.
 CODEX_MODEL=
+# Local state sync interval.
 CODEX_SYNC_INTERVAL_MS=10000
+# External CLI busy polling interval.
+CODEX_EXTERNAL_BUSY_CHECK_MS=5000
+# External CLI stale timeout.
+CODEX_EXTERNAL_BUSY_STALE_MS=300000
+# read-only, workspace-write, or danger-full-access.
+# Options: read-only, workspace-write, danger-full-access
 CODEX_SANDBOX_MODE=workspace-write
+# never, on-request, on-failure, or untrusted.
+# Options: never, on-request, on-failure, untrusted
 CODEX_APPROVAL_POLICY=never
-
-# Optional extra launch profiles for /launch_profiles.
-# Example: [{"id":"review","label":"Review","sandboxMode":"workspace-write","approvalPolicy":"on-request"}]
+# Additional launch profile definitions.
 CODEX_LAUNCH_PROFILES_JSON=
+# Launch profile ID used by default.
 CODEX_DEFAULT_LAUNCH_PROFILE=default
+# Expose danger-full-access profiles.
 ENABLE_UNSAFE_LAUNCH_PROFILES=false
 
-# Pi coding agent defaults. PI_DEFAULT_MODEL accepts Pi model patterns such as
-# openai-codex/gpt-5.5. PI_DEFAULT_THINKING: off, minimal, low, medium, high, xhigh.
+# Pi
+# Pi coding agent defaults.
+# Optional Pi executable path.
 PI_CLI_PATH=
+# Optional Pi session directory.
 PI_SESSION_DIR=
+# Default Pi model slug.
 PI_DEFAULT_MODEL=
+# off, minimal, low, medium, high, or xhigh.
+# Options: off, minimal, low, medium, high, xhigh
 PI_DEFAULT_THINKING=medium
+# default, readonly, no-tools, offline, or safe-offline.
+# Options: default, readonly, no-tools, offline, safe-offline
 PI_DEFAULT_PROFILE=default
 
-# Hermes Agent defaults. HERMES_DEFAULT_REASONING: none, minimal, low,
-# medium, high, xhigh. HERMES_API_KEY must match API_SERVER_KEY when the
-# Hermes API Server is protected.
+# Hermes
+# Hermes Agent defaults. Hermes uses the Hermes API Server.
+# Optional Hermes executable path.
 HERMES_CLI_PATH=
+# Optional Hermes home directory. Defaults to ~/.hermes.
 HERMES_HOME=
+# Optional explicit Hermes state.db path.
 HERMES_STATE_DB_PATH=
+# Hermes API Server base URL.
 HERMES_API_BASE_URL=http://127.0.0.1:8642
+# Bearer token for the Hermes API Server.
 HERMES_API_KEY=
+# Default model label sent to Hermes API runs.
 HERMES_DEFAULT_MODEL=
+# none, minimal, low, medium, high, or xhigh.
+# Options: none, minimal, low, medium, high, xhigh
 HERMES_DEFAULT_REASONING=
+# default, safe, readonly, or yolo.
+# Options: default, safe, readonly, yolo
 HERMES_DEFAULT_PROFILE=default
 
-# OpenClaw Agent defaults. OPENCLAW_DEFAULT_THINKING: off, minimal, low,
-# medium, high, xhigh. Gateway token/password are optional unless your
-# OpenClaw Gateway requires shared-secret authentication.
+# OpenClaw
+# OpenClaw Agent defaults. OpenClaw uses the OpenClaw Gateway WebSocket RPC endpoint.
+# Optional OpenClaw executable path.
 OPENCLAW_CLI_PATH=
+# OpenClaw Gateway WebSocket URL.
 OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
+# Shared-secret token for the OpenClaw Gateway.
 OPENCLAW_GATEWAY_TOKEN=
+# Shared-secret password for the OpenClaw Gateway.
 OPENCLAW_GATEWAY_PASSWORD=
+# Configured OpenClaw agent id, for example main or work.
 OPENCLAW_AGENT_ID=main
+# Optional OpenClaw home directory. Defaults to ~/.openclaw.
 OPENCLAW_HOME=
+# Optional OpenClaw state directory.
 OPENCLAW_STATE_DIR=
+# Default OpenClaw model id.
 OPENCLAW_DEFAULT_MODEL=
+# off, minimal, low, medium, high, or xhigh.
+# Options: off, minimal, low, medium, high, xhigh
 OPENCLAW_DEFAULT_THINKING=
+# default, safe, readonly, local, or deliver.
+# Options: default, safe, readonly, local, deliver
 OPENCLAW_DEFAULT_PROFILE=default
 
-# Claude Code defaults. CLAUDE_CODE_DEFAULT_EFFORT: off, low, medium, high,
-# xhigh. CLAUDE_CODE_CLI_PATH is optional; NordRelay uses `claude` on PATH or
-# the Claude Agent SDK bundled runtime.
+# Claude Code
+# Claude Code defaults. NordRelay uses the Claude Agent SDK and the host claude CLI when present.
+# Optional Claude Code executable path. Defaults to claude on PATH or the SDK bundled runtime.
 CLAUDE_CODE_CLI_PATH=
+# Optional Claude config directory. Defaults to ~/.claude.
 CLAUDE_CONFIG_DIR=
+# Default Claude Code model alias or model id.
 CLAUDE_CODE_DEFAULT_MODEL=
+# off, low, medium, high, or xhigh.
+# Options: off, low, medium, high, xhigh
 CLAUDE_CODE_DEFAULT_EFFORT=
+# default, accept-edits, plan, readonly, no-tools, or bypass-permissions.
+# Options: default, accept-edits, plan, readonly, no-tools, bypass-permissions
 CLAUDE_CODE_DEFAULT_PROFILE=default
+# Maximum agentic turns for each Claude Code prompt.
 CLAUDE_CODE_MAX_TURNS=100
 
-# Telegram output controls.
+# Operations
+# Runtime output, logging, update, and Telegram behavior controls.
+# text or json.
+# Options: text, json
 CONNECTOR_LOG_FORMAT=text
+# all, summary, errors-only, or none.
+# Options: all, summary, errors-only, none
 TOOL_VERBOSITY=summary
+# Append per-turn token usage.
 SHOW_TURN_TOKEN_USAGE=false
+# Allow /login and /logout.
 ENABLE_TELEGRAM_LOGIN=true
+# Send Telegram reactions.
 ENABLE_TELEGRAM_REACTIONS=false
+# Minimum send interval.
 TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS=80
+# Minimum edit interval.
 TELEGRAM_EDIT_MIN_INTERVAL_MS=1200
-TELEGRAM_TRANSPORT=polling
-TELEGRAM_WEBHOOK_URL=
-TELEGRAM_WEBHOOK_HOST=127.0.0.1
-TELEGRAM_WEBHOOK_PORT=8080
-TELEGRAM_WEBHOOK_PATH=/telegram/webhook
-TELEGRAM_WEBHOOK_SECRET=
+# off, status, final, or full.
+# Options: off, status, final, full
 TELEGRAM_CLI_MIRROR_MODE=status
+# Minimum mirrored edit interval.
 TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS=4000
+# off, minimal, or all.
+# Options: off, minimal, all
 TELEGRAM_NOTIFY_MODE=minimal
+# HH-HH or blank.
 TELEGRAM_QUIET_HOURS=
+# Additional comma-separated regex patterns.
 TELEGRAM_REDACT_PATTERNS=
+# auto, npm, or git.
+# Options: auto, npm, git
+NORDRELAY_UPDATE_METHOD=
+
+# Artifacts
+# File, artifact, and retention controls.
+# Max inbound/outbound file size.
 MAX_FILE_SIZE=20971520
+# Days before pruning.
 ARTIFACT_RETENTION_DAYS=7
+# Maximum artifact turns retained.
 ARTIFACT_MAX_TURNS=30
+# Maximum inbox dirs retained.
 ARTIFACT_MAX_INBOX_DIRS=30
+# Extra ignored dirs or relative paths.
 ARTIFACT_IGNORE_DIRS=
+# Extra ignored glob patterns.
 ARTIFACT_IGNORE_GLOBS=
+# Automatically send artifact files.
 TELEGRAM_AUTO_SEND_ARTIFACTS=false
 
-# State and team controls. Use sqlite for a single-file state database when
-# better-sqlite3 is available; json keeps separate human-readable files.
+# Workspace
+# State and workspace guardrails.
+# Restrict selectable workspaces.
+WORKSPACE_ALLOWED_ROOTS=
+# Warn for broad workspace roots.
+WORKSPACE_WARN_ROOTS=
+# json or sqlite.
+# Options: json, sqlite
 NORDRELAY_STATE_BACKEND=json
+# Retained audit events.
 NORDRELAY_AUDIT_MAX_EVENTS=1000
+# Write-lock TTL.
 NORDRELAY_SESSION_LOCK_TTL_MS=1800000
+# NPM version cache TTL.
 NORDRELAY_VERSION_CACHE_TTL_MS=3600000
 
-# Local WebUI dashboard. Binding to 0.0.0.0 requires either token auth or
-# basic auth; startup fails without one of these credentials.
-NORDRELAY_DASHBOARD_HOST=127.0.0.1
-NORDRELAY_DASHBOARD_PORT=31878
-NORDRELAY_DASHBOARD_TOKEN=
-NORDRELAY_DASHBOARD_USER=
-NORDRELAY_DASHBOARD_PASSWORD=
-NORDRELAY_ENV_FILE=
-
-# Optional workspace guardrails. Leave WORKSPACE_ALLOWED_ROOTS empty to allow
-# all workspaces discovered from enabled agent state.
-WORKSPACE_ALLOWED_ROOTS=
-WORKSPACE_WARN_ROOTS=
-
-# Optional voice transcription fallback. Local parakeet-coreml is used first
-# when installed; OpenAI Whisper is used when OPENAI_API_KEY is set.
+# Voice
+# Optional voice transcription settings.
+# Whisper fallback API key.
 OPENAI_API_KEY=
+# auto, parakeet, faster-whisper, or openai.
+# Options: auto, parakeet, faster-whisper, openai
 VOICE_PREFERRED_BACKEND=auto
+# Default transcription language.
 VOICE_DEFAULT_LANGUAGE=
+# Do not send voice transcripts as prompts.
 VOICE_TRANSCRIBE_ONLY=false
+# Python executable.
 FASTER_WHISPER_PYTHON=.venv/bin/python
+# Model name.
 FASTER_WHISPER_MODEL=base
+# cpu, cuda, etc.
 FASTER_WHISPER_DEVICE=cpu
+# int8, float16, etc.
 FASTER_WHISPER_COMPUTE_TYPE=int8
+# Fixed transcription language.
 FASTER_WHISPER_LANGUAGE=
+# Transcription timeout.
 FASTER_WHISPER_TIMEOUT_MS=600000
+
+# Dashboard
+# Local WebUI dashboard. User login is required for every page, API route, SSE stream, artifact download, and health endpoint.
+# WebUI bind host.
+NORDRELAY_DASHBOARD_HOST=127.0.0.1
+# WebUI bind port.
+NORDRELAY_DASHBOARD_PORT=31878
+# Optional explicit env-file path used by the CLI wrapper and dashboard.
+NORDRELAY_ENV_FILE=