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

Host Tools

Host tools run outside the VM and project the same file/console semantics the VM enforces. They do not introduce new control-plane verbs or bypass Secure9P; every tool is a convenience wrapper over LS, CAT, ECHO, and/or mounted Secure9P namespaces.

0.9.0-beta note This release introduces hive-gateway as the supported multiplexing layer for host tools. When you need multiple tools or remote operators, run hive-gateway as the sole console client and point every other tool at it using REST.

Build + locations

All examples below use ./bin/<tool> as the bundle layout. In the source tree, replace ./bin with out/cohesix/host-tools (staged) or target/<profile> (manual).

Live auth prerequisites (non-mock)

export COH_AUTH_TOKEN=replace-with-real-token
export COHSH_AUTH_TOKEN="$COH_AUTH_TOKEN"
export HIVE_GATEWAY_REQUEST_AUTH_TOKEN=replace-with-real-token

coh, cohsh, and hive-gateway reject the insecure placeholder token changeme in non-mock mode.

Console exclusivity The TCP console is single-client. Only one of cohsh, swarmui, hive-gateway, coh, gpu-bridge-host, host-sidecar-bridge, host-ticket-agent, cas-tool, or a Python TcpBackend should be attached at a time. cohsh enforces this with a lock file; set COHSH_CONSOLE_LOCK=0 only if you understand the risk. For multiplexed deployments, run hive-gateway as the sole console client and point host tools at it using REST (--rest-url, COH_REST_URL, or SWARMUI_REST_URL) with request-auth configured (--rest-auth-token or HIVE_GATEWAY_REQUEST_AUTH_TOKEN / COHSH_REST_AUTH_TOKEN / COH_REST_AUTH_TOKEN; SwarmUI also supports SWARMUI_REST_AUTH_TOKEN). coh mount --rest-url is limited to one active mount per gateway URL (host-side lock).

Choosing a transport Use the TCP console when a single tool is active and you want minimal hops. Use hive-gateway when you need multiple tools, remote operators, or a REST surface.

Scenario Recommended transport Why
Single operator, local machine TCP console Lowest latency, simplest mental model.
SwarmUI + CLI together REST via hive-gateway Console is single-client; REST multiplexes.
Remote Mac controlling a GPU host REST via SSH tunnel Keeps console on the host, secure remote access.
Multiple publishers (gpu + host-sidecar) REST via hive-gateway One console client, many REST clients.

Hive-gateway quickstart (0.9.0-beta)

Goal: run hive-gateway as the only console client and route all tools through REST.

  1. Boot the Queen VM. 
    ./qemu/run.sh
  2. Start the gateway (queen role). 
    COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway
  3. Verify the gateway is healthy. 
    curl -sS http://127.0.0.1:8080/v1/meta/bounds | jq .
curl -sS 'http://127.0.0.1:8080/v1/fs/ls?path=/' | jq .
  4. Attach cohsh via REST (not TCP). 
    ./bin/cohsh --transport rest --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --role queen
  5. Publish host snapshots through the gateway. 
    ./bin/gpu-bridge-host --publish --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --interval-ms 1000
./bin/host-sidecar-bridge --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --watch
  6. Launch SwarmUI over REST. 
    SWARMUI_TRANSPORT=rest SWARMUI_REST_URL=http://127.0.0.1:8080 \
  SWARMUI_REST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" ./bin/swarmui

cohsh

Purpose

Canonical operator shell for Cohesix. Runs on the host and attaches to NineDoor over the TCP console, the REST gateway multiplexer, or mock/QEMU transports for development. It never runs inside the VM and does not add new control-plane semantics.

Location

Usage

# TCP console (single client).
./bin/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role queen

# REST gateway (multiplexed; hive-gateway is the sole console client).
./bin/cohsh --transport rest --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --role queen

# QEMU (dev convenience).
./bin/cohsh --transport qemu --qemu-out-dir out/cohesix --qemu-arg "-nographic"

# Mock (offline, in-process NineDoor).
./bin/cohsh --transport mock --mock-seed-gpu

# Run or validate a .coh script.
./bin/cohsh --transport tcp --script scripts/cohsh/boot_v0.coh
./bin/cohsh --check scripts/cohsh/boot_v0.coh

# Mint a ticket (worker roles require a subject).
./bin/cohsh --mint-ticket --role worker-heartbeat --ticket-subject worker-1

Session + auth model

Core commands (interactive)

| Command | Notes | | — | — | | help | List available shell commands and console verbs. | | attach <role> [ticket] | Start a session (login is an alias). | | ls <path> | Enumerate directory entries. | | cat <path> | Read file contents once. | | tail <path> | Stream a file. | | log | Alias for tail /log/queen.log. | | echo <text> > <path> | Append a single line; adds a newline. | | spawn <role> ... | Queue worker spawn (see examples below). | | kill <worker_id> | Queue worker termination. | | bind <src> <dst> | Bind namespace path (queen session required). | | mount <service> <path> | Mount a service namespace (queen session required). | | lifecycle <cordon\|drain\|resume\|quiesce\|reset> | Node lifecycle controls via /queen/lifecycle/ctl (queen session required). | | telemetry push <file> --device <id> | Push a bounded telemetry segment. | | test [--mode <quick\|full\|smp>] [--json] [--timeout <s>] [--no-mutate] | Run self-tests (timeout 1–120s). | | ping | Health check; reports attach + transport status. | | tcp-diag [port] | TCP connectivity check without protocol traffic (TCP builds only). | | pool bench <opts> | Pooled throughput benchmark (advanced). | | quit | Close the session and exit. |

Spawn examples

coh> spawn heartbeat ticks=120
coh> spawn heartbeat ticks=50 ttl_s=60 ops=500
coh> spawn gpu gpu_id=GPU-0 mem_mb=4096 streams=1 ttl_s=120
coh> spawn gpu gpu_id=GPU-0 mem_mb=4096 streams=1 ttl_s=120 priority=3 budget_ttl_s=300 budget_ops=500

Tests

test executes the bundled .coh scripts under /proc/tests/ (for example selftest_smp.coh). Default timeout is 30s; maximum is 120s.

coh> test --mode quick
coh> test --mode full --timeout 120
coh> test --mode smp
coh> test --mode quick --no-mutate
coh> test --mode full --json

Pool bench examples

pool bench writes bounded payloads to a path and measures baseline vs pooled throughput. Use append-only paths (for example /log/queen.log or worker telemetry).

coh> pool bench path=/log/queen.log ops=50 kind=control
coh> pool bench path=/log/queen.log ops=200 batch=4 payload_bytes=64 kind=control
coh> pool bench path=/worker/<id>/telemetry ops=200 batch=8 kind=telemetry payload=telemetry
coh> pool bench path=/log/queen.log ops=50 kind=control inject_failures=2 inject_bytes=8
coh> pool bench path=/log/queen.log ops=20 kind=control exhaust=4

Telemetry push

telemetry push accepts txt, log, json, ndjson, or csv inputs and forwards bounded records to /queen/telemetry/<device_id>/. When source bytes exceed inline envelope limits, cohsh emits bounded coh-ref-c/v1 reference-manifest records (manifest-driven entry/byte limits) instead of generic file transfer.

coh> telemetry push demo/telemetry/demo.txt --device device-1
coh> telemetry push demo/telemetry/sample.ndjson --device jetson-1
coh> telemetry push demo/telemetry/sample.csv --device g5g-1

Quota checks (why you see ELIMIT)

cohsh enforces ticket-scoped quotas in the root-task. Each attached session carries a ticket with:

If a command exceeds these limits, the console returns ERR ... reason=ELIMIT (quota) or ERR ... reason=EPERM (scope). Fixes are:

Tips & gotchas

Notes

coh

Purpose

Host bridge for mount, GPU leases, telemetry pulls, runtime breadcrumbs, PEFT lifecycle glue, and environment checks (coh doctor).

Location

Usage

Usage: coh [OPTIONS] 

Commands:
  doctor     Run deterministic environment checks
  mount      Mount a Secure9P namespace via FUSE
  gpu        GPU discovery and lease operations
  peft       PEFT/LoRA lifecycle operations
  run        Run a host command with lease validation and breadcrumb logging
  telemetry  Telemetry pull operations
  evidence   Evidence pack and timeline operations
  fleet      Read-only multi-hive fan-in status commands
  help       Print this message or the help of the given subcommand(s)

Options:
      --role <ROLE>
          Role to use when attaching to Secure9P

          Possible values:
          - queen:            Queen orchestration role
          - worker-heartbeat: Worker heartbeat role
          - worker-gpu:       Worker GPU role
          - worker-bus:       Worker bus role
          - worker-lora:      Worker LoRa role
          
          [default: queen]

      --ticket <TICKET>
          Optional capability ticket payload

      --policy <FILE>
          Path to the manifest-derived coh policy TOML

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

./bin/coh doctor --mock
./bin/coh gpu --rest-url http://127.0.0.1:8080 --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" list
./bin/coh mount --rest-url http://127.0.0.1:8080 --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --at /tmp/coh-mount
./bin/coh gpu list --host 127.0.0.1 --port 31337
./bin/coh gpu lease --host 127.0.0.1 --port 31337 --gpu GPU-0 --mem-mb 4096 --streams 1 --ttl-s 60 \
  --receipt-out ./out/receipts/lease.json
./bin/coh run --host 127.0.0.1 --port 31337 --gpu GPU-0 --receipt-out ./out/receipts/run.json -- echo ok
./bin/coh telemetry pull --host 127.0.0.1 --port 31337 --out ./out/telemetry
./bin/coh evidence pack --host 127.0.0.1 --port 31337 --out ./out/evidence/live --with-telemetry
./bin/coh evidence timeline --in ./out/evidence/live
./bin/coh fleet status --rest-url http://127.0.0.1:8080 --hive hive-a=http://127.0.0.1:8080 --hive hive-b=http://127.0.0.1:8081 --hive hive-c=http://127.0.0.1:8082
./bin/coh fleet lease-summary --rest-url http://127.0.0.1:8080 --hive hive-a=http://127.0.0.1:8080 --hive hive-b=http://127.0.0.1:8081 --hive hive-c=http://127.0.0.1:8082
./bin/coh fleet pressure --rest-url http://127.0.0.1:8080 --hive hive-a=http://127.0.0.1:8080 --hive hive-b=http://127.0.0.1:8081 --hive hive-c=http://127.0.0.1:8082
./bin/coh peft export --host 127.0.0.1 --port 31337 --job job_8932 --out ./out/export
./bin/coh peft import --host 127.0.0.1 --port 31337 --publish --model demo-model \
  --from demo/peft_adapter --job job_8932 --export ./out/export --registry ./out/model_registry
./bin/coh peft activate --host 127.0.0.1 --port 31337 --model demo-model --registry ./out/model_registry
./bin/coh peft rollback --host 127.0.0.1 --port 31337 --registry ./out/model_registry

Evidence packs

coh evidence pack exports a deterministic on-disk directory sourced only from existing Cohesix surfaces (/proc, /log, /audit, /replay, telemetry). It is suitable for audits, due diligence, and incident review.

Pack layout (relative to --out):

coh evidence timeline generates timeline.ndjson and timeline.md offline from the pack directory.

CI + SIEM integration kits (Python)

CI validation (machine-readable summary JSON, non-zero exit on failures):

python3 tools/cohesix-py/examples/ci_evidence_pack.py --pack ./out/evidence/live

SIEM export (normalized NDJSON for Splunk/Elastic ingestion):

python3 tools/cohesix-py/examples/siem_export_ndjson.py --pack ./out/evidence/live \
  --out ./out/evidence/live/siem.ndjson

Notes

swarmui

Purpose

Desktop UI (Tauri) that renders the hive view and reuses cohsh-core semantics. It does not add new verbs or protocols.

Location

Usage

./bin/swarmui
SWARMUI_TRANSPORT=rest SWARMUI_REST_URL=http://127.0.0.1:8080 \
  SWARMUI_REST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" ./bin/swarmui
SWARMUI_TRANSPORT=9p SWARMUI_9P_HOST=127.0.0.1 SWARMUI_9P_PORT=31337 ./bin/swarmui
./bin/swarmui --replay /path/to/demo.hive.cbor
./bin/swarmui --replay-trace /path/to/trace_v0.trace
./bin/swarmui --mint-ticket --role worker-heartbeat --ticket-subject worker-1

Notes

cas-tool

Purpose

Package and upload CAS bundles over the TCP console or REST gateway using the same append-only flows as cohsh.

Location

Usage

Usage: cas-tool <COMMAND>

Commands:
  pack    Package a payload into CAS chunks and manifest
  upload  Upload a CAS bundle via the TCP console or REST gateway
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

./bin/cas-tool pack --epoch 1 --input path/to/payload --out-dir out/cas/1
./bin/cas-tool upload --bundle out/cas/1 --host 127.0.0.1 --port 31337 \
  --auth-token "$COH_AUTH_TOKEN" --ticket "$QUEEN_TICKET"
./bin/cas-tool upload --bundle out/cas/1 --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN"

Notes

gpu-bridge-host

Purpose

Discover GPUs on the host (NVML with CUDA fallback, or mock) and emit the /gpu namespace snapshot consumed by NineDoor.

Location

Usage

      --mock                     Use the deterministic mock backend instead of NVML
      --registry <DIR>           Host registry root containing available model manifests
      --list                     Print GPU namespace JSON to stdout
      --publish                  Publish the GPU namespace into /gpu/bridge/ctl on a live Queen
      --interval-ms <MS>         Interval in milliseconds between publish snapshots (requires --publish)
      --tcp-host <TCP_HOST>      TCP host for the live console publish mode [default: 127.0.0.1]
      --tcp-port <TCP_PORT>      TCP port for the live console publish mode [default: 31337]
      --auth-token <AUTH_TOKEN>  Authentication token for the live console publish mode
      --ticket <TICKET>          Optional ticket payload when attaching to the console
      --rest-url <URL>           REST gateway base URL for hive-gateway publish mode
      --rest-auth-token <TOKEN>  Request auth token for REST mutating routes
  -h, --help                     Print help
  -V, --version                  Print version

./bin/gpu-bridge-host --mock --list
./bin/gpu-bridge-host --list
./bin/gpu-bridge-host --publish --tcp-host 127.0.0.1 --tcp-port 31337 --auth-token "$COH_AUTH_TOKEN"
./bin/gpu-bridge-host --publish --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN"
./bin/gpu-bridge-host --publish --interval-ms 1000 --registry demo/peft_registry

Notes

host-sidecar-bridge

Purpose

Publish host-side providers into /host (systemd, k8s, docker, nvidia, jetson, net) via Secure9P for policy/CI validation and live telemetry snapshots.

Location

Usage

      --mock                     Enable deterministic mock mode (in-process NineDoor)
      --mount <MOUNT>            Mount point for the /host namespace [default: /host]
      --provider <PROVIDER>      Provider to publish (repeat for multiple) [possible values: systemd, k8s, docker, nvidia, jetson, net]
      --policy <FILE>            Path to the manifest-derived cohsh policy TOML (polling defaults)
      --watch                    Run continuously, polling providers on their configured interval
      --rest-url <URL>           REST gateway base URL for hive-gateway publish mode
      --rest-auth-token <TOKEN>  Request auth token for REST mutating routes
      --tcp-host <TCP_HOST>      TCP host for a live NineDoor console (non-mock) [default: 127.0.0.1]
      --tcp-port <TCP_PORT>      TCP port for a live NineDoor console (non-mock) [default: 31337]
      --auth-token <AUTH_TOKEN>  Authentication token for the TCP console (non-mock) [default: changeme]
  -h, --help                     Print help
  -V, --version                  Print version

./bin/host-sidecar-bridge --mock --mount /host --provider systemd --provider k8s --provider docker --provider nvidia
./bin/host-sidecar-bridge --tcp-host 127.0.0.1 --tcp-port 31337 --auth-token "$COH_AUTH_TOKEN"
./bin/host-sidecar-bridge --tcp-host 127.0.0.1 --tcp-port 31337 --auth-token "$COH_AUTH_TOKEN" --watch
./bin/host-sidecar-bridge --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --watch
./bin/host-sidecar-bridge --tcp-host 127.0.0.1 --tcp-port 31337 --auth-token "$COH_AUTH_TOKEN" \
  --provider systemd --provider k8s --provider docker --provider nvidia --watch

Notes

host-ticket-agent

Purpose

Host-only ticket executor that tails /host/tickets/spec, applies allowlisted actions, and appends deterministic receipts to /host/tickets/status or /host/tickets/deadletter.

Location

Usage

      --manifest <FILE>          Path to out/manifests/root_task_resolved.json
      --cursor <FILE>            Cursor state file for deterministic resume
      --mount <PATH>             Optional host mount override (default from manifest)
      --poll-ms <POLL_MS>        Poll interval in milliseconds [default: 1000]
      --relay                    Enable federated relay forwarding from /host/tickets/spec
      --relay-wal <FILE>         Relay WAL state file [default: out/host-ticket-agent/relay-wal.json]
      --run-once                 Process one pass and exit
      --mock                     Use deterministic in-process NineDoor
      --rest-url <URL>           REST gateway base URL
      --rest-auth-token <TOKEN>  Request auth token for REST writes
      --tcp-host <TCP_HOST>      TCP host [default: 127.0.0.1]
      --tcp-port <TCP_PORT>      TCP port [default: 31337]
      --auth-token <AUTH_TOKEN>  TCP auth token [default: changeme]
      --policy <FILE>            Optional coh policy TOML for PEFT defaults
      --registry-root <DIR>      Optional PEFT registry root override

./bin/host-ticket-agent --mock --run-once
./bin/host-ticket-agent --tcp-host 127.0.0.1 --tcp-port 31337 --auth-token "$COH_AUTH_TOKEN"
./bin/host-ticket-agent --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN"
./bin/host-ticket-agent --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  --relay --relay-wal out/host-ticket-agent/relay-wal.json

Notes

hive-gateway

Purpose

Host-only REST gateway that maps 1:1 to Cohesix console/file semantics (LS, CAT, ECHO). It does not add new verbs or control-plane behavior.

Location

Usage

      --bind <BIND>              Bind address for the REST gateway [default: 127.0.0.1:8080]
      --tcp-host <TCP_HOST>      TCP console host [default: 127.0.0.1]
      --tcp-port <TCP_PORT>      TCP console port [default: 31337]
      --auth-token <AUTH_TOKEN>  TCP console auth token (required in non-mock mode)
      --request-auth-token <REQUEST_AUTH_TOKEN>
                                Per-request REST auth token for mutating paths
      --allow-non-loopback-bind  Allow non-loopback bind addresses
      --role <ROLE>              Role to attach with (queen by default) [default: queen]
      --ticket <TICKET>          Optional capability ticket payload
      --pool-control-sessions <POOL_CONTROL_SESSIONS>
                                Override pooled control session capacity
      --pool-telemetry-sessions <POOL_TELEMETRY_SESSIONS>
                                Override pooled telemetry session capacity
      --mock                     Use the in-process mock NineDoor backend
  -h, --help                     Print help
  -V, --version                  Print version

./bin/hive-gateway --bind 127.0.0.1:8080 --auth-token "$COH_AUTH_TOKEN" \
  --request-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN"
COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway

curl -sS http://127.0.0.1:8080/v1/meta/bounds | jq .

Notes

Remote access pattern (SSH tunnel)

# On the GPU host (runs the gateway and holds the console).
COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway

# From your Mac, tunnel the gateway.
ssh -L 8080:127.0.0.1:8080 <gpu-host>

# Use REST clients locally.
SWARMUI_TRANSPORT=rest SWARMUI_REST_URL=http://127.0.0.1:8080 \
  SWARMUI_REST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" ./bin/swarmui
./bin/cohsh --transport rest --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --role queen

Using Host Tools Together

These workflows show how the tools complement each other without introducing new semantics. Each example uses the shipped commands only.

In the source tree, use scripts/qemu-run.sh instead of ./qemu/run.sh and replace ./bin paths with out/cohesix/host-tools.

1) Live Hive operator flow (Queen + UI + CLI)

Goal: show a live Queen with SwarmUI as the trustable lens, and cohsh as the action surface. Why this matters: proves the UI is observational only while the authoritative control plane remains the CLI and file-shaped paths.

./qemu/run.sh
./bin/swarmui

Quit SwarmUI before switching to cohsh:

./bin/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337

In cohsh:

attach queen
cat /proc/lifecycle/state
spawn heartbeat ticks=100

For multiplexed mode, keep hive-gateway attached to the console and run SWARMUI_TRANSPORT=rest with host tools using --rest-url so the console remains single-client. Quit cohsh, relaunch SwarmUI to observe the worker activity.

1b) Live Hive operator flow (gateway multiplexed)

Goal: run SwarmUI, cohsh, and host publishers concurrently through hive-gateway. Why this matters: demonstrates the supported multi-tool pattern in 0.9.0-beta.

./qemu/run.sh
COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway
./bin/gpu-bridge-host --publish --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --interval-ms 1000
./bin/host-sidecar-bridge --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --watch
SWARMUI_TRANSPORT=rest SWARMUI_REST_URL=http://127.0.0.1:8080 \
  SWARMUI_REST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" ./bin/swarmui
./bin/cohsh --transport rest --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --role queen

In cohsh:

attach queen
ls /gpu
ls /host

2) GPU surface + lease + breadcrumbs (host tools only)

Goal: prove the GPU namespace and bounded runtime breadcrumbs. Why this matters: shows GPU access is host-side and lease-gated, and that runtime actions are logged in /gpu/<id>/status.

./qemu/run.sh
./bin/gpu-bridge-host --list   # NVML/CUDA discovery on Linux
./bin/coh --host 127.0.0.1 --port 31337 gpu list
./bin/coh --host 127.0.0.1 --port 31337 gpu lease --gpu GPU-0 --mem-mb 4096 --streams 1 --ttl-s 60
./bin/coh --host 127.0.0.1 --port 31337 run --gpu GPU-0 -- echo ok

Note: if /gpu is empty, confirm the host GPU bridge integration is running and the snapshot shows devices.

3) Telemetry ingress + pull (operator + host bridge)

Goal: write telemetry to the Queen’s ingest surface and pull the bundles. Why this matters: demonstrates the append-only ingest surface and bounded export without introducing any new protocol.

./qemu/run.sh
./bin/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role queen \
  telemetry push demo/telemetry/demo.txt --device device-1
./bin/coh --host 127.0.0.1 --port 31337 telemetry pull --out ./out/telemetry/pull

4) PEFT lifecycle loop (export -> import -> activate -> rollback)

Goal: show auditable adapter handling with host tooling. Why this matters: proves adapters are managed as auditable artifacts with reversible activation.

./qemu/run.sh
./bin/gpu-bridge-host --mock --list
./bin/coh peft export --mock --job job_0001 --out demo/peft_export
./bin/coh --host 127.0.0.1 --port 31337 peft import --model demo-model \
  --from demo/peft_adapter --job job_0001 --export demo/peft_export --registry demo/peft_registry --publish
./bin/coh --host 127.0.0.1 --port 31337 peft activate --model demo-model --registry demo/peft_registry
./bin/coh --host 127.0.0.1 --port 31337 peft rollback --registry demo/peft_registry

5) Host sidecar publishing + policy validation

Goal: project host providers into /host and observe via CLI/UI. Why this matters: validates /host gating, queen-only controls, and audit logging with either mock or live snapshots.

./qemu/run.sh
./bin/host-sidecar-bridge --tcp-host 127.0.0.1 --tcp-port 31337 --auth-token "$COH_AUTH_TOKEN" \
  --provider systemd --provider k8s --provider docker --provider nvidia --watch
./bin/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337

In cohsh:

attach queen
ls /host

Quit cohsh, open SwarmUI to observe the live hive alongside host provider activity.

Note: if live provider commands (systemctl/kubectl/docker/nvidia-smi) are unavailable, status lines report state=unknown reason=<...>.

6) CAS update bundle demo (pack + upload + verify)

Goal: show content-addressed update flows with deterministic upload paths. Why this matters: proves update artifacts are signed, chunked, and uploaded through the same audited console path.

./qemu/run.sh
QUEEN_TICKET=$(./bin/cohsh --mint-ticket --role queen)
./bin/cas-tool pack --epoch 1 --input demo/telemetry/demo.txt --out-dir out/cas/1 \
  --signing-key resources/fixtures/cas_signing_key.hex
./bin/cas-tool upload --bundle out/cas/1 --host 127.0.0.1 --port 31337 \
  --auth-token "$COH_AUTH_TOKEN" --ticket "$QUEEN_TICKET"

In cohsh (optional):

attach queen
ls /updates

7) Hive gateway monitoring + API control

Goal: observe host telemetry (NVML/CUDA-backed GPU snapshots plus systemd, k8s, and docker) over HTTP and submit control actions through the REST projection. Why this matters: demonstrates that monitoring and control stay aligned with the same file and console semantics.

Real-world flow (continuous publish + REST read):

./qemu/run.sh

# Start the REST gateway (sole console client).
COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway

# Publish continuous snapshots through the gateway.
./bin/gpu-bridge-host --publish --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" --interval-ms 1000
./bin/host-sidecar-bridge --rest-url http://127.0.0.1:8080 --watch \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  --provider systemd --provider k8s --provider docker --provider nvidia

In another terminal:

# List top-level providers under /host.
curl -sS 'http://127.0.0.1:8080/v1/fs/ls?path=/host' | jq .

# Read systemd unit status (example unit).
curl -sS 'http://127.0.0.1:8080/v1/fs/cat?path=/host/systemd/cohesix-agent.service/status&max_bytes=256' | jq .

# Read a Kubernetes node status (example node id).
curl -sS 'http://127.0.0.1:8080/v1/fs/cat?path=/host/k8s/node/node-1/status&max_bytes=256' | jq .

# Read Docker and NVIDIA provider status.
curl -sS 'http://127.0.0.1:8080/v1/fs/cat?path=/host/docker/status&max_bytes=256' | jq .
curl -sS 'http://127.0.0.1:8080/v1/fs/cat?path=/host/nvidia/gpu/0/status&max_bytes=256' | jq .

# Read NVML/CUDA-backed GPU info published by gpu-bridge-host.
curl -sS 'http://127.0.0.1:8080/v1/fs/cat?path=/gpu/GPU-0/info&max_bytes=2048' | jq .

Real-world API control (lease + schedule + policy):

# Enqueue a GPU worker schedule entry.
curl -sS -X POST http://127.0.0.1:8080/v1/fs/echo \
  -H "Authorization: Bearer $HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/queen/schedule/ctl","line":"{\"id\":\"sched-42\",\"role\":\"worker-gpu\",\"priority\":3,\"ticks\":5,\"budget_ms\":120}"}'

# Grant and preempt a lease.
curl -sS -X POST http://127.0.0.1:8080/v1/fs/echo \
  -H "Authorization: Bearer $HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/queen/lease/ctl","line":"{\"op\":\"grant\",\"id\":\"lease-42\",\"subject\":\"queen\",\"resource\":\"gpu0\",\"ttl_s\":300,\"priority\":5}"}'
curl -sS -X POST http://127.0.0.1:8080/v1/fs/echo \
  -H "Authorization: Bearer $HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/queen/lease/ctl","line":"{\"op\":\"preempt\",\"id\":\"lease-42\",\"reason\":\"maintenance\"}"}'

# Apply and roll back a policy revision.
curl -sS -X POST http://127.0.0.1:8080/v1/fs/echo \
  -H "Authorization: Bearer $HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/policy/ctl","line":"{\"op\":\"apply\",\"id\":\"rev-2026-02-05\",\"sha256\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}"}'
curl -sS -X POST http://127.0.0.1:8080/v1/fs/echo \
  -H "Authorization: Bearer $HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/policy/ctl","line":"{\"op\":\"rollback\",\"id\":\"rev-2026-02-05\"}"}'

Notes:

8) Multi-Hive federation relay (source + target)

Goal: queue a host ticket on one hive and execute it on a federated peer with deterministic dedupe and receipts. Why this matters: validates manifest-gated relay (ecosystem.host.federation) without introducing new control-plane verbs.

Source hive (hive-mac, local gateway :8080):

./qemu/run.sh
COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway
./bin/host-ticket-agent --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  --relay --relay-wal out/host-ticket-agent/relay-wal.json

Target hive (hive-jetson, run directly on Jetson):

./qemu/run.sh
COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway
./bin/host-ticket-agent --rest-url http://127.0.0.1:8080 \
  --rest-auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN"

Submit one federated ticket on source:

curl -sS -X POST http://127.0.0.1:8080/v1/fs/echo \
  -H "Authorization: Bearer ${HIVE_GATEWAY_REQUEST_AUTH_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/host/tickets/spec","line":"{\"schema\":\"host-ticket/v1\",\"id\":\"fed-systemd-1\",\"idempotency_key\":\"fed-20260221-1\",\"action\":\"systemd.restart\",\"target\":\"/host/systemd/cohesix-agent.service/restart\",\"source_hive\":\"hive-mac\",\"target_hive\":\"hive-jetson\"}"}'

Create a read-only tunnel from source for verification:

ssh -L 8081:127.0.0.1:8080 <jetson-host>

Verify receipt fields on target via the tunnel:

curl -sS 'http://127.0.0.1:8081/v1/fs/cat?path=/host/tickets/status&max_bytes=4096' | jq .

Expected: status lines include source_hive, target_hive, and relay_hop; repeated spec submission with the same federated key deduplicates.

Policy & Dependency Diagrams

These diagrams summarize the policy gating and host-tool interdependencies that most often surprise new users.

Figure 1: Policy-gated control writes (/queen/ctl)

flowchart TD
  A["coh / cohsh / hive-gateway"] --> B["TCP console (single client)"]
  B --> C["NineDoor Secure9P"]
  C --> D{"Policy gating enabled?<br/>/policy/rules present"}
  D -- "No" --> E["Write /queen/ctl accepted"]
  D -- "Yes" --> F{"Approval queued?<br/>/actions/queue"}
  F -- "No" --> G["ERR ECHO reason=policy (EPERM)"]
  F -- "Yes" --> H["Write accepted<br/>approval consumed (audit if enabled)"]
  H --> I["Queen applies action<br/>(spawn/lease/export/etc.)"]

Figure 2: Policy control apply/rollback (/policy/ctl)

flowchart TD
  A["cohsh / hive-gateway / REST client"] --> B["ECHO /policy/ctl (apply/rollback)"]
  B --> C["Policy control validation<br/>(bounds, schema, hash)"]
  C --> D["Policy state updated"]
  D --> E["/policy/preflight/* reflects queued/consumed approvals"]
  D --> F["/proc/pressure/policy exposes pressure"]
  D --> G["/policy/rules remains manifest-derived"]

Figure 3: GPU + host visibility dependencies (live vs mock)

flowchart TD
  subgraph Live["Live (QEMU + TCP console)"]
    L1["QEMU running (TCP console)"] --> L2["gpu-bridge-host --publish"]
    L2 --> L3["/gpu namespace populated"]
    L3 --> L4["coh gpu list/lease"]
    L4 --> L5["coh run requires active lease<br/>/gpu/<id>/lease"]
    L1 --> L6["host-sidecar-bridge --watch/--provider ..."]
    L6 --> L7["/host namespace populated"]
    L7 --> L8["cohsh / coh / hive-gateway reads /host/*"]
    L7 --> L9["host-ticket-agent tails /host/tickets/spec"]
    L9 --> L10["/host/tickets/status|deadletter receipts"]
  end
  subgraph Mock["Mock (in-process backend)"]
    M1["coh --mock / cohsh --transport mock"] --> M2["No QEMU or TCP console used"]
    M2 --> M3["gpu-bridge-host --mock --list<br/>drives mock GPU data"]
  end

Glossary