Skip to content
A personal experiment · alpha · code not public yet · no offer, no support Project status →

Architecture

ComponentLanguageRuns onRole
vaicoa-coreGo, one binarya server you runidentities, signed roster, own CA, signed catalog, policy, approvals, queue, audit, secrets
vaicoa-nodeGoevery host it managesenrols with attestation, pulls ops over mTLS, verifies them itself, runs them (Podman, host, k3s, Kubernetes, Cluster API), reports
vcxGoan operator’s machinepairing, proposing, approving, roster and catalog signing, audit export, tunnels
vaicoa-runGoinside an agent sessionthe agent’s only way to the core: a CLI and a local MCP server over stdio
Approval appsSwift, KotliniPhone, Android, Macpair by QR code, list approvals, render the display locally, sign with a hardware key
ModulesPythonnext to the core, out of processpodman_env, k3s_cluster, capi: state, preconditions, plans
DriversPythonnext to the core, out of processhetzner_cloud, forgejo_git, forgejo_actions, agent_sandbox, alertmanager, observability, mcp_bridge, llm_local
vaicoa-pushGonext to the corewake-up pushes (APNs, FCM, UnifiedPush) without content

Modules and drivers talk to the core over JSON-RPC on stdin/stdout. The core never imports a driver.

Inside, and meant to be reviewed: the Go code of the core, the node and vcx, and the contracts (JSON Schemas under contract/). Outside: every Python module and driver, the language model, the provider APIs, Podman itself.

  • Modules and drivers propose and check; the core enforces. A module’s preconditions can only make the core stricter: a failed precondition denies, a passed one never skips a constraint or the policy.
  • Drivers get one credential per call, never a stored token.
  • What runs is what was approved: the node reads the action and parameters from the signed op, recomputes their digest and checks the approvals against the roster it pinned itself.
  • A language model’s output is data. Its proposals are filtered by the run’s allowed actions, validated against the catalog and decided by policy like a human’s. Signals, webhook bodies and claims are untrusted input.
KindProofLevels
Human (a user with one or more devices)a device key: file, PKCS#11, Secure Enclave, Android Keystore, YubiKeyfile < device < presence
Nodenode key plus attestation (join token, Hetzner Cloud lookup)token < provider < hardware
Agent runa run key the core mints per run, acting on behalf of a userdelegated: never above its user, capped at device

Quorums count distinct users, never devices. Roles (owner, operator, developer, viewer, and your own) can be scoped to environments. The assurance profile decides what a device’s claimed level counts for.

  1. A proposal arrives, from a human (vcx propose), an agent run (vaicoa-run), or a trigger.
  2. The core looks the action up in the signed catalog and validates the parameters against its JSON Schema.
  3. The action’s module turns the environment’s state into state, checks preconditions and computes a plan.
  4. CEL constraints and Cedar policy decide: refuse, run, or ask for approval and from whom.
  5. If approval is needed, the approval object (payload, display, plan, evidence) goes to the approvers’ devices. They render it themselves and sign its digest.
  6. The op goes into the queue with an idempotency key. The node leases it at its next sync.
  7. The node verifies the op against its own pinned catalog and roster and the plan, runs it and reports steps and result.
  8. Every step lands in the hash-chained audit, with the catalog and policy versions it ran under.

Ops for third-party APIs (Hetzner Cloud, Forgejo, Alertmanager, observability back ends, MCP servers) do not go to a node: a driver runs them at the core, and the core is their checkpoint.

Every connection between two Vaicoa components uses TLS 1.3 with the crypto profile. The core has a door listener (pairing, enrolment, webhooks, without client certificates) and an mTLS API listener. Between hosts, IPsec (strongSwan, IKEv2) replaces WireGuard; admin access to a node service goes through a TLS tunnel that opens only with a valid access grant.