cohesix

Cohesix is an open-source high-assurance control-plane operating system built on the formally verified seL4 microkernel, designed to keep the trusted computing base intentionally small while enabling deterministic orchestration of edge GPU systems and auditable MLOps. Cohesix is "infrastructure for AGI".

View the Project on GitHub lukeb-aidev/cohesix

Cohesix Userland & CLI

Philosophy

cohsh is the canonical operator shell for the entire hive: one Queen orchestrating many workers via a shared Secure9P namespace.

At a glance

Overview

Cohesix userland exposes two operator entry points:

Use the root console for low-level validation (bootinfo, capability layout, untyped counts) and quick liveness checks. Use cohsh for day-to-day operator workflows and NineDoor interactions.

Related docs

Operator rules of engagement

Root Console (PL011 / QEMU Serial)

Access and purpose

Commands (current behaviour)

Example boot and probe

[cohesix:root-task] [uart] init OK
[console] PL011 console online
cohesix> help
Commands:
  help  - Show this help
  bi    - Show bootinfo summary
  caps  - Show capability slots
  smp   - Show SMP scheduler/CPU info (debug builds only)
  mem   - Show untyped summary
  ping  - Respond with pong
  quit  - Exit the console session
cohesix> bi
[bi] node_bits=12 empty=[0x0010..0x0100) ipc=0x7f000000
cohesix> caps
[caps] root=0x0001 ep=0x0002 uart=0x0003
cohesix> mem
[mem] untyped caps=16 ram_ut=14 device_ut=2
cohesix> ping
pong

Use this surface to confirm boot-time state before bringing up TCP or NineDoor; it is not the operator-facing control plane.

cohsh Shell (Host CLI)

What it is

Transport selection

| Transport | Requires | Best for | Notes | | — | — | — | — | | tcp | QEMU or hardware console | Live ops | Single-client console. | | rest | hive-gateway | Multiplexed ops | Queen-only; uses gateway REST projection. | | mock | none | CI, demos | Deterministic in-process backend. | | qemu | QEMU binary + artifacts | Dev convenience | Spawns QEMU and attaches. |

CLI flags (current)

Key options from --help:

Manifest-derived policy defaults are emitted by coh-rtc into out/cohsh_policy.toml and embedded into the CLI at build time. The CLI refuses to start if the policy or manifest hash drifts.

Auth token vs ticket

cohsh client policy (generated)

Generated from configs/root_task.toml (sha256: 3a20adc55c8f975e20e8ef031422f8a09b4a7b8e524dd052bf69296ddf7ff1af).

Manifest-derived CohClient defaults (paths and Secure9P bounds) are emitted by coh-rtc.

cohsh client defaults (generated)

Generated from configs/root_task.toml (sha256: 3a20adc55c8f975e20e8ef031422f8a09b4a7b8e524dd052bf69296ddf7ff1af).

Shared console grammar and ticket policy are emitted by coh-rtc from cohsh-core so CLI and console stay aligned.

cohsh console grammar (generated)

Generated from cohsh-core verb specs (18 verbs).

Lifecycle control (cohsh)

cohsh ticket policy (generated)

Generated from cohsh-core ticket policy.

Ticket quota limits (generated)

Generated by coh-rtc (sha256: 1b869521f68c26d43c1ad278fbc557f2442e438ab12d443a142e53a33e4466fb).

coh Host Bridges (Mount / GPU / Run / Evidence / Telemetry Pull)

Common live prerequisites

PEFT registry layout (host-side, file-native):

Manifest-derived coh policy defaults are emitted by coh-rtc.

coh policy defaults (generated)

coh doctor

coh doctor checks (generated)

Generated by coh-rtc (sha256: 66febf7b6dae0625c6a004490655dfcea1dd5777fe6792ecf027164df8f2ab4f).

cohesix Python client

Manifest-derived cohesix defaults are emitted by coh-rtc.

Cohesix Python defaults (generated)

Generated by coh-rtc (sha256: ef522e0341d65fb59287879364b7c0f066eaddb4121dc18463c8d07abd7ba07d).

SwarmUI Desktop (Host UI)

Manifest-derived SwarmUI defaults are emitted by coh-rtc.

SwarmUI defaults (generated)

Generated from configs/root_task.toml (sha256: 1aee4b854f804a6f250d113062597502ba30a1198315c33fe0156d5d2d1b7cb3).

Interactive shell surface

Startup banner and prompt:

Welcome to Cohesix. Type 'help' for commands.
detached shell: run 'attach <role>' to connect
coh>

Commands and status:

Attachment semantics:

Connection handling (TCP transport):

Acknowledgements and heartbeats

Script mode

--script <file> feeds newline-delimited commands; blank lines and lines starting with # are ignored. Errors abort the script and bubble up as a non-zero exit.【F:apps/cohsh/src/lib.rs†L732-L763】

coh scripts (.coh)

Purpose

Non-goals

Execution model

Syntax

Two statement families:

  1. Command line
    • Any line that does not start with EXPECT is interpreted as a cohsh command exactly as typed at coh>.
  2. Assertion line
    • Assertions apply only to the last executed command and evaluate against the last command response line (single line as emitted by cohsh for that command).
    • EXPECT OK — last command response line must begin with OK.
    • EXPECT ERR — last command response line must begin with ERR.
    • EXPECT SUBSTR <text> — last command response line must contain <text> as a substring (case-sensitive).
    • EXPECT NOT <text> — last command response line must not contain <text>.

An optional control statement is provided for bounded waits: WAIT <ms> pauses locally (does not issue a server command) for the requested duration.

For streaming commands, the “response line” is the initial acknowledgement line (OK … or ERR … that starts the stream), not any subsequent streamed payload lines.

Determinism & bounds

Preinstalled self-test scripts

coh> test reads .coh scripts from /proc/tests/:

coh> test JSON schema

When invoked with --json, coh> test emits:

{
  "ok": true,
  "mode": "quick",
  "elapsed_ms": 123,
  "checks": [
    {"name": "preflight/ping", "ok": true, "detail": "OK ping"},
    {"name": "line 4: cat /proc/boot", "ok": true, "detail": "OK"}
  ],
  "version": "1"
}

Security posture

Examples

Quick check (ping, proc read, and an expected error):

# connectivity and auth sanity
ping
EXPECT OK
cat /proc/queen/state
EXPECT OK
echo forbidden > /queen/ctl
EXPECT ERR

Disposable worker lifecycle with ID assertion:

spawn gpu gpu_id=GPU-0 mem_mb=4096 streams=1 ttl_s=60
EXPECT OK
ls /shard
EXPECT OK
EXPECT SUBSTR path=/shard
tail /shard/<label>/worker/worker-123/telemetry
EXPECT OK
WAIT 500
kill worker-123
EXPECT OK
EXPECT NOT ERR

End-to-End Workflow: QEMU + cohsh over TCP

This section covers the development harness for running Cohesix on QEMU; production deployments target physical ARM64 hardware booted via UEFI with equivalent console and cohsh semantics.

Terminal 1 – build and boot under QEMU

Run the build wrapper to compile components, stage host tools, and launch QEMU with PL011 serial plus a user-mode TCP forward to 127.0.0.1:<port>:

SEL4_BUILD_DIR="$PWD/seL4/SMP_build" ./scripts/cohesix-build-run.sh \
  --sel4-build "$PWD/seL4/SMP_build" \
  --out-dir out/cohesix \
  --profile release \
  --root-task-features cohesix-dev \
  --cargo-target aarch64-unknown-none \
  --transport tcp

Use --sel4-build "$PWD/seL4/build" to target the single-core baseline (keeps SMP artifacts separate). The script builds root-task with the serial and TCP console features, compiles NineDoor and workers, copies host tools (cohsh, gpu-bridge-host, host-sidecar-bridge) into out/cohesix/host-tools/, and assembles the CPIO payload.【F:scripts/cohesix-build-run.sh†L369-L454】【F:scripts/cohesix-build-run.sh†L402-L442】 QEMU runs with -serial mon:stdio and a user-net device that forwards TCP/UDP ports 31337–31339 into the guest so the TCP console and self-tests are reachable from the host.【F:scripts/cohesix-build-run.sh†L518-L553】 The wrapper selects the NIC backend from the root-task features: dev-virt (via cohesix-dev) uses virtio-net by default, which adds -global virtio-mmio.force-legacy=false for the modern header; removing net-backend-virtio switches the wrapper to RTL8139 instead.【F:scripts/cohesix-build-run.sh†L518-L553】 The script prints the ready command for cohsh once QEMU is live.【F:scripts/cohesix-build-run.sh†L546-L553】 In deployment, the same console and cohsh flows apply to UEFI-booted ARM64 hardware without the VM wrapper.

Virtio-MMIO modes (when net-backend-virtio is enabled)

Verify the modern TCP path quickly

Terminal 2 – host cohsh session over TCP

From out/cohesix/host-tools/:

./cohsh --transport tcp --tcp-port 31337
Welcome to Cohesix. Type 'help' for commands.
detached shell: run 'attach <role>' to connect
coh> attach queen
[console] OK ATTACH role=Queen session=1
attached session SessionId(1) as Queen
coh>

Use log to stream /log/queen.log, ping for health, and tail <path> for ad-hoc inspection. If the TCP session resets, cohsh reports the error and continues in a detached state; reconnects are attempted automatically with back-off in interactive mode.【F:apps/cohsh/src/transport/tcp.rs†L54-L73】

Scripted Sessions with --script

Example script (queen.coh):

# Attach and tail the queen log
attach queen
log
quit

Run via ./cohsh --transport tcp --tcp-port 31337 --script queen.coh. The runner stops on the first error (including connection failures) and propagates the error code to the host shell.【F:apps/cohsh/src/lib.rs†L732-L763】 Use ./cohsh --check <script.coh> to validate .coh syntax without executing commands.【F:apps/cohsh/src/main.rs†L28-L138】

GUI clients

Debugging TCP Console Issues

Future Root Console Extensions (ideas)

Not implemented yet, but likely additions for debugging:

References & Cross-links