Cohesix 1.2.0 quickstart

Cohesix 1.2.0 is a published release. Download its archives and native host packages from the 1.2.0 release page. Check the release notes for the supported hosts, targets and qualification limits before choosing a download.

Cohesix is a control-plane OS that runs in QEMU or on a Raspberry Pi 4. Its shell, gateway, Python client and desktop UI run on your Mac or Linux host. This guide gets you from a release archive to an authenticated console, then shows how several clients can share one target through the gateway.

After your first connection, use the use-case guide to choose a 1.2.0 workflow. The host-tool guide covers the relevant CLI, gateway and evidence commands; Adoption describes a separate selected signed component-package installation.

Choose your download

Use all files from the same release. For 1.2.0:

When upgrading from 1.1.0-beta, extract into new directories and install the bundled Python wheel there. Keep each host’s binaries, QEMU image and generated contracts together. Export existing evidence before replacing a target image; copying an old policy or generated configuration into the new bundle does not migrate it. The bundled Python distribution and individual tools have their own package versions; VERSION.txt identifies the overall release.

Native host packages

The Mac .pkg and Linux .deb set are separate host installation choices. Check their installers.json package hashes against the downloaded bytes and verify publisher trust independently: macOS must accept the Developer ID Installer signature and stapled notarization; Linux must verify installers.json.asc with an already trusted publisher key. The package manifest alone cannot establish publisher identity. Use the package hashes and signing records from the published release page.

The Debian publisher key fingerprint is 6840 71A2 AF49 8008 930C F6AE EBB8 ECC4 9397 F8C2. Its public copy is cohesix-debian-publisher-2026.asc. Confirm this fingerprint through a trusted release announcement before using the key to verify a package signature.

On a supported Apple Silicon Mac, install the verified Cohesix-1.2.0-MacOS.pkg with macOS Installer. Open SwarmUI from Applications, Finder, Spotlight or the Dock. The host tools live in /Library/Application Support/Cohesix/bin; the app resolves them without a Terminal PATH. The installed cohesix-uninstall helper in that directory checks the package receipt and owned file hashes before removing package code. It leaves user state, credentials, models and evidence in place.

On the JetPack 7.2.1 ARM64 reference host, install the verified cohesix-controller_1.2.0_arm64.deb with apt. The optional cohesix-swarmui_1.2.0_arm64.deb adds the GNOME application entry and desktop dependencies. Open SwarmUI from GNOME search or the application grid. Headless controller use needs only the controller package; tools are under /usr/lib/cohesix/bin. apt remove or apt purge removes package code and desktop registration, while external operator state remains separate. Keep the 1.1.0-beta extracted directory intact for side-by-side migration; native installation does not adopt its credentials or evidence automatically.

These native packages install the host controller and, where selected, SwarmUI. They do not install the seL4 QEMU guest image, qemu/run.sh, or a QEMU executable. To run the VM, keep the matching Mac or Linux release archive and its guest files together, select QEMU with setup_environment.sh --with-qemu, and follow Boot the QEMU guest. Package installation by itself does not provision a bootable VM.

Each archive contains QUICKSTART.md, README.md, RELEASE_NOTES.md, VERSION.txt and MANIFEST.sha256. The Pi archive has no bin/, Python runtime or qemu/run.sh; run the host tools from the Mac or Linux archive. Host archives also carry the source-checked NeMo client wheel, Linux ARM64 dependency lock and explicit installer. Install that optional kit only on a compatible Linux client host after checking its recorded hashes and selecting a private environment; see the bundled integrations/nemo-agent-toolkit/README.md. You do not need Rust, seL4 build tools, or a GPU to use the prebuilt host tools. For a source checkout, use Build from source below.

1. Extract and verify

Use a new directory for each archive. The examples use Bash; on a Mac, enter bash in Terminal first. In each additional terminal, use Bash and change into the same extracted host bundle. Replace archive names with the one you downloaded; do not paste angle-bracket placeholders literally.

mkdir -p "$HOME/cohesix-releases"
cd "$HOME/cohesix-releases"
tar -xzf "$HOME/Downloads/Cohesix-1.2.0-MacOS.tar.gz"
cd Cohesix-1.2.0-MacOS

Before running anything, verify all manifest entries:

# macOS
shasum -a 256 --check MANIFEST.sha256

# Linux
sha256sum --check MANIFEST.sha256

Every entry must report OK. Check VERSION.txt and RELEASE_NOTES.md for the intended release and its limitations. Obtain archives from the trusted release publisher; the internal hashes detect changed files, not publisher identity. Keep the archive so you can make another clean extraction.

2. Set up the Mac or Linux host

Run these commands from the host bundle root, including when your target is a Pi. Installation may download host packages and ask for administrator access; run the script as your normal user:

./scripts/setup_environment.sh
./scripts/setup_environment.sh --check
source .venv/bin/activate

The script installs host runtime dependencies and the bundled Python wheel into this bundle’s .venv. It does not build Cohesix or install CUDA drivers. QEMU is optional for host-only or Pi operation. Before Step 3, run:

./scripts/setup_environment.sh --with-qemu
./scripts/setup_environment.sh --check --with-qemu

On Mac, setup checks the actual four-core HVF startup envelope. If the current Homebrew QEMU fails it, setup builds the pinned QEMU 10.1.0 with the Cohesix HVF fix from hash-checked upstream source in your user directory. This needs Homebrew build dependencies and at least 2 GiB free; it does not replace the system QEMU. On Linux, setup uses Ubuntu’s qemu-system-arm package and checks four-core KVM startup. If your system QEMU cannot start that profile, setup stops with a clear error instead of silently using TCG. --check never installs or builds packages. The release launcher selects the verified QEMU from this bundle’s .venv when present. On a Linux host without a desktop, add --headless to both setup commands; this omits SwarmUI’s graphical libraries while retaining the controller, Python and optional QEMU dependencies.

Verify the tools without a target:

./bin/coh doctor --mock
./bin/cohsh --transport mock --role queen

At the coh> prompt, try help, ls /, cat /proc/boot, then quit. Mock output is simulated. You can also create a sample evidence pack and run a packaged Python example:

./bin/coh evidence pack --mock --out out/evidence/quickstart-mock
./bin/coh evidence timeline --input out/evidence/quickstart-mock
python python/cohesix-py/examples/lease_run.py --mock

For a physical Pi, continue with Install the Pi image.

3. Boot the QEMU guest

In terminal 1, from the host bundle root:

./qemu/run.sh

Leave it running. The launcher uses four cores and GICv3, with HVF on Mac and KVM on eligible Linux hosts. Wait for [mark] root-console.start.ok and the cohesix> prompt. The serial console supports ping, bi, caps mcs, smp mcs, mem and netstats for boot and network inspection.

The default forwarded endpoints are 127.0.0.1:31337 (TCP console), UDP 31338 and TCP 31339. If occupied, stop the prior instance or select free host ports, for example:

TCP_PORT=32337 UDP_PORT=32338 SMOKE_PORT=32339 ./qemu/run.sh

Use the chosen TCP port when connecting below. Do not change CPU, timer, core count or machine options to get around a failed native boot. A Linux fallback to TCG is a slower diagnostic run and does not establish native release acceptance. A different Linux counter frequency needs a compatible guest build.

Continue with Connect to your target, using 127.0.0.1 and port 31337 unless you changed the host port.

4. Install the Pi 4 SD image

Use a Pi 4, a suitable power supply, an SD card and reader, an HDMI display and a USB keyboard. Connect Ethernet to your local network, or use the boot menu to configure Wi-Fi. The host computer must be able to reach the selected Pi address. Cohesix boots directly on the Pi; you do not first install Raspberry Pi OS or run the Linux host bundle on the bare Cohesix target.

Extract the -Pi4 archive and verify its MANIFEST.sha256 as in step 1. The following commands run from that Pi bundle root. Verify the image sidecar too:

# macOS
(cd image && shasum -a 256 --check cohesix-pi4-sd.img.sha256)
# Linux: use sha256sum --check in the same image directory instead.

image/cohesix-pi4-sd.img is the complete raw MBR/FAT32 image. Read image/cohesix-pi4-sd.json: the card’s byte capacity must be at least minimum_target_bytes. Extra capacity on larger cards remains unallocated; no expansion is needed. Flashing replaces the whole card, including any saved network settings. Back up anything you need before proceeding.

Write and read back on Mac

Discover the removable card again after insertion. Apple’s built-in SDXC reader appears as an internal, physical disk, so inspect diskutil list rather than filtering for external disks. Replace diskN below with the exact whole disk; check its model, removable status and byte size using diskutil info. The commands erase the selected disk:

diskutil list
diskutil info /dev/diskN
diskutil unmountDisk /dev/diskN
sudo python3 - image/cohesix-pi4-sd.img /dev/rdiskN <<'PY'
import hashlib
import os
from pathlib import Path
import plistlib
import subprocess
import sys

image, raw = Path(sys.argv[1]), sys.argv[2]
if not raw.startswith('/dev/rdisk') or not raw[10:].isdigit():
    raise SystemExit('select an explicit whole raw disk such as /dev/rdisk22')
whole = '/dev/disk' + raw[10:]
info = plistlib.loads(subprocess.check_output(['diskutil', 'info', '-plist', whole]))
if not (info.get('WholeDisk') and info.get('RemovableMedia')
        and info.get('Writable') and info.get('VirtualOrPhysical') == 'Physical'
        and info.get('BusProtocol') == 'Secure Digital'
        and info.get('TotalSize', 0) >= image.stat().st_size):
    raise SystemExit('selected disk is not a writable removable SD card of sufficient size')
with image.open('rb') as source, open(raw, 'r+b', buffering=0) as card:
    while chunk := source.read(1024 * 1024):
        if card.write(chunk) != len(chunk):
            raise SystemExit('short SD write')
    card.flush()
    os.fsync(card.fileno())
    source.seek(0)
    expected, actual = hashlib.sha256(), hashlib.sha256()
    with open(raw, 'rb', buffering=0) as readback:
        while chunk := source.read(1024 * 1024):
            expected.update(chunk)
            data = readback.read(len(chunk))
            if len(data) != len(chunk):
                raise SystemExit('short SD readback')
            actual.update(data)
    if actual.digest() != expected.digest():
        raise SystemExit('SD readback differs from the distributed image')
print('SD write and whole-image readback: PASS')
PY
diskutil eject /dev/diskN

Keep the raw device open through the readback: macOS can otherwise remount the new FAT partition and write Spotlight/FSEvents files before a separate cmp starts. Eject immediately after PASS; do not mount or browse the card between verification and eject. Do not boot on a write, readback or eject error.

Write and read back on Linux

Identify the removable whole disk by model, transport and byte size. It may be /dev/sdX or /dev/mmcblkN. Unmount each mounted partition shown by lsblk; for example, use sudo umount /dev/sdX1 for that listed partition. Substitute the verified whole disk in the write and readback commands:

lsblk --bytes --output NAME,SIZE,TYPE,TRAN,MODEL,MOUNTPOINTS
sudo dd if=image/cohesix-pi4-sd.img of=/dev/sdX bs=4M conv=fsync status=progress
IMAGE_BYTES=$(stat -c %s image/cohesix-pi4-sd.img)
sudo cmp -n "$IMAGE_BYTES" image/cohesix-pi4-sd.img /dev/sdX

Require a successful write and a zero-exit, silent comparison. To inspect the target’s credential reference, reinsert the reader so the new partition table is recognised, then mount the FAT partition using your desktop disk utility. Unmount it after reading and eject or safely remove the card. Do not use a partition such as /dev/sdX1 as the destination for the raw image.

First boot and network configuration

Before booting, obtain the exact Pi image’s Queen console credential from its provisioner as described in step 5. The queen ticket entry in the card’s cohesix-root-task-resolved.json identifies its secret_ref; the reference is not the credential value. The Pi credential can differ from the QEMU bundle’s and is separate from the Wi-Fi password.

Insert the ejected card into the Pi, attach HDMI and the USB keyboard, then power it on. The image stops at Cohesix boot menu; it does not automatically skip network setup. For a first installation:

1. Select 2 — Change network settings.
2. Select Automatic (DHCP), or Manual (static IPv4) with a valid address, subnet prefix and optional gateway for your network.
3. Select Ethernet (wired) or Wi-Fi (wireless). For Wi-Fi, enter the SSID and password on the attached USB keyboard. They are visible on the local display and hidden from serial output; do not enter passwords over serial.
4. On Review network settings, select 2 — Save settings and restart.
5. After restart, verify Saved network settings loaded, then select 1 — Boot with saved settings.

The Boot once without saving option is temporary. Saving creates cohesix.env on the card; treat that file and the card as credentials. Changing networks later uses the same menu, without reflashing. If keyboard setup is unavailable, the bounded offline cohesix.env procedure is in First-boot network policy.

Wait for the cohesix> console and inspect netstats. For DHCP, find the assigned address in the boot/network output or your router’s lease table; for static mode, use the address you configured. Confirm the active interface and address before connecting. A blank display or missing USB input is a boot/input problem, not a reason to guess network settings. A correctly wired serial console at 115200 baud can retain boot output; use one serial owner and follow Hardware Bring-up for capture and diagnostics.

5. Connect to your target

In terminal 2, change into the Mac or Linux host bundle. Obtain the Queen console credential from the provisioner of the exact target image. For QEMU, inspect the queen entry in configs/generated/root_task_resolved.json; for Pi, inspect the image’s cohesix-root-task-resolved.json. Selected manifests retain a secret_ref, such as env:COH_TICKET_QUEEN_KEY, rather than the credential value. Use the value supplied through that reference when the image was built. An older development manifest may instead contain a literal secret; inspect it locally without printing it into shared logs. The Pi’s cohesix.env network settings and Wi-Fi password are separate from console authentication.

Ticket credentials are embedded in the target image. Treat an image built with private deployment credentials as private too. A public evaluation image must use a separate explicitly shared keyset, never keys used by a private hive. Changing a host environment variable or editing a copied manifest does not rotate the credential in an existing target image; rebuild and qualify the replacement image with the new credential.

Enter the target credential without putting it in shell history (Bash):

read -r -s -p 'Target console token: ' COHSH_AUTH_TOKEN
printf '\n'
export COHSH_AUTH_TOKEN
export COH_AUTH_TOKEN="$COHSH_AUTH_TOKEN"
TARGET_HOST=127.0.0.1
TARGET_PORT=31337

For Pi, replace 127.0.0.1 with its actual IP address. For an alternate QEMU forward, use the selected host TCP port. Connect:

./bin/cohsh --transport tcp --tcp-host "$TARGET_HOST" \
  --tcp-port "$TARGET_PORT" --role queen

At coh>, try these read-only observations:

ping
ls /
cat /proc/boot
cat /proc/root/reachable
cat /proc/schedule/summary
cat /proc/lease/summary
ls /shard
quit

Success means the authenticated session attached, the reads returned bounded responses, and /proc/boot identifies the intended target. quit closes the session; it does not power off the Pi. The canonical Worker namespace is /shard. Runtime observations and mock output are different proof sources; this quickstart is not a complete hardware or performance qualification.

TCP authentication provides no encryption. Keep QEMU forwards on loopback. Use a private controlled network for Pi, or terminate an encrypted tunnel/VPN on a host gateway. Only one direct TCP client may own the target at a time.

6. Share the target through the gateway

Close the direct cohsh session first. In terminal 2, retaining the target address and credential above, choose a separate strong request token for gateway writes and start the gateway:

read -r -s -p 'New gateway request token: ' HIVE_GATEWAY_REQUEST_AUTH_TOKEN
printf '\n'
export HIVE_GATEWAY_REQUEST_AUTH_TOKEN
export COH_REST_URL=http://127.0.0.1:8080
./bin/hive-gateway --bind 127.0.0.1:8080 \
  --tcp-host "$TARGET_HOST" --tcp-port "$TARGET_PORT"

In terminal 3, from the host bundle root:

export COH_REST_URL=http://127.0.0.1:8080
curl --fail --silent --show-error "$COH_REST_URL/v1/meta/status"
./bin/cohsh --transport rest --rest-url "$COH_REST_URL" --role queen

Require connected: true before using the REST-backed shell. These clients share the gateway’s upstream role and ticket. For writes, securely set the same HIVE_GATEWAY_REQUEST_AUTH_TOKEN in the client terminal; a new terminal does not inherit variables exported in terminal 2.

After quitting the shell, launch the desktop UI through that same gateway:

SWARMUI_TRANSPORT=rest SWARMUI_REST_URL="$COH_REST_URL" ./bin/swarmui

SwarmUI needs a graphical desktop. On a headless Jetson, use the CLI/REST clients or an existing remote desktop; xvfb-run provides an off-screen test display, not a visible desktop. Python users can activate .venv in this terminal and follow Python support for RestBackend. For optional real NVIDIA inventory, run ./bin/gpu-bridge-host --list on the Linux GPU host; Host tools covers publishing it through the gateway. GPU discovery does not establish model execution.

When finished, quit clients, stop the gateway with Ctrl-C, then exit QEMU with Ctrl-A, followed by X. Avoid cutting Pi power while its boot menu is saving settings. Clear credentials from each terminal that used them:

unset COHSH_AUTH_TOKEN COH_AUTH_TOKEN HIVE_GATEWAY_REQUEST_AUTH_TOKEN

If something fails

See Userland and CLI for commands, Hardware Bring-up for Pi diagnostics, and Host tools for mounts, GPU bridges, tickets and evidence packs. For 1.2.0 CUDA/LoRA, Mac MLX, MCP/A2A and NeMo workflows, start with the use-case guide and check your installed profile against current status.

Build from source

This section requires a source checkout; the runtime bundles intentionally omit the build toolchain. Follow the source README for the Mac or Linux installer. The installers prepare dependencies; they do not build Cohesix host binaries or seL4 target artifacts. Complete the source README’s external seL4 preparation and QEMU profile build before running the Mac source build below. Then activate the tools from the repository root:

source "$HOME/.cargo/env"
source .venv/bin/activate
export SEL4_BUILD_DIR="$PWD/out/sel4/profile-v2/qemu-smp-production"
./scripts/cohesix-build-run.sh \
  --sel4-build "$SEL4_BUILD_DIR" --out-dir out/cohesix \
  --profile release --root-task-features release-qemu,bootstrap-trace \
  --cargo-target aarch64-unknown-none --transport tcp

Use out/cohesix/host-tools/ in place of the release’s bin/ for host commands. The Linux installer supplies host-build dependencies and diagnostic QEMU; the native Linux release lane requires its own built 31.25 MHz KVM seL4 profile. See the release factory for native builds and release qualification. Do not mix checkout artifacts with an extracted release.