Files
archie/config.example.toml
T

390 lines
20 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
# module_dir = "~/.local/share/archie/modules" # EDA playbook Module action kinds (log.go etc.); unset means no modules loaded
# workflow_routing_file = "~/.local/share/archie/workflow-routing.yaml" # kind->workflow rebinding (bug/feature/bootstrap)
# workflow_labels_file = "~/.local/share/archie/workflow-labels.yaml" # arbitrary forge label -> workflow (EDA playbook slice 2)
# playbook_dirs = ["~/.local/share/archie/workflows"] # list of dirs of *.yaml binding files, merged with the two above (slice 3); a key bound twice across sources is a load failure
# eda_playbook_dir = "~/.local/share/archie/eda-playbooks" # rich EDA playbook documents (trigger + CEL gated single workflow action, t2db.15); distinct from playbook_dirs
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]
# Preferred: resolve the bot token through a configured secret engine.
# token = { engine = "bws", key = "TELEGRAM_BOT_TOKEN" }
# Legacy compatibility: read the token from this environment variable.
# token_env = "TELEGRAM_BOT_TOKEN" # env var holding the bot token from @BotFather
# 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"
# 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"
# Trust X-Forwarded-Proto and X-Forwarded-Host headers when validating Origin
# on mutating requests (CSRF protection).
#
# Off by default. When false, the expected Origin scheme is derived directly
# from the daemon's own network connection (http unless TLS is terminated by
# archied directly). Setting this to true causes archied to respect the
# X-Forwarded-Proto header sent by a reverse proxy (e.g. Traefik, Caddy, Nginx).
#
# SECURITY WARNING: Enable ONLY when archied is deployed behind a trusted
# reverse proxy that strips or overwrites any client-supplied X-Forwarded-*
# headers. Enabling this on a directly exposed daemon allows untrusted
# clients to spoof the Origin scheme and bypass CSRF protection.
# trust_forwarded_headers = false
# 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 engine (MEMORY.md + USER.md under
# work_dir) is always on -- nothing here is required to get memory at all.
# engine selects among the domain/memory engine family; "builtin" (the
# default, same as leaving it unset) is the only one implemented so far.
# provider is a separate, older mechanism -- an external provider identifier
# for internal/memory.Manager.RegisterExternal -- but no external provider
# is implemented anywhere in the repo to construct and register, so
# setting it is REJECTED at config load rather than silently doing
# nothing. Leave it unset.
# [memory]
# engine = "builtin" # "builtin" is the only engine implemented so far
# session_ttl = "0s"
# Image generation capability (internal/domain/image). No provider is
# implemented yet -- this section defines the contract/config surface only
# (archie-core-1786748942147-2-47cd5bd1). Absent is valid and registers no
# provider. default names the provider /image uses without asking; leaving
# it unset means /image always asks which mechanism to use. Every provider
# is off by default -- a hosted provider spends real API credits per call,
# and a local one can saturate the host GPU, so both require an explicit
# enabled = true, never an inferred one from the presence of a key alone.
# [image.hosted.openai]
# enabled = false
# class = "openai"
# api_key_env = "OPENAI_API_KEY"
#
# [image.local.sdxl]
# enabled = false
# backend = "sdxl-turbo"
# 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
wall_clock = "30m"
gate_max_failures = 5
# NATS is the sole autonomous workflow handoff. mode changes only where the
# broker runs; every workflow still runs in a managed task container:
# "embedded" – in-process nats-server (the default; no external server)
# "external" – connect to url
# Leave the section absent to run embedded.
# [nats]
# mode = "embedded" # "embedded" | "external"
# url = "nats://localhost:4222" # required when mode = "external"
# token_env = "NATS_TOKEN" # optional external-server credential; embedded generates one per start
# 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
# Playbook-binding at-rest encryption: [bindings].encryption_key resolves a
# 32-byte high-entropy key through the secret registry (engine + key) and seals
# each binding's HMAC secret in the SQLite bindings.secret column with AES-256-
# GCM (see docs/prds/binding-secret-encryption.md). When the key is absent,
# binding secrets are stored as plaintext (the pre-t2db.7 behaviour) -- enabling
# encryption does not retroactively encrypt existing rows, which stay plaintext
# until they are edited. Rotation: after changing encryption_key, retain the
# previous material in previous_encryption_keys so rows sealed under the old
# key still decrypt, then drop it once no row references it. A reload that
# changes these keys requires a daemon restart.
# [bindings]
# encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }
# previous_encryption_keys = [ { engine = "env", key = "ARCHIE_BINDING_KEY_OLD" } ]
# Docker sandbox execution of archie-agent is mandatory for autonomous
# workflows. Omit this section to use the default image, lifetimes, and pull
# policy; the options below show the available overrides. If Docker or
# the image is unavailable, chat and the dashboard still start while tasks
# park explicitly; archied never falls back to a host agent loop.
# [containers]
# image = "ghcr.io/samcharles93/archie-agent:latest"
# max_concurrency = 4 # optional cap; 0/absent means no global cap
# 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
# # review_enabled = true # run a fresh adversarial reviewer (no path to the implementer's
# # context) after gates pass and before the PR opens. Default false --
# # an uncalibrated reviewer that cries wolf is worse than no review.
# ── 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
# 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.