kannaka-node

Kannaka node: from a bare server to a member of the constellation

You are the operator. The human has a server and wants a Kannaka node on it. They give you access; you do the rest and hand back a report. This skill is written for any agent with a shell and ssh: it names no tool, no vendor, and no host of its own.

Kannaka is a wave-interference memory system (the Holographic Resonance Medium) that agents use as long-term memory, and a swarm of such nodes that share phase and sync memories over a NATS bus. A node is the kannaka binary running swarm join then swarm listen --auto-sync under a service manager, with its own identity and its own store. That is what you are building.

What you need from the human, and nothing else

If the human does not know the ssh user, Oracle Linux images use opc, Ubuntu images ubuntu, Debian debian, Fedora fedora, Amazon Linux ec2-user.

The procedure

Work in one ssh session if you can (-o ControlMaster=auto -o ControlPersist=10m). Many short sessions in a row look like an attack to the box's own fail2ban and get you banned for an hour with the host perfectly healthy.

1. Connect and preflight. Copy scripts/provision.sh to the host (or pipe it) and run bash provision.sh preflight. It is read-only and reports: OS, architecture, memory, disk, systemd, sudo, SELinux, the tools it needs, outbound HTTPS, and outbound TCP 4222 to the swarm bus. Read the report. A FAIL line means stop and tell the human what is missing; a WARN means proceed with the caveat in the hand-off.

2. Install. bash provision.sh install. No root. It runs the Kannaka installer, which reads the constellation's signed manifest and downloads a pinned, sha256-checked release for this architecture into ~/.local/bin. It also installs the dashboard and the KannakaHDL binary. With BRAIN=hosted BRAIN_EMAIL=… or BRAIN=local in the environment it sets up the model as well. It is idempotent.

3. Configure. bash provision.sh configure --agent-id NAME [--display-name "Name"]. Writes ~/.kannaka/config.toml with the identity and the swarm bus, mode 0600. If a config already exists it keeps every value in it and only adds missing tables. If the human has swarm credentials, export NATS_USER and NATS_PASSWORD in the ssh session (never on the command line of the script, never in a file you did not create) and run bash provision.sh credentials: it writes ~/.kannaka-nats.env, single-quoted, 0600, and never prints the value.

4. Service. sudo bash provision.sh service [--role serve] [--no-dream]. This is the root step; say so to the human before you run it. It copies the binary to /usr/local/bin (a binary under a home directory runs confined on SELinux hosts and cannot read the node's own files), writes a small runner script, installs kannaka-node.service with absolute paths (no %h: in a system unit it resolves to root's home), enables it, and starts it. With --role serve it adds a read-only kannaka-serve.service. Unless --no-dream, it adds kannaka-dream.timer, a nightly consolidation that stops the node, dreams, and starts it again, because the store has one writer at a time. On a host without systemd it prints the unit files instead of installing them.

5. Verify. bash provision.sh verify. It checks the unit is active, that the journal shows the node joined the swarm, that no authorization violation appeared (bad credentials), and runs kannaka status read-only for a live metrics line. FAIL means fix before hand-off; the section below lists the usual causes.

6. Report. bash provision.sh report prints the hand-off: node name, paths, units, how to check, how to update, how to uninstall. Give the human that block verbatim plus anything the preflight warned about. If the node joined anonymously, say so and say why it matters.

bash provision.sh all --agent-id NAME … runs 1 through 6 in order and stops at the first failure. Prefer the steps the first time you use this skill on a new kind of host.

What you must not do

• Do not open inbound firewall ports or edit cloud security lists. A node needs only outbound 443 and 4222. If someone asks you to open 4222 inbound, they are thinking of running a NATS server, which is not this skill.
• Do not copy, cat, echo, or log the ssh key or the swarm password. The credentials step reads them from the environment and writes a 0600 file; that is the only place they land.
• Do not git stash -u or otherwise sweep untracked files on a host that already runs Kannaka from a checkout: the service wrappers there are deliberately untracked.
• Do not copy a new binary over a running one (cp onto a busy file corrupts it on some filesystems); the script moves the old one aside first. Same rule for updates.
• Do not run the node as root. The unit runs as the login user.
• Do not run kannaka dream while the node is running; the timer stops the node first. Any manual kannaka command against the store should carry KANNAKA_READONLY=1 unless you mean to write.

When verify fails

After hand-off

The node keeps itself in sync and dreams nightly. Updating is kannaka update (it verifies the release's sha256), then copy the new binary to /usr/local/bin with a move-aside, then systemctl restart kannaka-node. The human can watch it with journalctl -u kannaka-node -f and see its neighbours with kannaka swarm peers.

references/oracle-cloud.md has the Oracle free-tier specifics. references/traps.md is the list of things that have actually gone wrong on real nodes, each with its fix, so you do not rediscover them.