Architecture
Components
Section titled “Components”| Component | Language | Runs on | Role |
|---|---|---|---|
vaicoa-core | Go, one binary | a server you run | identities, signed roster, own CA, signed catalog, policy, approvals, queue, audit, secrets |
vaicoa-node | Go | every host it manages | enrols with attestation, pulls ops over mTLS, verifies them itself, runs them (Podman, host, k3s, Kubernetes, Cluster API), reports |
vcx | Go | an operator’s machine | pairing, proposing, approving, roster and catalog signing, audit export, tunnels |
vaicoa-run | Go | inside an agent session | the agent’s only way to the core: a CLI and a local MCP server over stdio |
| Approval apps | Swift, Kotlin | iPhone, Android, Mac | pair by QR code, list approvals, render the display locally, sign with a hardware key |
| Modules | Python | next to the core, out of process | podman_env, k3s_cluster, capi: state, preconditions, plans |
| Drivers | Python | next to the core, out of process | hetzner_cloud, forgejo_git, forgejo_actions, agent_sandbox, alertmanager, observability, mcp_bridge, llm_local |
vaicoa-push | Go | next to the core | wake-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.
The trust boundary
Section titled “The trust boundary”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.
Principals and levels
Section titled “Principals and levels”| Kind | Proof | Levels |
|---|---|---|
| Human (a user with one or more devices) | a device key: file, PKCS#11, Secure Enclave, Android Keystore, YubiKey | file < device < presence |
| Node | node key plus attestation (join token, Hetzner Cloud lookup) | token < provider < hardware |
| Agent run | a run key the core mints per run, acting on behalf of a user | delegated: 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.
One op, end to end
Section titled “One op, end to end”- A proposal arrives, from a human (
vcx propose), an agent run (vaicoa-run), or a trigger. - The core looks the action up in the signed catalog and validates the parameters against its JSON Schema.
- The action’s module turns the environment’s state into
state, checks preconditions and computes a plan. - CEL constraints and Cedar policy decide: refuse, run, or ask for approval and from whom.
- If approval is needed, the approval object (payload, display, plan, evidence) goes to the approvers’ devices. They render it themselves and sign its digest.
- The op goes into the queue with an idempotency key. The node leases it at its next sync.
- The node verifies the op against its own pinned catalog and roster and the plan, runs it and reports steps and result.
- 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.
Transport
Section titled “Transport”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.