Files
archie/config.example.toml
T
sam eaa436b09b docs+scripts: add archie-update-check, document missing config sections
The check-side of the reference update adapter never existed:
scripts/ had archie-update-install and archie-update-watchdog but no
archie-update-check, so any deployment that configured
chat.telegram.update_check_command pointing at the documented
"/usr/local/bin/archie-update-check" path had nothing there to run --
/update would report "not configured" regardless of what was actually
set. Add it: read-only, reports the daemon/agent components via git
describe against the local checkout and origin/main (no fetch-and-pull
the way install does), using the same "daemon"/"agent" component IDs
archie-update-watchdog's report and releaseupdate.ComponentDaemon/
ComponentAgent already use, so Service.Enrich and Report.Verify (this
session's earlier work) recognise it automatically.

Also fix archie-update-install's archie-agent build: it stamped
archied's ldflags but built archie-agent with none at all, so even a
native (non-container) archie-agent install reported an unstamped
"dev" build with installtype.Unknown.

config.example.toml gained every section that existed in the Go schema
but wasn't documented anywhere, not even commented: skills_dir,
plugin_dir, [chat.email], [chat].webhook_addr, [log], [memory] (noted
as currently unwired -- RegisterExternal is declared but never called
from cmd/archied, so the section has no effect yet), [[identities]]
(pointer to docs/architecture/identity.md rather than duplicating it),
and [[repos]].max_retries. tools.tool_policy.parallel_execution was
deliberately left undocumented: it's declared on ToolPolicy but never
read anywhere, genuinely dead rather than just underdocumented.
2026-08-24 00:32:37 +10:00

345 lines
17 KiB
TOML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#
# archied configuration
#
# Secrets are NOT stored here: each one is a {engine, key}
# reference resolved through a secrets engine at startup.
# The built-in "env" engine reads key as an environment variable name;
# "bws" (Bitwarden Secrets Manager) is compiled in. Custom engines are
# Yaegi plugins loaded from this directory -- reference implementations
# for sops, vault/openbao and age ship in examples/secret-engines/ and
# each needs its CLI on PATH plus engine-specific env (sops: SOPS_FILE;
# vault: VAULT_ADDR, VAULT_TOKEN, optional VAULT_SECRET_PATH;
# age: AGE_FILE, AGE_IDENTITY).
# secret_engine_dir = "~/.config/archie/secret-engines"
# work_dir = "~/.local/share/archie/work" # default
# db_path = "~/.local/share/archie/archie.db" # prefix for independent task and conversation SQLite files
# skills_dir = "~/.local/share/archie/skills" # SKILL.md search path; defaults under work_dir when unset
# plugin_dir = "~/.local/share/archie/plugins" # daemon plugin manifests; unset means no plugins are loaded
poll_interval = "60s"
label = "archie"
bot_user = "vectis-labs-archie"
diff_cap_lines = 400
# how many operator-triggered retries a parked task gets
# before it moves to dead (global default; set per-repo to
# override). Enforced by the dashboard's retry action.
# max_retries = 3
[forge]
type = "github"
host = "https://github.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
# How forge issues become work:
# "poll" – re-discover issues each poll_interval (default)
# "webhook" – react to GitHub webhook events the moment they arrive
# "both" – webhook plus the poll as a backstop
# intake = "poll"
# Required when intake is "webhook" or "both": the shared secret configured
# on the GitHub webhook, and the host:port the receiver listens on. On
# GitHub, set the webhook's Content type to application/json (the UI
# default) -- the alternate form-encoded delivery is not supported.
# Not supported alongside [[identities]] (each identity keeps polling).
# webhook_secret = { engine = "env", key = "ARCHIE_WEBHOOK_SECRET" }
# webhook_addr = "0.0.0.0:8645"
# [[identities]] runs more than one bot identity from a single daemon, each
# with its own forge/dispatch/models/providers/budgets/notify -- see
# docs/architecture/identity.md for the full design and constraints (e.g.
# not combinable with [forge].intake = "webhook"/"both"). Minimal shape:
# [[identities]]
# name = "personal" # required; namespaces logs/events/NATS subjects
# bot_user = "your-bot" # required
# forge = { type = "github", host = "https://github.com", token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN_PERSONAL" } }
[dispatch]
# Can be of "assignee", "label", or "either"
# this sets the method archie uses to pick up tasks.
trigger = "assignee"
# Optionally set a reaction to show that archie has picked up a task.
# setting this to "off" disables the pickup reactions.
ack_reaction = "eyes"
# dispatch.labels maps each task lifecycle state to the label
# Archie applies on the issue.
# You can rename labels to match your project's conventions,
# or comment one out to skip that transition.
# The labels are the *source of truth* for the dispatch loop: Archie
# scans for issues bearing queued, then moves them through working →
# waiting → pr → parked (→ dead when max_retries is exhausted).
[dispatch.labels]
queued = "archie:queued"
working = "archie:working"
waiting = "archie:waiting"
pr = "archie:pr"
parked = "archie:parked"
# dead = "archie:dead" # state label for a task that exhausted max_retries
[models] # role -> ai-sdk runtime ref (used by agent workflows)
triage = "openai/gpt-5.4"
planner = "openai/gpt-5.4"
builder = "openai/gpt-5.4"
[providers.openai]
class = "openai"
api_key = { engine = "bws", key = "OPENAI_API_KEY" }
# api_key_env = "OPENAI_API_KEY" # backwards-compatible environment form
[providers.ollama]
class = "ollama"
# [chat]
# `operator` is the display name of user. It is
# passed to the chat agent as runtime metadata, which means it is sent to the
# configured model provider on every turn -- leave it unset to tell the agent
# nothing about who is running it.
# operator = "John Smith"
# `workspace` roots the chat agent's file and shell tools (read, write, edit,
# shell, grep, find). If unser, the tools aren't registered.
# Set it to let the agent read, modify and execute inside that directory
# choose it deliberately
# workspace = "~/.local/share/archie/workspace"
# `max_steps` caps the model/tool round-trips in a single chat turn
# (default 100). This is a task budget, not a safety limit.
# max_steps = 100
# Let read/write/edit/find/grep tools reach absolute paths outside the
# workspace jail. Relative paths still resolve against workspace.
# The shell tool is never confined, so a jail only pushes the agent into
# using shell for everything, losing truncation, line numbering, and
# read-before-write protection. Enable when the agent needs to work
# cross-filesystem (disk ops, system edits, etc.). Grant deliberately.
# unrestricted_filesystem = true
# Render each completed tool call inline in the reply, naming the tool and one
# line of its result, before the answer built from them. Off by default: it is
# there to make a wrong tool choice visible from the chat, at the cost of
# narrating every internal step. Applies to every chat channel -- Telegram
# and the web dashboard both read this one setting.
# show_tool_calls = true
# Optional interactive-chat catalog. /provider groups these references by
# their first path segment, and /model shows only the selected provider's
# entries. When omitted, Archie uses the distinct refs in [models].
# models = [
# "openai/gpt-5.6-sol",
# "openrouter/openai/gpt-5.6-sol",
# ]
# Optional self-hosted update adapter. Both values are argv arrays (never
# shell snippets). The check command must write a releaseupdate.Snapshot JSON
# document to stdout; configure the installer as well to show Approve/Defer.
# [chat.telegram]
# update_check_command = ["/usr/local/bin/archie-update-check"]
# update_install_command = ["/usr/local/bin/archie-update-install"]
# Inbound email as a chat channel, via SMTP. Empty listen_addr disables it.
# [chat.email]
# listen_addr = "0.0.0.0:2525" # inbound SMTP server
# relay_addr = "smtp.example.com:587" # outbound relay for replies
# Generic inbound webhook gateway: external services push messages into
# chat for LLM processing (deliver-only, no outbound reply channel). This
# is a distinct surface from [forge].webhook_addr (forge issue events) and
# [capture] (unbound event storage for later binding) -- three different
# inbound HTTP concerns that happen to share the word "webhook".
# webhook_addr = "0.0.0.0:8646" # under [chat], not [chat.telegram]
# External MCP tools are launched and managed by Archie's MCP client. A
# command of "npx" gets a persistent package cache under work_dir
# (top of this file) automatically, so a daemon restart reuses it instead
# of re-resolving and re-downloading the package from the npm registry
# every time. This does not cover a package's own separate downloads (e.g.
# a Playwright/Puppeteer-based server fetching a browser binary from a CDN
# via its postinstall script) -- consult that package's own env vars for
# those.
# [[tools.mcp_servers]]
# name = "desktop-commander"
# transport = "stdio"
# command = "npx"
# args = ["-y", "@wonderwhy-er/desktop-commander@0.2.46", "--no-onboarding"]
# work_dir = "/path/to/workspace"
[agent]
# How the daemon invokes the agent:
# "inprocess" – run agent logic directly in the daemon (default)
# "subprocess" – spawn `command` as a child, communicating over stdin/stdout
# "nats" – dispatch tasks over NATS (requires [nats]; add [containers] for Docker sandboxing)
mode = "inprocess"
# Binary to launch when mode = "subprocess".
command = "archie-agent"
# Environment variables forwarded to the agent process (subprocess/nats modes).
# env = ["GOCACHE"]
# Workspace code-search index. Paths default under work_dir when unset.
[indexing]
# Code-search index files (default: <work_dir>/indexes).
# index_dir = "/var/lib/archie/indexes"
# Per-index lifecycle metadata DB (default: <work_dir>/workspace-indexes.db).
# db_path = "/var/lib/archie/workspace-indexes.db"
# Web dashboard and API: task board, activity stream, chat, config,
# logs, memory, SSE events. Served as an embedded SPA with a full REST
# and streaming API. Auth is token-based for non-loopback addresses;
# loopback binds (127.0.0.1, ::1, localhost) skip auth automatically.
# Set to "off" (or leave empty) to disable.
[web]
listen = "127.0.0.1:8484"
# Where archied writes its logs. Without file set, output goes only to
# stderr -- which under systemd means journald holds the sole copy, and
# running by hand leaves no record at all. Setting file gives a durable
# copy independent of the supervisor, and is what lets the dashboard show
# history from before it connected. Both stderr and the file get output
# unless quiet is set.
# [log]
# file = "~/.local/share/archie/logs/archied.log"
# max_size_mb = 20 # rotate once the file exceeds this; 0 uses the default (20)
# keep = 5 # rotated files to retain; 0 uses the default (5)
# level = "info" # "debug" | "info" | "warn" | "error"
# quiet = false # true suppresses stderr once a file is configured
# The built-in file-backed memory provider (MEMORY.md + USER.md under
# work_dir) is always on -- nothing here is required to get memory at all.
# [memory] exists to register an EXTERNAL provider alongside it, but as of
# this writing that wiring (memory.Manager.RegisterExternal) is not called
# anywhere in cmd/archied, so setting this section currently has no effect.
# Left here so the schema is documented, not because it does anything yet.
# [memory]
# provider = "" # external provider identifier; currently unwired
# session_ttl = "0s"
# [memory.provider_config]
# # key = "value" # provider-specific settings
# Notifications for human-in-the-loop moments
# (approval requests, gate failures, parked tasks).
# Archie POSTs a JSON payload to the webhook
# wire it to n8n, email, Slack, or any HTTP endpoint.
[notify]
# webhook = "https://n8n.example.com/webhook/archie"
[budgets]
max_steps = 60
max_tokens = 400000
wall_clock = "30m"
gate_max_failures = 5
# NATS JetStream for task distribution and reaction delivery. mode selects
# how NATS is provided:
# "embedded" – in-process nats-server (the default; no external server)
# "external" – connect to url (required for agent.mode="nats" / [containers])
# "off" – no NATS; the SQLite ClaimNext flow is used for tasks
# Leave the section absent (or set no url) to run embedded; set mode="off"
# only to opt out of NATS entirely.
# [nats]
# mode = "embedded" # "embedded" | "external" | "off"
# url = "nats://localhost:4222" # required when mode = "external"
# token_env = "NATS_TOKEN" # optional; named variable must be set
# Unbound webhook capture: POST /webhooks/capture/{source} accepts and
# stores any inbound payload archie doesn't yet have a binding for, so it can
# be inspected and mapped later (see docs/prds/event-capture-storage.md).
# Stored in the same SQLite database as tasks, not NATS -- capture has one
# writer and one (human, dashboard) reader, so it doesn't need JetStream's
# fan-out/replay machinery, and SQLite is available in every deployment
# shape unconditionally. All fields default when the section is absent;
# capture is on by default.
# [capture]
# retention = "168h" # 7 days; prune-on-write deletes anything older
# max_events = 5000 # row cap, pruned on every insert regardless of age
# max_body_bytes = 262144 # 256 KiB; larger POSTs are rejected with 413
# rate_per_second = 1.0 # per-remote-address token bucket
# rate_burst = 5
# Docker sandbox execution of archie-agent. Requires [nats] and agent.mode = "nats".
# [containers]
# enabled = true
# image = "archie-agent:latest" # Docker image to run
# max_concurrency = 4 # max simultaneous tasks/containers
# max_uptime = "60m" # container lifetime cap
# volume_ttl = "72h" # max age for persistent repo volumes and Git clone caches
# pull_policy = "missing" # "missing" or "always"
# At least one [[repos]] entry is required before archied will poll
# anything -- it is deliberately left commented rather than shipped active:
# an active example here validates as a normal, working repo (owner/name are
# only checked for non-empty), so archied would silently start polling a
# repository that doesn't exist. archied setup does not write this section
# ([[repos]] is an array of tables, which the text-patching setup uses
# cannot target) -- add at least one entry by hand.
#
# [[repos]]
# owner = "your-github-username"
# name = "todo"
# base = "main"
# ecosystem = "go" # "go", "python", "node", "rust", or "custom"
# # Override the ecosystem defaults when needed:
# # preflight = [["go", "version"]]
# # test_glob = "*_test.go"
# protect = ["_templ.go"]
# gate = [
# ["templ", "generate", "./components/"],
# ["go", "vet", "./..."],
# ["go", "build", "./..."],
# ["golangci-lint", "run"],
# ["go", "test", "./...", "-count=1"],
# ]
# # allow_concurrent = true # let the daemon run multiple tasks for this repo at once instead of
# # FIFO-serializing them; only safe when concurrent worktrees won't collide
# # (e.g. different base branches or packages per task). Still bounded by
# # [containers].max_concurrency globally.
# # persistent_storage = true # reuse a per-repo Docker volume and Git object cache until volume_ttl
# # max_retries = 5 # per-repo override of the global max_retries above
# ── Tools ───────────────────────────────────────────────────────────────────
# Limits on what a tool may return. These bound how much of the context window
# one tool call can spend: the workspace file tools truncate themselves, but
# skill bodies and MCP server results otherwise arrive whole.
#
# Zero (or absent) takes the default. A NEGATIVE value disables the limit --
# zero cannot mean "off" because it is indistinguishable from an unset key.
# [tools.tool_policy]
# max_result_chars = 50000 # cap on one tool result; -1 for no cap
# turn_budget_chars = 200000 # cap on all tool results in one chat turn; -1 for no cap
# spill_dir = "" # unset by default, which truncates oversized results
# # inline. When set, a result over the cap is written
# # here in full and the model is handed the path.
# # It MUST be inside chat.workspace: the read tool
# # refuses paths outside it, so a spill anywhere else
# # is a reference the model cannot open -- worse than
# # truncating. Startup warns if it is outside.
# # Task agents work in their own worktree and cannot
# # read it at all; they always truncate.
# The web_fetch tool: retrieve a URL and return readable text.
# [tools.web_fetch]
# enabled = true # set false to withdraw the tool entirely
# timeout = "30s"
# max_bytes = 2000000
# allow_private_networks = false
# # Off by default, and worth leaving off. archied's own dashboard, NATS and
# # the Docker API answer on loopback and private addresses, and the URL to
# # fetch arrives through chat -- an untrusted path, since a forge issue body
# # or an inbound email can be quoted into a turn. The address is checked at
# # dial time rather than on the URL string, so a public name that resolves to
# # a private address is refused too. Turn this on only for a homelab endpoint
# # you intend Archie to reach.
# The generate_video tool: text-to-video via MiniMax's API. Off by default,
# unlike web_fetch -- this spends real API credits per call, so it needs an
# explicit opt-in and a working key before it is registered at all.
# [tools.minimax]
# enabled = true
# api_key = { engine = "env", key = "MINIMAX_API_KEY" }
# base_url = "" # override the API host; leave unset in normal operation
# # Generation is synchronous from the model's point of view: the tool call
# # blocks until MiniMax reports the video ready or failed, which can take
# # several minutes. The result is a hosted URL delivered through whatever
# # channel supports gateway.MediaSender (Telegram today); channels without
# # that support get the URL as a plain link in the reply text instead.