culture-nodes

Culture Nodes is a durable, ledger-native workflow orchestrator for agents, code, services, and people. Workflows are immutable graphs; agents are triggered on their own machines through a provider-neutral protocol; code runs through an external runner boundary; and every result lands in an append-only work ledger where an agent's "done" is a claim, not a fact.

Every node has a contract. Every result has evidence.

See it running

A run is a live graph: solid edges have been walked, dashed edges are still possibilities — and the loops from test.failed and verify.changes_required back to build are domain outcomes on the graph, never engine failures.

Dark mode follows your OS, with the same design tokens the agentculture.org site ships — nothing here invents a sibling aesthetic.

Click any node (or press Enter on it — the whole canvas is keyboard-operable) to see what it really is: its pinned contract digest, its owner, every attempt, and the ledger records it appended.

The work ledger is the run's truth: every record carries its authority — proposed renders dashed, confirmed/observed/derived render solid — so an unverified completion claim looks unverified.

Everything the UI shows comes from the same /v1alpha1 API the CLI uses, so anything you can see here you can script there.

A runs board (cards on state columns) and a jobs timeline (cross-run node-run history with a time-range filter) are landing later this cycle — screenshots go here once they ship.

Quickstart

The complete local system in one command (API + scheduler + worker + PostgreSQL + MinIO, UI embedded):

cd deploy/compose
cp .env.example .env       # dev-only defaults; required — no password ships in the compose file
docker compose up --build  # UI + API on http://localhost:8080

Publish the reference workflow and start a run from the Python CLI front:

export NODES_API_URL=http://localhost:8080
uv run nodes workflow publish examples/delivery-loop/workflow.yaml
uv run nodes run create --workflow <digest> --input examples/delivery-loop/input.json
uv run nodes run events <id>   # follow the live event stream

That's the whole product path — no AgentCulture-mesh dependency anywhere in it. nodes (the Python CLI) has zero third-party dependencies and is a pure REST client; the compose stack above is Postgres, MinIO, and the Go control plane. Agent and code nodes execute through two open, provider-neutral contracts, and you are not limited to the reference implementations this repo ships:

• Actor protocol (api/actor-protocol) — how an agent node's attempt reaches an external process and how that process reports back. Three conformant reference bridges exist — adapters/colleague, adapters/claude-code, adapters/codex — but anything that passes the runnable conformance kit (tests/conformance) is just as valid a fourth, in any language, over any agent backend.
• Runner protocol (api/runner-protocol) — how a code node's operation reaches a runner service. cmd/nodes-runner is the reference implementation (headspace-cli behind the contract); anything that passes tests/runnerconformance is just as valid a replacement.

Registering an actor or a runner is a row in a table today (no HTTP registration endpoint yet — PRD §26 open question); see deploy/compose/README.md for the worked local example.

For Kubernetes, the Helm chart deploys the same system with a migration Job, probes, and worker replicas: 2 by default (multi-pod safety — leases and fencing — is built in):

helm install nodes deploy/helm/culture-nodes

Phase 1 runs authless behind a private network — deploy only on a private cluster/VPC. See the chart's NOTES and docs/guide.md for the full tour, including dev mode and the external-agent story.

What's in the box

• Go control plane (cmd/nodes, one binary): compiler + nodes validate, a durable engine (fenced claiming, bounded loops, restart survival), the work ledger (agents propose; humans confirm; runners observe; validators derive), an approval surface for human-in-the-loop nodes (below), transactional outbox, Postgres/SQS queue drivers, scheduler, worker.
• Actor protocol (api/actor-protocol) for external agents — provider-neutral HTTP/JSON, a runnable conformance kit (tests/conformance), and three reference bridges: adapters/colleague, adapters/claude-code, adapters/codex.
• Runner protocol (api/runner-protocol) for code nodes: placement-unaware (the same workflow digest runs against a runner anywhere by changing one registry entry), polling-authoritative, callbacks optional. cmd/nodes-runner is the reference runner service (headspace-cli behind the contract, mandatory bearer auth); the AWS Lambda adapter (internal/runners/lambda, registry-pinned, IAM-scoped, honest evidence) is the cloud-native alternative. No Docker socket, and no execution of any code, ever enters a control-plane container.
• Web front (web/): the read-only Runs list, Run view, and Ledger view above, embedded into the Go binary. A runs board and a cross-run jobs timeline are landing later this cycle.
• Python CLI front (nodes on PyPI): thin, zero-dependency client of the same API.

The full design lives in docs/initial-design/culture-nodes-prd-spec.md; what was built, with evidence, in docs/acceptance.md and docs/deliveries/.

Approvals: a human in the loop

An approval node pauses a run without ever creating a work item: the engine writes one human_tasks row (decision schema, approver role/group, deadline, context/artifact refs, allowed outcomes — PRD §9.9) inside the same transaction that creates the node run, and the run holds no worker lease and no open database transaction while it waits (internal/engine/humantask.go, internal/worker/doc.go). A human answers through the API, never through the worker:

curl http://localhost:8080/v1alpha1/human-tasks              # pending + decided, this namespace
curl http://localhost:8080/v1alpha1/human-tasks/<id>          # one task's context

curl -X POST http://localhost:8080/v1alpha1/human-tasks/<id>/decision \
  -H "Authorization: Bearer $NODES_HUMAN_DECISION_TOKEN_SECRET" \
  -H 'content-type: application/json' \
  -d '{"outcome": "approved", "decider_actor_id": "ori", "expected_ledger_version": 4}'

The decision endpoint is the one write in this API that requires a bearer token (NODES_HUMAN_DECISION_TOKEN_SECRET on nodes serve) — every other Phase-1 endpoint is authless behind the private network above, but a decision here writes a human-authority review into the ledger and resumes the run on whoever's behalf the token vouches for. The commit is atomic and stale-guarded: a decision against a ledger version the run has since moved past is refused, never silently applied. The shipped examples/delivery-loop reference workflow does not include an approval node yet (see its header comment); the engine, API, and worker plumbing above are real and tested independently of that fixture.

Example topology: one machine, or a small production split

The runner protocol's placement-unaware model above is what makes this possible with zero workflow changes: local dev runs everything — Postgres, API, scheduler, worker, and a runner — on one machine. A small production split looks like the shared control plane and its Postgres on one machine, and a second machine running just a worker (and its own runner service) pointed at the first machine's database; nothing about the workflow definition or its compiled contract differs, only registry/deployment config does (the runner-protocol doc's own worked example uses exactly this shape — an endpoint named runner.thor.internal).

This repo's own development follows that shape as a concrete example — spark for local dev, a thor + orin pair sharing one Postgres on thor for production — but the machine names are illustrative, not a product requirement: any names, any machine count, any cloud or bare metal work the same way. Per-machine compose profiles for that split are landing later this cycle.

CLI

The Python front's product verbs (workflow, run, ledger, review) are thin API clients; the identity verbs below work offline:

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved. The Go binary carries the same contract for its serve / scheduler / worker / all / migrate / validate modes.

Mesh identity

Separately from the product path above (which has no mesh dependency), this repository is also a Culture mesh agent — it develops itself using the same AgentCulture tooling its maintainers use elsewhere: culture.yaml (suffix: culture-nodes, backend: colleague) with the resident prompt file AGENTS.colleague.md, and the vendored guildmaster/devague skill kit under .claude/skills/ (cite-don't-import — see docs/skill-sources.md). Running Culture Nodes yourself needs none of this.

Contributing

See CLAUDE.md for the working conventions: the design ground rules distilled from the PRD, the version-bump-every-PR rule, the cicd PR lane, and the vendored-skills policy.

License

Apache 2.0 — see LICENSE.