# === Telegram (required) === BOT_TOKEN=your-telegram-bot-token ALLOWED_USERS=your-telegram-user-id # === AI Provider (choose one) === # Options: groq | nvidia-llama-3.3-70b | gemini-2.5-flash | gpt-4o | openrouter | claude-sdk | ollama # Free providers: groq, nvidia-llama-3.3-70b, gemini-2.5-flash # claude-sdk (Agent SDK): premium — full agent with tool use; sign in once with `claude login` (subscription) or set the API key below PRIMARY_PROVIDER=groq # Fallback chain (comma-separated, tried in order if primary fails) # FALLBACK_PROVIDERS=nvidia-llama-3.3-70b,gemini-2.5-flash # === API Keys (set the one for your chosen provider) === # Groq — free at console.groq.com (fallback for voice transcription) GROQ_API_KEY= # Voice transcription runs on THIS machine when a local Whisper is installed # (see README, "Local speech-to-text") — no key and no network needed. Groq is # only used when the local path is unavailable. To change that: # STT_LOCAL=off never transcribe locally # STT_PREFER=groq try the network first, local as the fallback # Google Gemini — free tier at aistudio.google.com GOOGLE_API_KEY= # NVIDIA NIM — free tier at build.nvidia.com NVIDIA_API_KEY= # OpenAI — paid, platform.openai.com OPENAI_API_KEY= # API key for the Agent SDK provider, alternative to the CLI sign-in ANTHROPIC_API_KEY= # OpenRouter — openrouter.ai, 387 models incl. ~20 free ones with tool calling. # With this set, `/openrouter free` lists what actually answers right now and # `/openrouter add ` wires a model into the fallback chain. The catalogue # (`/openrouter search`) works without a key. OPENROUTER_API_KEY= # Optional, and ONLY for showing the account credit balance: OpenRouter refuses # /credits to ordinary keys ("Only management keys can fetch credits"). This key # can also create and delete API keys, so leave it empty unless you want that # one number. Create it at openrouter.ai → Management Keys. OPENROUTER_MANAGEMENT_KEY= # === Agent === WORKING_DIR=~ # Timezone used for the bot's sense of "now" (IANA name, e.g. Europe/Berlin). # Optional — defaults to the host's timezone, which is right on a normal # desktop install. Worth setting on a server or in Docker, where the host is # usually UTC while you think in local time. # BOT_TIMEZONE=Europe/Berlin # Global sub-model of the Agent SDK provider. Normally chosen via # /provider — this is just where that choice is stored, so it survives a # restart. (/model only changes the lane you are in.) Accepts a CLI tier alias # (opus | sonnet | haiku | fable, each auto-resolving to that tier's newest # model) or a pinned full model id. Unset = opus. "inherit" = let the # agent CLI pick, which is whatever ITS settings default to. # CLAUDE_SDK_MODEL=opus # Automatic lane titles (on by default). A lane you named yourself is never # touched. Titles are made by the lane's own model after the answer, at most # once per topic; "off" disables them. The two caps limit the calls per day. # LANE_TITLES=off # LANE_TITLE_MAX_PER_LANE_DAY=12 # LANE_TITLE_MAX_PER_DAY=60 # Optional hard daily-spend cap (OFF by default — the bot is never blocked). # To enable a runaway-cost brake, set BOTH a positive limit AND BUDGET_ENFORCE=1. # Leaving these unset/commented means no budget blocking at all. # MAX_BUDGET_USD=5.0 # BUDGET_ENFORCE=1 # === Web UI === WEB_PORT=3100 # WEB_PASSWORD=your-password # === Optional Platforms === # WHATSAPP_ENABLED=true # DISCORD_TOKEN=your-discord-bot-token # SIGNAL_API_URL=http://localhost:8080 # SIGNAL_NUMBER=+491234567890 # === Custom Chrome (for WhatsApp, if not auto-detected) === # CHROME_PATH=/usr/bin/google-chrome # =================================================================== # OPTIONAL — Security & Auth # =================================================================== # Auth mode for new users trying to talk to the bot. # allowlist (default) — only ALLOWED_USERS can use the bot # pairing — new users get a 6-digit pairing code; owner approves # open — anyone can chat (for public bots) # AUTH_MODE=allowlist # Session isolation (how context is scoped): # per-user (default) — each user gets their own session # per-channel — everyone in the same channel shares a session # per-channel-peer — per (channel, user) pair # SESSION_MODE=per-user # =================================================================== # OPTIONAL — Text-to-Speech (TTS) # =================================================================== # TTS backend: "edge" (free, default) or "elevenlabs" (paid, higher quality) # TTS_PROVIDER=edge # ElevenLabs — set all three to use ElevenLabs TTS # ELEVENLABS_API_KEY= # ELEVENLABS_VOICE_ID=iP95p4xoKVk53GoZ742B # ELEVENLABS_MODEL_ID=eleven_v3 # =================================================================== # OPTIONAL — Webhooks # =================================================================== # Enable inbound webhook endpoint (POST /api/webhook) for external triggers # WEBHOOK_ENABLED=false # WEBHOOK_TOKEN=change-me-to-a-random-secret # =================================================================== # OPTIONAL — Sub-Agents & Compaction # =================================================================== # Maximum number of sub-agents that can run in parallel (default: 4) # MAX_SUBAGENTS=4 # Sub-agent hard timeout in ms. -1 = unlimited (default: -1) # SUBAGENT_TIMEOUT=-1 # Context compaction threshold in tokens (default: 80000) # COMPACTION_THRESHOLD=80000 # Warn in-chat once a session's transcript file has grown past this size in # MB (re-warns only after it doubles). Default: 4 # CONTEXT_WARN_MB=4 # OPT-IN: automatically start a fresh model session once the session # transcript outgrows this size in MB (recent history is re-bridged; memory, # notes and workspace stay). Unset = off (default). # CONTEXT_AUTO_ROTATE_MB=6 # =================================================================== # OPTIONAL — Browser Automation # =================================================================== # Connect to an existing Chrome DevTools Protocol endpoint instead of # launching a new browser instance. # CDP_URL=ws://localhost:9222 # Port for the optional browser HTTP gateway (default: 3800) # BROWSE_SERVER_PORT=3800 # =================================================================== # OPTIONAL — Data Directory # =================================================================== # Override where alvin-bot stores its data (default: ~/.alvin-bot) # ALVIN_DATA_DIR=/custom/path/to/data # =================================================================== # OPTIONAL — Log Rotation # =================================================================== # How many days of bot logs to keep (default: 30, valid: 0-3650). Once a day # the bot trims its live logs (/logs/alvin-bot.out.log / .err.log) # to this window and deletes finished log files in that folder that are older. # The live logs are only ever trimmed when the writer's append mode has been # verified — otherwise they are left alone. Set to 0 to disable entirely. # LOG_RETENTION_DAYS=30 # Live steering — inject follow-up instructions mid-generation (default: on) # STEERING_ENABLED=true # Real-time token streaming — the Agent SDK provider emits partial # (mid-block) chunks as the model generates, instead of one chunk per # finished block (default: on). Set to false/0 to fall back to the # pre-streaming block-level behavior — useful as an operational kill switch # if a downstream consumer misbehaves on partial chunks. # TOKEN_STREAMING=true # The same for every OpenAI-compatible endpoint — Groq, Gemini, OpenAI, NVIDIA, # OpenRouter, a local or hosted Ollama, and your own endpoints (default: on). # The tool loop reads the endpoint's event stream and shows the answer while it # is being written. An endpoint that cannot stream falls back on its own, so # this is not needed for that; set it to `off` only if a third-party endpoint # sends fragments your setup cannot handle. It restores the previous behaviour # in full: one request with `stream: false`, one complete answer at the end. # OPENAI_TOOL_STREAM=on # Interactive turns on OpenAI-compatible endpoints no longer stop at a round # COUNT (measured 2026-09-04: models that call one tool per round died at a # cap sized for models that bundle several — same work, different style). What # ends a turn that does not finish on its own: stall detection (the identical # tool call repeated, or ten rounds in a row in which no tool produced a result # it had not produced before), a wall-clock watch, an optional cost watch, and # a hard emergency ceiling of 2000 rounds. NONE of these can end a turn before round # 50 — the point where the old cap closed — so nothing that used to run is ever # cut shorter; inside those first 50 rounds a detected repetition is handed to # the model as a hint on the tool result instead of ending the turn. # OPENAI_TOOL_TIME_BUDGET_MS caps the wall-clock time of ONE PROVIDER ATTEMPT # (default 3600000 = 60 min; 0 disables the watch). A turn the TIME or COST # watch stopped is not retried on the next provider in the chain, so in # practice that is the whole turn: a budget that starts over at every link # would be three times the stated figure on a three-provider chain. A STALL is # different — it is a model-specific failure, so unless the turn already ran a # writing tool it moves to the next provider exactly as before. # OPENAI_TOOL_COST_BUDGET_USD caps one attempt's estimated spend the same way, # but is OFF by default. The figure it compares is a flat $0.001 per 1000 # tokens for every paid model regardless of price — a placeholder, not a bill. # Measured 2026-09-04: with a $2 default, a turn on a local-URL `:cloud` model # whose history grows by 5000 tokens per round ended at exactly round 50, the # very wall this change removes; and a default high enough to carry the longest # real run measured (round 109) would have to sit near $31, which means # something 15x different depending on the model. Set it if your endpoint is # genuinely metered per token and you want a per-turn ceiling; the day-wide # MAX_BUDGET_USD meter is unaffected either way. # OPENAI_TOOL_ROUNDS is the way back: it restores a fixed round count for # interactive turns AND, like a caller's own budget, switches off the stall # detection and both watches — you get exactly the old behaviour, not a # stricter one. Explicit budgets (cron jobs, sub-agents that were spawned with # their own maxTurns) take that same path and keep exactly their round count # with none of the new watches; a sub-agent WITHOUT its own budget runs like an # interactive turn. # OPENAI_TOOL_TIME_BUDGET_MS=3600000 # OPENAI_TOOL_COST_BUDGET_USD= # OPENAI_TOOL_ROUNDS= # How long the automatic empty-turn RETRY may stay completely silent before it # is written off, in ms. Applies to the second attempt only, and only until its # first chunk. The default is coupled to TOKEN_STREAMING above, because that # flag decides when the first chunk can appear at all: with streaming on the # first chunk lands in seconds (default 60000), with it off nothing is emitted # until a whole text block is finished, which measured 73 s on a heavy prompt # (default 300000). Set this only to tune those defaults — e.g. after raising # ALVIN_STUCK_TIMEOUT_MINUTES, or on a very slow model. # ALVIN_EMPTY_STREAM_RETRY_TIMEOUT_MS=60000 # =================================================================== # POWER / OWNER OPT-INS — unlock full capability # # These are safe-by-default for unconfigured installs. As the owner # you can opt in to the full power mode for each feature. # =================================================================== # Shell & Python execution security: # allowlist (default) — only a curated set of safe binaries (ls, cat, git, # python3, node, etc.) can be executed by the bot # full — unrestricted shell/Python — full agent power mode; set this # when you want the bot to run arbitrary commands on your machine # deny — block all exec/python tool calls (read-only agent) # EXEC_SECURITY=allowlist # OPTIONAL — operator opt-out for the extended safety guards. # By default the bot refuses recursive deletes of your home/user folders and # writes to credential/persistence files (.env, .ssh, shell rc) even in full # mode. Set to 1 if you explicitly want the agent to manage those too. # Truly catastrophic commands (rm -rf /, mkfs, dd to raw devices, fork bombs, # system directories) stay blocked no matter what. # ALVIN_ALLOW_PROTECTED_WRITES=0 # OPTIONAL (macOS) — folder-access watch. Every 15 minutes the bot checks the # folders your active jobs use (drives under /Volumes, Desktop, Documents, # Downloads, iCloud Drive) and notifies you once if macOS blocks access until # a permission dialog is confirmed. Add more folders comma-separated, or set # "off" to disable the watch. # ALVIN_WATCH_PATHS=/Volumes/MyDrive,/Users/me/Archive # OPTIONAL — start deadline for Agent SDK turns in milliseconds (digits only). # If the CLI sends no first message within it (typically a macOS permission # prompt is holding the start), the turn is aborted with a clear notice # instead of waiting for the 10-minute hang guard, and other lanes that use # the CLI are skipped for that turn. 0 turns it off; above 3600000 counts as # 3600000. # ALVIN_SDK_START_FRIST_MS=90000 # OPTIONAL — process watch (macOS/Linux, off when the bot is PID 1). Every # 10 min it samples CPU time; orphaned processes of your user (ppid 1) with # >= 90 % of a core in 6 samples in a row are reported once (default). # With "an" it also stops a process, by PID, but only if it came from an agent # shell (its output goes to an agent task output file, or a deleted zsh # here-document is its input), # was not detached on purpose (no setsid/nohup, not its own process group, the # starting shell is gone) and everything could be read; on macOS SIGHUP cannot # be read, so there it only reports. Identity is re-checked before SIGTERM and # SIGKILL. # melden = report only (default) | an = also stop | aus = off # ALVIN_PROZESS_WAECHTER=melden # OPTIONAL — how many characters a single tool result may return on the # generic provider path (everything except the Agent SDK). Anything longer is cut and the # notice names the way to the rest, so nothing is lost either way: read_file # takes an `offset` to continue, the other tools say how to get more. # Raise one of these only if every model you fall back to has room for it — # the same limit serves a million-token window and a local 8k one. # Minimum 500; anything smaller or unparseable keeps the default. # ALVIN_TOOL_OUTPUT_READ_FILE_CHARS=20000 # ALVIN_TOOL_OUTPUT_RUN_SHELL_CHARS=8000 # ALVIN_TOOL_OUTPUT_RUN_SHELL_ERROR_CHARS=2000 # ALVIN_TOOL_OUTPUT_LIST_DIRECTORY_CHARS=8000 # ALVIN_TOOL_OUTPUT_PYTHON_CHARS=10000 # ALVIN_TOOL_OUTPUT_PYTHON_ERROR_CHARS=3000 # Web UI host binding: # 127.0.0.1 (default) — loopback only, not reachable from LAN or internet # 0.0.0.0 — listen on all interfaces (expose to LAN/VPS/remote) # If you set WEB_HOST=0.0.0.0 (or any non-loopback address), also set # WEB_PASSWORD to protect the UI: # WEB_HOST=127.0.0.1 # WEB_PASSWORD=your-strong-password # Allow the bot to fetch localhost / LAN / internal URLs (SSRF guard): # unset or 0 (default) — private IPs and loopback are blocked to prevent # SSRF attacks from untrusted prompt content # 1 — enable, so the bot can reach your local services, dev # servers, and internal APIs (owner workflow on your own machine) # ALLOW_PRIVATE_FETCH=0 # =================================================================== # OPTIONAL — Local models: tool path, eyes, documents (v5.133.0) # =================================================================== # A model served by a local Ollama is measured once, on the first turn in # which it reaches for a tool: native tool calls, the text protocol, and a # read-then-write chain. Afterwards the lane takes the simplest path that # passed. Set this to decide instead of measuring — and to skip the # measurement entirely: # nativ — native function calling, one plain tool loop # protokoll — the text protocol, one plain tool loop # harness — the offline harness (broker plus planning loop) # WERKZEUGWEG=nativ # Switch the measurement off without forcing a path. The lane then runs on # the capabilities its provider entry claims, exactly as before v5.133. # FAEHIGKEITSPROBE=off # Switch the offline harness off. A model measured as needing it runs in the # plain tool loop instead — honest, but weaker on multi-step tasks. # OFFLINE_AGENT_LOOP=off # Step and time budget of the offline harness. They exist to stop a runaway # loop, not to cap the work: defaults are 32 steps and 1800 seconds. # OFFLINE_LOOP_MAX_STEPS=32 # OFFLINE_LOOP_MAX_SECONDS=1800 # Reserved for the cloud layer of the eyes, which is empty in 5.133 — setting # it changes nothing today. Layer 0 is the macOS Vision framework, layer 1 a # LOCAL vision model in Ollama (`ollama pull gemma4:e4b`); cloud-proxied # models are never used for images. # AUGEN_CLOUD=1 # No effect since 5.133. The prompted-tool broker it used to enable now runs # inside the offline harness only, where it is switched on by the measured # tool path rather than by this variable. # OFFLINE_STRUCTURED_TOOLS=1 # Where the bot puts temporary files — uploaded photos and documents, renders, # recordings, browser artefacts — and the one directory its sweeper clears. # Default: /alvin-bot. Point it elsewhere to keep a second # instance (or a test run) out of the running bot's folder. # ALVIN_TMP_DIR=/custom/path/to/tmp