Archer is an open-source framework for drawing, checking and changing infrastructure as a live flow diagram.
You describe your system (entry points, relays, tunnels, pools, exits, policies) in a plain YAML document. Archer shows it as a canvas you can read at a glance, keeps it live with data from your own sources, and lets you edit the flow, press Apply, review exactly what will change, and deploy it. Scripts and agents get the same abilities through a CLI and an MCP server.
Status: early development. The headless loop works today: the v2 document model, flow resolution per audience, pools, policies, impact analysis, drift, change sets with approvals, deploys with automatic rollback, git history and a hash-chained audit log, through the
archerCLI and an MCP server. The live panel is next; see Roadmap.
In real infrastructure, the name a user sees is rarely one box. It is a path through several systems, it can differ for different audiences, and it changes as pools fail over or run out of quota. Every layer on that path accepts traffic and passes it on, so a break in the middle can look healthy from above.
Archer makes those paths first-class:
- Flows: a named path, resolved separately for each audience, hop by hop.
- Pools: backends with health and quota rules, a selection strategy and ordered fallbacks.
- Policies: rules such as "this address is never exposed to that audience" or "fail closed", checked on every change and against live state.
- Impact: before anything deploys, which flows and audiences a change reroutes.
- Drift: where the running system differs from what the document declares.
- Deterministic apply path. Edit → change set → validate → policies → impact → plan → review → deploy → verify. Every step is code you can read, test and audit.
- Everything domain-specific is a plugin pack. Node kinds, edge kinds, live-data sources, deploy providers, policies, layouts and themes. Archer works for networks, cloud, Kubernetes, data pipelines or anything else you can model as a graph.
- Declared and discovered. Sources discover what is running; parts you mark as managed are converged to the document; differences show as drift.
- Unknown is never green. Missing or stale live data is shown as unknown, not as healthy.
- Private by default. Self-hosted, loopback-only until you add authentication, secrets by reference only, no telemetry, no external requests.
Requires Node.js 22.13 or newer and git.
npm ci && npm run build
alias archer="node $PWD/packages/cli/bin/archer.js"
archer init --example relay-multi-audience demo && cd demo
archer flows explain # one name, two audiences, two paths, with reasons
archer findings # every rule holds
archer drift # the simulated system is empty: everything is missing
# People and agents authenticate with tokens; roles decide what they may do.
archer user add alice --role approver && archer user add bob --role deployer
archer user add capacity-bot --role editor --type agent
export AGENT=$(archer token create capacity-bot --name mcp)
archer change propose --token "$AGENT" --title "Open 8443 on the forwarder" --patch '[{"op":"add","path":"/nodes/fwd-xc/props/listen/-","value":"tcp/8443"}]'
archer change approve <id> --token "$(archer token create alice --name cli)"
archer deploy <id> --token "$(archer token create bob --name cli)"
archer history && archer audit verifyarcher mcp serves the same operations to agents over the Model Context Protocol; an agent's
token only sees the tools its role allows.
node packages/cli/bin/archer.js examples
node packages/cli/bin/archer.js init --example multi-hop-relay -o relay.json
node packages/cli/bin/archer.js validate relay.json
node packages/cli/bin/archer.js export html relay.json -o relay.htmlThe HTML export is a single offline file. Pan and zoom, click a card (or focus it and press Enter) to trace everything upstream and downstream of it, and save the diagram as SVG or PNG. Each export carries a Content Security Policy that blocks all network access and allows only its own viewer script, and every card renders at exactly the height the layout computed.
The v1 specification is described by its JSON Schema in
packages/model/schema/v1.schema.json. Every command
accepts --json for scripts and agents; exit codes are 0 ok, 1 invalid input, 2 usage error,
5 runtime error.
| Path | What it is |
|---|---|
packages/graph |
Graph algorithms: cycles, stages and lanes, edge classes, path tracing |
packages/layout |
Deterministic layered layout and edge routing |
packages/model |
The v2 document (id-keyed YAML), JSON Patch editing that keeps comments, v1 migration |
packages/sdk |
The plugin contract: kinds, policies, strategies, sources, providers |
packages/core |
Pure engines: validation, flow and pool resolution, policies, impact, drift |
packages/engine |
Runtime: workspaces in git, pack host, live state, change sets, deploys, audit |
packages/mcp |
MCP server generated from the engine's operation registry |
packs/pack-core, packs/pack-network, packs/pack-demo |
Official packs |
packages/export-html |
Static single-file HTML export and its viewer runtime |
packages/cli |
The archer command line, with bundled examples |
docs/diagnostics.md |
Every diagnostic and finding code |
docs/adr |
Architecture decision records |
e2e |
Browser tests (Playwright) |
npm ci
npm run check # Biome lint, TypeScript build, unit tests, public-safety lint
npm run e2e # browser tests; PW_CHANNEL=chrome uses an installed Chrome| Milestone | What it delivers |
|---|---|
| M0 Foundation | TypeScript monorepo, the v1 engine ported with identical geometry, hardened export, CI and public-safety checks |
| M1 Headless loop | v2 document model, flows, pools, policies, impact, drift, change sets, deploy executor with rollback, CLI and MCP |
| M2 Panel | The live canvas: flow tracing per audience, inspector, review sheet, deploy progress, history |
| M3 Live truth | Discovery, drift and converge, hop-by-hop verification probes, what-if simulation |
| M5 Hardening | OIDC, secret resolvers, locks, container image, threat model |
| M6 Ecosystem | Stable plugin SDK, pack scaffolding, more examples, embeddable components, docs site |
See CONTRIBUTING.md. Examples, tests and docs use documentation address ranges
and example.* names only; npm run lint:public checks this. Security issues: see
SECURITY.md.