Skip to content
wfnexus

Architecture

How a wfnexus run flows: an agent or a person uses wfx; wfx-server runs steps on providers and asks a classifier; a human gate approves; the change lands in git.

The loop above is an SVG, 12 seconds long. There is also a full-screen animated version, made with the diagram-motion skill’s motion canvas, and a video fallback:

The path of a run

Section titled “The path of a run”

The one-page version, with the same diagram as text and a “where to change X” table, is ARCHITECTURE.md in the repo.

  1. A person or agent starts a run: UI, wfx (CLI or agent skills), cron, channel, hook or MCP call.
  2. wfx calls wfx-server over REST and SSE (internal/api); the concurrency group is checked.
  3. The engine (internal/engine) runs one toolnexus agent per step, ordered by internal/planner, on a provider from internal/catalog, here or on a worker.
  4. The classifier (internal/judge) answers decide: and judge: questions.
  5. A human gate pauses the run until someone runs wfx approve, wfx reject or wfx answer; internal/notify tells them.
  6. State lives in internal/store; the result lands in git as a PR, a proposal (internal/proposal) or a bundle (internal/bundle).

The binaries

Section titled “The binaries”
Binary Built from Role
wfx-server apps/api The engine, the API and the embedded UI (apps/ui). WFX_MODE=local uses SQLite and a folder; server uses Postgres and S3.
wfx apps/api/cmd/wfx The CLI. See the reference.
wfx-runner apps/api/cmd/wfx-runner An outbound-only worker.

Server and runner images start through carry, which can bring a machine’s tools and config from a bucket before the process starts. Only agent CLIs are baked in.

Boot

Section titled “Boot”

At boot the server loads the config (environment over config.yaml), then every workflow source. A workflow that does not load is skipped by name and logged as NOT LOADED, never a reason to exit: the rest still load and schedule. It then prints what is wired (default provider, keys by name and set or unset, classifiers, skills), marks runs cut off by the last shutdown as interrupted, and serves. A loopback bind runs with no authentication; a wider bind with no users refuses to serve until the install is claimed. The self-host page walks through a one-box install.

Packages

Section titled “Packages”
Package Purpose
internal/api The REST and SSE surface the UI and the CLI use.
internal/engine Executes runs: steps, gates, decide, state, redaction, schedules, workers.
internal/workflow Loads the YAML and renders prompts.
internal/planner Derives execution order from consumes / produces.
internal/catalog Providers, classifiers and MCP servers: everything a step can name.
agentadapter/ Makes an ACP agent CLI usable as a model.
internal/judge Typed questions to classifier calls, and the verdict bands.
internal/proposal A workflow change becomes a git change.
internal/secrets AES-GCM seal and open for the env store.
internal/skills The SKILL.md registry.
internal/bundle The published unit: a workflow plus its skills and MCP servers.
internal/notify Delivers a pause to a person.
internal/store Persistence (SQLite or Postgres).