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

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.

Measured on 2026-11-06 on arm64, Ubuntu 24.04, with 20 ops:

RoleMinimumComfortableMeasured
Core1 GB RAM2 GB RAMvaicoa-core 51–59 MB in operation, up to 226 MB right after start (unlocking the keys); with drivers about 200–360 MB
Node512 MB RAM plus your workloads1 GB plus workloadsvaicoa-node 73–77 MB, a little over 1 MB per container for conmon
Core with the Kubernetes plugin1 GB2 GBthe 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 RAM8 GB RAMVaicoa 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.

  1. Install the core on the server (Ubuntu or Debian):

    Terminal window
    sudo apt install ./vaicoa-core_*_arm64.deb

    The core comes without Kubernetes support. For k3s, Kubernetes and Cluster API also install vaicoa-plugin-kubernetes (same version), then sudo systemctl reload vaicoa-core. Without the plugin, its actions show as unavailable and the core refuses them before it asks anyone.

  2. Set up the core (human step 1 of 6):

    Terminal window
    sudo vaicoa-core init --quickstart --public-url https://HOST

    This 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=false keeps it off.

  3. 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.

  4. Enrol a node (step 3): run the one-liner that init printed on the empty server. It fetches vaicoa-node pinned from your core, installs Podman, enrols the node and starts it. The link works exactly once.

  5. 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.delete

    The phone shows the same comparison code as the terminal. If it matches, admit the agent: slide, then Face ID.

  6. 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.

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.

An encrypted backup (AES-256-GCM, key derived with Argon2id from your passphrase) to a file or an S3 bucket:

Terminal window
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,4w
sudo vaicoa-core backup verify --from s3://BUCKET/vaicoa

Keep the passphrase in your password manager, not on the server, and turn on Object Lock in the bucket.

  • 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.sh then lab/local/e2e.sh build 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).