archi.yaml and ops.yaml
archi init writes archi.yaml into the instance. archi up, down,
doctor, ingest and ops read it. It holds settings, never secrets: those are in
.env.
archi.yaml
| Key | Meaning |
|---|---|
instance_version |
The file format. Always 1. |
name |
The instance and deployment name. A lowercase slug. |
bundles |
The bundles selected at init, in order. |
with_packs, without_packs |
Packs added to or removed from the bundles' defaults. |
profile |
The name of the rendered okg profile under profiles/. |
okg_version |
The OKG version the instance was made with. |
data_root |
Absolute path of the data root: connector caches and repository checkouts. Outside the instance. |
runtime |
docker or podman. |
ports |
Host ports, all bound to 127.0.0.1: graph_db, mcp, webui. |
admin_email |
The Open WebUI admin account. |
mcp_servers |
External MCP servers archi connect registers next to the instance's own. See below. |
automations |
Per automation, level: L0, L1 or L2. See below. |
mcp_servers
mcp_servers:
- name: notes # lowercase letters, digits, - _
url: https://notes.example.org/mcp
headers:
Authorization: NOTES_AUTH # header name -> NAME of an environment variable
The variable holds the whole header value, for example Bearer abc. The file
is committed, so it never holds a secret. archi connect stops with the reason
for a value that is not a variable name, a URL with credentials or a query
string, an unknown key, a duplicate name, or the instance's own server name.
See Connecting an agent.
Automation levels
automations:
instance-health:
level: L1
A name under automations must be an automation pack the instance selected.
level can be L0, L1 or L2. Any other value, including L3, is
refused when the file loads. The effective level is the lowest of this
value, the bundle's bound and the pack's maximum.
ops.yaml
Per automation, under automations.<name>:
| Key | Meaning |
|---|---|
mode |
shadow (default) or live. live counts only after an approved promotion. |
timeout_seconds |
How long an L2 escalation waits for a person. Default 4 hours. |
estimate_cost |
Cost checked against the budget before each proposal. Default: the pack's cost_per_run. |
promotion |
The change archi ops promote opened. Do not edit by hand. |
proposer, outcome |
How proposals and outcomes are produced. See Running automations. |
Other files
| File | What it holds |
|---|---|
.env |
Generated secrets and your source credentials, readable only by you, ignored by git. |
archi.lock |
Bundle and pack versions and content digests. Committed. |
compose.yaml |
The stack. Generated. Edit archi.yaml, not this file. |
profiles/<name>/ |
The rendered okg profile. |
The keys of pack.yaml and bundle.yaml are in the
pack and bundle format.