docs(config): cut the setup template to the settings that start the services

This commit is contained in:
sam committed 2026-10-24 22:26:33 +11:00
1 parent 7abc816735
commit e818f7f15b
1 file changed
+38 -464
+38 -464
View File
@@ -1,500 +1,74 @@
# archie configuration
#
# archied configuration
# This file starts the services. Everything else (forge connections, models,
# providers, chat, tools, containers, repositories, policies) is edited in the
# dashboard, and a saved value there overrides the same setting here.
#
# 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.
# Every other engine (bws, sops, vault, age) is an extension installed from
# the archipelago marketplace and enabled through the control plane.
# Secrets are never written here: each is a {engine, key} reference. The
# built-in "env" engine reads key as an environment variable.
# work_dir = "~/.local/share/archie/work" # default
# state_dir = "~/.local/share/archie" # default; embedded NATS store, task logs, disk probe
# The PostgreSQL connection archie-state-store, archied and archie-gateway
# serve from. Required: each fails closed without it.
# `docker compose up -d postgres` starts a matching local postgres:18 with this
# default URL.
# database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
# skills_dir = "~/.local/share/archie/skills" # SKILL.md search path; defaults under work_dir when unset
# database_url = "postgres://archie:archie@localhost:5432/archie?sslmode=disable"
# work_dir = "~/.local/share/archie/work"
# state_dir = "~/.local/share/archie"
poll_interval = "60s"
label = "archie"
bot_user = "vectis-labs-archie"
# org = "acme" # empty means the default org (a single-operator install's one identity)
# granted_credentials = ["openai"] # credential@1 services the root identity may resolve (see [containers.credentials])
# 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]
# The name of an installed, enabled forge package (archipelago: forge/github, forge/gitea), or "none".
# Install and enable it from the Extensions page, then restart archied.
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.
# Webhook intake is single-identity, and that is enforced: with [[identities]]
# configured this combination is REJECTED at startup rather than silently
# downgraded to polling. The receiver binds one secret and one dispatch
# predicate, so it could only judge another identity's events by the wrong
# rules. Either drop the [[identities]] blocks, or keep intake = "poll" and
# let each identity poll.
# intake = "poll" # "poll", "webhook" or "both"
# 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 repository membership. Forge access comes from organisation
# connections, edited through the control plane. [forge].intake =
# "webhook"/"both" is rejected alongside [[identities]]. Minimal shape:
# [[identities]]
# name = "personal" # required; namespaces logs/events/NATS subjects
# bot_user = "your-bot" # required
# org = "acme" # empty inherits the shared org (empty = default)
# granted_credentials = ["openai"] # credential@1 services this identity may resolve (see [containers.credentials])
[dispatch]
# Can be of "assignee", "label", or "either"
# this sets the method archie uses to pick up tasks.
trigger = "assignee"
trigger = "assignee" # "assignee", "label" or "either"
ack_reaction = "eyes" # "off" for none
# Optionally set a reaction to show that archie has picked up a task.
# setting this to "off" disables the pickup reactions.
ack_reaction = "eyes"
[models] # role -> ai-sdk runtime ref (used by agent workflows)
[models]
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"
# `transcription` is optional: it turns Telegram voice notes into text before
# the turn is dispatched, behind a "[voice transcription]" marker. Read by
# archie-messaging. Unset, or a provider that does not resolve, leaves the
# voice note as its media placeholder -- the turn still runs.
# transcription = "openai/whisper-1"
# [providers.openai]
# class = "openai"
# api_key = { engine = "env", key = "OPENAI_API_KEY" }
[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",
# ]
# [chat.telegram]
# The bot token from @BotFather, resolved through a configured secret engine.
# token = { engine = "bws", key = "TELEGRAM_BOT_TOKEN" }
# Email and the generic inbound webhook are archipelago channel extensions
# (channels/email, channels/webhook): install, accept and enable them from the
# Extensions page, with their settings there.
# 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 -- a source, not a person, so it reaches the
# limiter as a transport-only budget key rather than as an identity. Off by
# default -- both fields must be set to a positive value.
#
# This section is the seed for the Channel settings resource. The Web UI owns
# the value a running deployment limits with (restart-required), so edit it
# there rather than here; a stored value is not overwritten by this file.
# [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.
# Most MCP servers are single-threaded and get one tools/call at a time.
# parallel_tool_calls = true (default false) drops that serialization for
# this server only, for a server whose own implementation handles
# concurrent requests. It never affects another configured server.
# [[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"
# parallel_tool_calls = false
# 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"
# Bounds one readiness probe's call into a service the daemon depends on but
# does not own (the Gateway), so a hung dependency degrades that probe instead
# of stalling the whole report. Omit for the default; a negative value leaves
# only the caller's own deadline in force.
# dependency_timeout = "5s"
# 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.
#
# 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 <same config.toml>` 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 (internal/domain/memory +
# internal/infrastructure/memory) 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.
# [memory]
# engine = "builtin" # "builtin" is the only engine implemented so far
# Operator alerts (parked tasks, failed runs, unhealthy services, missing
# credentials) are listed in the dashboard. Archie also POSTs each raised and
# resolved alert as JSON to the webhook: wire it to n8n, email, Slack, or any
# HTTP endpoint. Failed deliveries are retried and recorded on the alert.
[notify]
# webhook = "https://n8n.example.com/webhook/archie"
# min_severity = "warning" # info, warning or action: the lowest severity delivered
# secret = {engine = "env", key = "ARCHIE_NOTIFY_SECRET"} # signs X-Archie-Signature (HMAC-SHA256)
[budgets]
max_steps = 60
wall_clock = "30m" # one agent call
wall_clock = "30m" # one agent call
gate_max_failures = 5
task_wall_clock = "4h" # a whole task run; keep containers.max_uptime at or above it
task_wall_clock = "4h" # a whole task run
[health]
listen = "127.0.0.1:8485"
# dependency_timeout = "5s"
[web]
listen = "127.0.0.1:8484" # "off" disables the dashboard
# trust_forwarded_headers = false # only behind a proxy you control
[services.gateway]
target = "127.0.0.1:8585"
# listen = "127.0.0.1:8585"
[services.state]
target = "127.0.0.1:9090"
# listen = "127.0.0.1:9090"
# TLS: every gRPC hop between services uses certificates from your own CA
# (step-ca, cert-manager, Vault, openssl). Each process loads
# cert_dir/<service>.pem and cert_dir/<service>-key.pem, whose DNS SAN is its
# service name: archied, archie-gateway, archie-messaging, archie-state-store,
# archie-ui. Every peer must chain to ca_file. Certificates are reloaded when
# they change. Without [tls], services may only listen on and dial loopback
# addresses, task containers cannot reach the State Store, and the harness
# setup terminal is off.
# [tls]
# ca_file = "/etc/archie/tls/ca.pem"
# cert_dir = "/etc/archie/tls"
# Services selects contract adapters at composition time.
[services.gateway]
target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remote once set)
# listen = "127.0.0.1:8585" # The address archie-gateway BINDS. Read only by the
# # archie-gateway process; every client ignores it. Defaults
# # to the target above, so a default deployment's client and
# # server cannot drift onto different ports. Set it when the
# # host already owns that port.
[services.state]
target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address archied and
# # archie-gateway dial. They own no task data
# # in-process: the standalone archie-state-store process
# # owns it in PostgreSQL. An empty target is a startup error.
# listen = "127.0.0.1:9090" # The address archie-state-store BINDS. Read only by that
# # process; every client ignores it. Defaults to the target
# # above, so a default deployment's client and server cannot
# # drift onto different ports. Move it when a port is already
# # taken on the host.
# The dashboard checks repository access through the daemon's gRPC contract.
# Plaintext is allowed on loopback only; remote deployments require [tls].
# [services.daemon]
# target = "127.0.0.1:8587"
# listen = "127.0.0.1:8587"
# The daemon listener also serves the setup terminal and the Sandbox tab, which
# require [tls] and a container launcher.
# 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
# mode = "embedded" # or "external" with url
# url = "nats://localhost:4222"
# token_env = "NATS_TOKEN"
# 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.
# Stored in the same PostgreSQL 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. All fields default when the section is absent;
# capture is on by default.
#
# 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
# [log]
# file = "~/.local/share/archie/logs/archied.log"
# level = "info"
# 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 bindings.secret column with AES-256-
# GCM. 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"
#
# A private registry needs a credential the daemon sends on pull (an
# anonymous pull always answers 401 there, whatever the policy). The value is
# a Docker registry.AuthConfig JSON document -- {"username":"bot","password":"..."}
# ("identitytoken"/"registrytoken" are alternatives; "serveraddress" is
# optional and defaults to the image's registry). Unset means anonymous pulls,
# exactly as before this key existed; a reference that cannot be resolved
# warns and pulls anonymously rather than failing the daemon.
# registry_auth = { engine = "env", key = "ARCHIE_REGISTRY_AUTH" }
#
# Agent profiles a workflow selects with `profile: <name>`. A workflow that
# names none runs under [containers].image with every tool.
# Once the State Store holds container policies, edit profiles in the
# dashboard (Settings, Advanced); a stored set replaces the file's.
# [containers.profiles.network-investigator]
# image = "archie-agent-net:local" # docker compose build agent-net; empty uses [containers].image
# tools = [] # allowlist over MCP, script and plugin tools; empty allows all
# A Kit profile runs every agent stage on an external CLI packaged as a Kit v3
# image: one workload Kit or published Kit set (which merges a workload with
# its mixins), pinned by digest.
# [containers.profiles.claude]
# kit = "docker/claude-code-kit@sha256:<digest>"
# adapter = "claude-code" # claude-code, codex, pi, omp or copilot; empty runs without capture tools or usage
#
# Credential bindings map a Kit's credential@1 service name to a secret. A
# binding alone grants nothing -- an identity resolves it only when its own
# org matches and the service is in its granted_credentials
# ([[identities]] above). Once the State Store holds it, edit bindings in the
# dashboard (Settings, Advanced); a stored set replaces the file's.
# [[containers.credentials]]
# service = "openai"
# org = "acme" # empty means the default org
# secret = {engine = "env", key = "OPENAI_API_KEY"}
# 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"
# # Install what the gate needs and the image does not ship; repo.tooling runs
# # these in the worktree, in order, before any gate step:
# # tooling = [["go", "install", "google.golang.org/protobuf/cmd/protoc-gen-go@latest"]]
# 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
# 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.
# encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }