# # 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" # `reviewer` runs the adversarial self-review stage and operator-triggered PR # reviews. Omitted, it falls back to `builder`. # reviewer = "openai/gpt-5.4" # `embedding` is optional: it powers in-process embedding consumers # (curators first). Unset, or a credential that fails to resolve, degrades # to the capability reporting unavailable -- archied still starts. # embedding = "openai/text-embedding-3-small" [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. 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] # # [chat.webhook] configures the single route the gateway serves. Every # field is optional; an absent section runs with the pre-existing # behaviour: path "/webhook", no signature validation, raw body as message # text, no reply. # [chat.webhook] # path = "/webhook" # secret = { engine = "bws", key = "CHAT_WEBHOOK_SECRET" } # verifies # # X-Hub-Signature-256 on inbound payloads. Empty (the default) accepts # # any unsigned POST -- set this to make the gateway actually verify # # what it claims to. # template = "issue.title" # dot-notation extraction of the message text # # from the JSON payload. Empty uses the raw body. # deliver_to = "origin" # "origin" writes the reply as the HTTP # # response; empty (the default) sends no reply. # Per-(channel, sender) inbound rate limiting, shared by every chat channel: # Telegram keys by numeric user ID, email by SMTP from address, webhook by # its configured route path. Off by default -- both fields must be set to a # positive value. # [chat.rate_limit] # window = "1m" # max_requests = 20 # 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: /indexes). # index_dir = "/var/lib/archie/indexes" # Per-index lifecycle metadata DB (default: /workspace-indexes.db). # db_path = "/var/lib/archie/workspace-indexes.db" # archied's own liveness surface, always on. GET /healthz and /health answer # 200 once the daemon is serving (503 while it is still booting), and # /health/detailed reports the readiness probes. This is what the update # watchdog polls after restarting archied to decide whether the release came # up or has to be rolled back, so it stays separate from the dashboard's # /healthz: the dashboard can be switched off, and it runs as its own process # in the extracted UI topology. [health] listen = "127.0.0.1:8485" # Web dashboard and API: task board, activity stream, chat, config, # 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. # # From the UI cutover (archie-core-8cda.5.4) the dashboard is served by the # standalone archie-ui process, not by archied: this listen address is what # archie-ui binds, and archied runs no dashboard listener at all. Run # `archie-ui -config ` alongside the other services. [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 # Services selects contract adapters at composition time (see # docs/prds/state-store-contract.md). [services.gateway] target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remote once set) # target_token = "..." # Bearer [REDACTED] for a NON-loopback listener. A loopback listener # # (127.0.0.1/::1/localhost) needs no token. A non-loopback # # listener without a token fails closed, as does a # # non-loopback dial without one. The same token is # # presented as GATEWAY_TOKEN by remote consumers. [services.state] target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address archied and # # archie-gateway dial. They no longer own archie.db # # in-process: the standalone archie-state-store process # # owns the single SQLite file (docs/prds/state-store-contract.md # # §10/§12 step 7). An empty target is a startup error. # target_token = "..." # bearer token for a NON-loopback target. A loopback target # # (127.0.0.1/::1/localhost) needs no token. A non-loopback # # target without a token fails closed (docs/prds/state-store-contract.md # # §9). The same token is injected as STATE_STORE_TOKEN into # # archie-agent containers so the agent authenticates to the # # same remote store. See deployments/README.md for how to # # start archie-state-store. # 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. # # From the UI cutover (archie-core-8cda.5.4) the receiver is mounted by the # archie-ui process, which projects these same values from this file; the # daemon's binding-dispatch loop consumes captures from the shared State # Store. Leave this section here even if you do not edit it: both processes # read it. # [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 # The cron/scheduling ticker engine: how often scheduled jobs are checked, # how many may run at once, and how long one may run. The engine polls a job # store for what is due and dispatches each due job to the delivery it names # -- so nothing here schedules anything by itself, it only tunes the timing. # Absent is valid: every field defaults independently, and a section naming # only one of them still gets the defaults for the other two. # # Zero (or absent) takes the default named below. A NEGATIVE value is a # startup error, not a clamp: running something other than what was written # is how a misconfiguration stays invisible. Zero cannot mean "off" here for # the same reason it cannot in [tools.tool_policy] -- it is indistinguishable # from an unset key. # [scheduling] # interval = "60s" # tick cadence: how often due jobs are checked. # # Absent/zero means 1m. The finest granularity a # # cron-style schedule needs, and polling a local # # job store that often costs nothing. # max_parallel = 4 # caps simultaneous parallel-pool runs, so a store # # reporting many jobs due at once (the first tick # # after long downtime, typically) cannot launch an # # unbounded fan-out. Absent/zero means 4. It does # # not bound the sequential pool, which is one by # # definition. # job_timeout = "1h" # bounds one run. Absent/zero means 1h. A job that # # has not finished in an hour is stuck, and leaving # # it in flight would suppress every later run of the # # same job forever. # events_sink = "none" # "bus" publishes each run and failure on the event # # stream, which is what the dashboard timeline reads; # # "none" (the default, same as leaving it unset) # # leaves the engine unobservable -- a scheduled run # # has no task or chat turn behind it, so with no # # sink nothing anywhere records that it fired. # # Any other value is a startup error, so a typo # # cannot silently turn observability off. # 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.