Quickstart (lab only)
This is the path a new user takes: one server for the core, one empty server as a node, your phone with the approval
app, and a coding agent. You work in solo mode: while you are the only person who can approve, you approve what
your own agent proposes. The lab script lab/local/quickstart.sh walks exactly this path; it needs six human steps
and just under two minutes.
What you need
Section titled “What you need”Measured on 2026-11-06 on arm64, Ubuntu 24.04, with 20 ops:
| Role | Minimum | Comfortable | Measured |
|---|---|---|---|
| Core | 1 GB RAM | 2 GB RAM | vaicoa-core 51–59 MB in operation, up to 226 MB right after start (unlocking the keys); with drivers about 200–360 MB |
| Node | 512 MB RAM plus your workloads | 1 GB plus workloads | vaicoa-node 73–77 MB, a little over 1 MB per container for conmon |
| Core with the Kubernetes plugin | 1 GB | 2 GB | the plugin costs about 25 MB; cluster servers need what k3s needs, plus 50–80 MB for the node |
| Everything on one machine (k3s server, core with plugin, node) | 4 GB RAM | 8 GB RAM | Vaicoa together 165–337 MB; k3s itself about 970 MB, typical add-ons about 400 MB |
Most of the 4–8 GB is k3s, not Vaicoa. A 24-hour soak test is still to come.
-
Install the core on the server (Ubuntu or Debian):
Terminal window sudo apt install ./vaicoa-core_*_arm64.debThe core comes without Kubernetes support. For k3s, Kubernetes and Cluster API also install
vaicoa-plugin-kubernetes(same version), thensudo systemctl reload vaicoa-core. Without the plugin, its actions show as unavailable and the core refuses them before it asks anyone. -
Set up the core (human step 1 of 6):
Terminal window sudo vaicoa-core init --quickstart --public-url https://HOSTThis creates the keys, the catalog, the policy and the systemd unit and starts the core. The terminal shows a QR code with a short link, the one-liner for your first node and a checklist. Solo mode is on;
--solo=falsekeeps it off. -
Become the first owner (step 2): scan the QR code with the approval app. The app shows “you are the first owner” with the CA fingerprint and “solo mode on”. Check them and confirm once with Face ID or fingerprint. That pairs the phone and signs the first roster. If the core’s roster differs from what the app showed, the app signs nothing and shows it to you separately.
-
Enrol a node (step 3): run the one-liner that
initprinted on the empty server. It fetchesvaicoa-nodepinned from your core, installs Podman, enrols the node and starts it. The link works exactly once. -
Connect an agent (steps 4 and 5), on the agent’s machine:
Terminal window vaicoa-run pair --core https://HOST:8444 --ca-sha256 <fingerprint> \--actions env.apply,env.deleteThe phone shows the same comparison code as the terminal. If it matches, admit the agent: slide, then Face ID.
-
First approval (step 6): let the agent propose something, for example “Deploy nginx as web in demo”. The app shows the badge “solo mode: you approve your own agent”. Read the facts, slide and confirm. The container runs on the node, and the history shows the op marked
solo.
What solo mode does not change
Section titled “What solo mode does not change”Face ID, sliding, picking or typing for destructive actions stay; so do expiry times, plans and every check on the
node. What you propose yourself directly still needs a second person. Under the starter profile solo mode shows in
vaicoa-core check as RELAXED, under standard as WEAKENED; under strict the core does not start with it.
When you invite a second member with the owner or operator role, solo mode ends with exactly that roster change, and four eyes apply from then on.
Back up the core
Section titled “Back up the core”An encrypted backup (AES-256-GCM, key derived with Argon2id from your passphrase) to a file or an S3 bucket:
sudo vaicoa-core backup --config /var/lib/vaicoa/core.yaml \ --to s3://BUCKET/vaicoa --passphrase-file /root/backup-pass \ --s3-credentials-file /root/s3.env --retention 7d,4wsudo vaicoa-core backup verify --from s3://BUCKET/vaicoaKeep the passphrase in your password manager, not on the server, and turn on Object Lock in the bucket.
Other ways in
Section titled “Other ways in”- Only the app, without a core (about 10 minutes): a fake core on a Mac and the Android app in the emulator.
- Fully automated (about 15 minutes):
lab/local/up.shthenlab/local/e2e.shbuild a core, two nodes and two people on local VMs and play through pairing, four-eyes approval, plan drift, agents and profiles.
Both are described in the user manual (docs/handbuch.md, “Schnellstart” A and B).