.env.example

# =============================================================================
# Remote Personal Coding Agent — configuration
# Copy to `.env` and fill in. NEVER commit `.env`.
# =============================================================================

# -----------------------------------------------------------------------------
# INTERFACES — pick Telegram, Web, or both. Each is an optional client of the
# same core: same tasks, same approvals, same budgets, same task ids.
# -----------------------------------------------------------------------------
# Default: on when TELEGRAM_BOT_TOKEN is set, off otherwise.
# Set to false to run web-only even with a token configured.
TELEGRAM_ENABLED=

# The browser interface. Before enabling, create a password once with:
#   npm run agent -- web setup
WEB_ENABLED=false

# Localhost only by default. Change ONLY for trusted private networks — see
# "Remote access" in the README before touching this.
WEB_HOST=127.0.0.1
WEB_PORT=8787

# How long a browser sign-in lasts. Sessions also end when the agent restarts.
WEB_SESSION_TTL_HOURS=168

# -----------------------------------------------------------------------------
# TELEGRAM (free — Telegram Bot API has no fee). Only needed if enabled.
# -----------------------------------------------------------------------------
# From @BotFather
TELEGRAM_BOT_TOKEN=

# Your numeric Telegram user id (from @userinfobot). Comma-separated list allowed.
# ONLY these ids may control this machine. Everyone else is ignored.
AUTHORIZED_TELEGRAM_USER_ID=

# Long polling (outbound only, no inbound port) — strongly recommended.
# Webhook mode would require a public inbound endpoint; not supported by design.
TELEGRAM_POLLING=true

# -----------------------------------------------------------------------------
# AGENT PROVIDER
# -----------------------------------------------------------------------------
# Which agent CLI does the work: copilot | claude
#
# copilot — GitHub Copilot CLI. Billed to your existing Copilot subscription,
#           so the running cost of this project stays zero.
# claude  — Claude Code. Billed to your Anthropic plan or API credits, which is
#           NOT covered by a Copilot subscription. Set COPILOT_MODEL to a Claude
#           Code alias (opus | sonnet | haiku) when you use it, and note that
#           MAX_AI_CREDITS_PER_TASK is then read as US dollars.
#
# An unrecognised value stops startup rather than quietly falling back.
# This sets the DEFAULT: the web interface can pick any installed, signed-in
# provider per task, and each task bills to the provider that ran it.
AGENT_PROVIDER=copilot

# -----------------------------------------------------------------------------
# COPILOT CLI
# -----------------------------------------------------------------------------
# Model id as understood by the INSTALLED Copilot CLI.
# Run `remote-agent models` to list what your CLI actually supports — the
# catalogue changes between CLI versions, so never assume.
COPILOT_MODEL=claude-opus-5

# Used if COPILOT_MODEL is not offered by your CLI build.
# Leave empty to fail fast instead of falling back.
COPILOT_MODEL_FALLBACK=claude-opus-4.8

# Reasoning effort: none | minimal | low | medium | high | xhigh | max  (empty = CLI default)
COPILOT_EFFORT=

# Custom agent (see .github/agents/remote-engineer.md). Use `none` to disable.
# It is installed to <COPILOT_HOME>/agents automatically on start, so it applies
# to every registered project without modifying any of your repositories.
# NB: this is COPILOT_CUSTOM_AGENT, not COPILOT_AGENT — VS Code's integrated
# terminal already uses COPILOT_AGENT for something else.
COPILOT_CUSTOM_AGENT=remote-engineer

# Run the agent in autopilot mode (autonomous continuation).
COPILOT_AUTOPILOT=true

# Hard cap on autopilot continuation messages — the CLI's own runaway guard.
MAX_AUTOPILOT_CONTINUES=5

# Run the agent's shell commands inside the Copilot CLI's OS-level sandbox
# (experimental; Windows 11 / macOS / Linux+bwrap). This is the ONLY real
# containment boundary — without it, shell commands run with your full user
# rights and the deny-list is only defence in depth. It can break some builds,
# so it is opt-in. Strongly recommended if you run tasks against code you did
# not write.
COPILOT_SANDBOX=false

# Path to the copilot executable. Empty = auto-detect from PATH.
COPILOT_BIN=

# -----------------------------------------------------------------------------
# COST PROTECTION  (see README "Cost")
# -----------------------------------------------------------------------------
# Stop a task once it has consumed this many AI credits / premium requests.
# When this is >= 30 it is ALSO passed to the CLI as `--max-ai-credits`, which
# blocks the next model call in-process (the CLI rejects smaller values).
# Below 30 it is enforced by this application between Copilot invocations.
# 0 = no app-level cap (NOT recommended).
MAX_AI_CREDITS_PER_TASK=10

# Rolling 24h budget across all tasks. 0 = disabled.
MAX_AI_CREDITS_PER_DAY=50

# Wall-clock ceiling for a single task.
MAX_TASK_DURATION_MINUTES=30

# Automatic recovery attempts after failing tests/build.
MAX_RETRIES=2

# Tasks executed simultaneously. Keep at 1 unless you know what you are doing.
MAX_CONCURRENT_TASKS=1

# -----------------------------------------------------------------------------
# GIT BEHAVIOUR
# -----------------------------------------------------------------------------
AUTO_COMMIT=true
# Pushing is OFF by default and requires approval even when enabled.
AUTO_PUSH=false
# Allow an auto-commit when the project declares no test/build command at all.
# Off by default: unverified work should not be committed silently.
ALLOW_COMMIT_WITHOUT_VERIFICATION=false
# Snapshot uncommitted work into a recoverable git object before touching anything.
GIT_CHECKPOINT=true
# Ask via Telegram before working in a repository with uncommitted changes.
REQUIRE_APPROVAL_WHEN_DIRTY=true
# Branches the agent must never commit/push to directly.
PROTECTED_BRANCHES=main,master,production,release

# -----------------------------------------------------------------------------
# APPROVALS & SAFETY
# -----------------------------------------------------------------------------
REQUIRE_APPROVAL_FOR_DANGEROUS_ACTIONS=true
# How long an approval request waits before the task is cancelled.
APPROVAL_TIMEOUT_MINUTES=60
# Extra shell commands the agent may never run (comma separated, added to defaults).
EXTRA_DENIED_COMMANDS=

# Extra environment variables to forward to the Copilot process. The child gets
# an ALLOW-LIST of toolchain variables only; credentials and code-injection
# variables (NODE_OPTIONS, PYTHONSTARTUP, JAVA_TOOL_OPTIONS, LD_PRELOAD, ...)
# are withheld. Name one here only if a build genuinely needs it.
COPILOT_ENV_PASSTHROUGH=

# Load the TARGET repository's AGENTS.md / CLAUDE.md / copilot-instructions.md
# as agent instructions. Off by default: those files live in the repository the
# agent is working on, so enabling this turns repository content into
# instructions (indirect prompt injection).
COPILOT_REPO_INSTRUCTIONS=false

# Keep the built-in GitHub MCP server enabled. Off by default: it talks to the
# GitHub API with your identity over HTTP, so it is NOT covered by ALLOWED_URLS
# and is a ready-made exfiltration channel (gists, issues, private repos).
COPILOT_GITHUB_MCP=false
# Domains the agent may reach. Everything else is denied.
# NOTE: writable GitHub endpoints (api/gist/uploads) are always denied on top of
# this, because they are an exfiltration channel for an authenticated machine.
ALLOWED_URLS=registry.npmjs.org,pypi.org,files.pythonhosted.org,objects.githubusercontent.com,github.com

# -----------------------------------------------------------------------------
# VERIFICATION
# -----------------------------------------------------------------------------
RUN_TESTS=true
RUN_BUILD=true
# Ceiling for a single test/build command.
VERIFY_TIMEOUT_MINUTES=15

# -----------------------------------------------------------------------------
# ORCHESTRATION
# -----------------------------------------------------------------------------
# How much AI to spend is decided in plain code, for free: the request is
# classified, and a read-only survey or review is added only when it is likely
# to pay for itself. Trivial work always costs exactly one session.
#
# false = always exactly one Copilot session per attempt (cheapest, least safe).
ORCHESTRATION=true
# Hard ceiling on paid Copilot sessions per task, counting retries, the
# read-only survey and the review. A plan that does not fit is trimmed rather
# than promised. 4 allows the full survey → implement → review → fix loop.
MAX_AGENT_CALLS_PER_TASK=4
# After tests pass, the system scores its own confidence from evidence (tests,
# diff size, retries, paths touched). Below this it buys a review; above it, it
# stops. Raise it to review more often and spend more; lower it to spend less.
REVIEW_CONFIDENCE_THRESHOLD=0.75

# -----------------------------------------------------------------------------
# STORAGE / LOGGING
# -----------------------------------------------------------------------------
# Where the SQLite database and logs live. Empty = ./data
AGENT_WORKSPACE=
# Project registry file. Empty = ./config/projects.json
PROJECTS_FILE=
LOG_LEVEL=info

# -----------------------------------------------------------------------------
# HEARTBEAT
# -----------------------------------------------------------------------------
# One Telegram message per day proving the agent is alive (zero AI credits).
# If the morning ping does not arrive, the agent or the PC is down.
DAILY_HEARTBEAT=true
# Local hour (0-23) at which the heartbeat is sent.
DAILY_HEARTBEAT_HOUR=9