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 Python Support (0.9.0-beta As-Built)

The cohesix Python client is a thin, non-authoritative wrapper over existing Cohesix console and filesystem semantics. It does not introduce new control-plane behavior; it mirrors the same verbs, bounds, and error rules enforced by cohsh and Secure9P.

This document reflects the 0.9.0-beta release line (Milestones 25c/25e/25g plus TCP/auth hardening).

Milestone 25e adds offline integration kit examples that validate and export evidence packs for CI and SIEM ingestion.

Concise real-world examples

These are intentionally short, copy/paste commands that map to production activities.

1) Run a release-control dry run for a large Mac fleet

cohesix-playbook --playbook mac-release-factory --dry-run --mock

Outcome: validates scheduler/approval orchestration and emits a report/audit pair you can inspect before live rollout.

2) Drive Jetson traffic safety orchestration through the REST gateway

cohesix-playbook \
  --playbook jetson-traffic-safety \
  --auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" \
  --rest-url http://127.0.0.1:8080

Outcome: executes bounded control writes (schedule + lease) and captures auditable results under out/examples/playbooks/.

3) Run a closed-loop mixed-fleet AI factory plan

cohesix-playbook --playbook mixed-closed-loop-ai-factory --dry-run --mock

Outcome: validates Mac-train + Jetson-infer coordination logic without touching live control files.

4) Programmatically enqueue schedule + lease controls from Python

from cohesix import CohesixOrchestrator, ScheduleRequest, LeaseRequest

with CohesixOrchestrator.from_env() as orch:
    orch.enqueue_schedule([
        ScheduleRequest("sched-edge-1", "worker-gpu", priority=6, ticks=6, budget_ms=180)
    ])
    orch.apply_leases([
        LeaseRequest(
            op="grant",
            lease_id="lease-edge-1",
            subject="queen",
            resource="gpu0",
            ttl_s=300,
            priority=6,
        )
    ])

Outcome: integrates directly into existing Python jobs without inventing new control semantics.

5) Pull host integration telemetry snapshot and ship it through the playbook flow

from cohesix.integrations import collect_host_snapshot, snapshot_to_ndjson

snapshot = collect_host_snapshot(
    systemd_services=["cohesix-agent.service"],
    include_docker=True,
    include_k8s=True,
    include_nvml=True,
    include_peft=True,
)
print(snapshot_to_ndjson(snapshot))

Outcome: gives one normalized snapshot envelope for service health, containers, pods, GPU state, and PEFT runtime readiness.

Scope and guarantees

Where it lives

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

Backends

Orchestration APIs (Milestone 25c / 25g)

Ticket translation example:

from cohesix import CohesixOrchestrator, K8sRbacIntent

with CohesixOrchestrator.from_env() as orch:
    orch.enqueue_k8s_rbac_tickets(
        [
            K8sRbacIntent(
                intent_id="intent-node-1-cordon",
                subject="ops-user",
                namespace="edge-a",
                node="node-1",
                verb="cordon",
            )
        ]
    )

Host integration adapters (Milestone 25c)

Backend matrix

| Backend | Requires | Best for | Notes | | — | — | — | — | | TcpBackend | QEMU + TCP console | Direct console automation | Single-client console. Do not run cohsh, swarmui, or hive-gateway concurrently. | | RestBackend | QEMU + hive-gateway | HTTP clients and OpenAPI tooling | Gateway itself holds the console. | | FilesystemBackend | coh mount (FUSE) | Air-gapped or file-shaped integrations | Mount is long-running and stays in the foreground. | | MockBackend | None | CI, demos, first-run validation | No VM involved; uses an in-process backend. |

Choosing a backend

Operational interdependencies (read first for live runs)

Install

Source tree (editable):

python3 -m pip install -e tools/cohesix-py

Source tree (editable + integration extras):

python3 -m pip install -e 'tools/cohesix-py[integrations]'

Source tree (editable + PEFT extras):

python3 -m pip install -e 'tools/cohesix-py[ml]'

Release bundle:

python3 -m pip install ./python/cohesix-py

Per-host .venv setup (macOS/Linux)

Create an isolated environment in the repo root before running tests/examples:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e 'tools/cohesix-py[dev]'

If you need host integration and ML adapters:

python -m pip install -e 'tools/cohesix-py[dev,integrations,ml]'

Quick verification:

.venv/bin/python -m pytest tools/cohesix-py/tests/test_auth.py -q

Notes:

Playbook CLI

The package now ships cohesix-playbook for one-command orchestration templates:

cohesix-playbook --list
cohesix-playbook --playbook mixed-closed-loop-ai-factory --dry-run --mock
cohesix-playbook --playbook jetson-traffic-safety --tcp-host 127.0.0.1 --tcp-port 31337

Reports are written under out/examples/playbooks/<playbook-id>/.

Common example flags

All bundled examples share the same backend arguments:

Quickstart (mock mode)

--mock runs the client against a deterministic in-memory backend. It is fast, requires no QEMU, and is ideal for CI and first-run demos.

python3 tools/cohesix-py/examples/lease_run.py --mock
python3 tools/cohesix-py/examples/peft_roundtrip.py --mock
python3 tools/cohesix-py/examples/telemetry_write_pull.py --mock

Artifacts land under out/examples/ unless --out is provided.

Evidence pack integration kits (Milestone 25e)

These examples operate on an evidence pack directory produced by coh evidence pack. Once the pack exists, they run offline (no VM or network required).

cargo run -p coh -- --mock evidence pack --out out/evidence/mock
python3 tools/cohesix-py/examples/ci_evidence_pack.py --pack out/evidence/mock \
  --out out/evidence/mock/ci_summary.json
python3 tools/cohesix-py/examples/siem_export_ndjson.py --pack out/evidence/mock \
  --out out/evidence/mock/siem.ndjson

Live connection requirements (no --mock)

To run against a live Queen, you need:

If policy gating is enabled (see /policy/rules), queue approvals before any control writes to /queen/ctl:

./bin/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role queen <<'COH'
echo {"id":"approve-1","target":"/queen/ctl","decision":"approve"} > /actions/queue
COH

Live TCP backend (Queen running)

1) Boot the VM (Mac host, source tree):

scripts/qemu-run.sh

2) Run a Python example against the TCP console:

python3 tools/cohesix-py/examples/lease_run.py \
  --tcp-host 127.0.0.1 --tcp-port 31337

If token resolution is ambiguous, pass --auth-token explicitly.

Note: the TCP console is single-client. Do not attach cohsh, swarmui, or hive-gateway while using the TCP backend.

REST backend (hive-gateway)

1) Start the REST gateway on the host:

COH_TCP_HOST=127.0.0.1 COH_TCP_PORT=31337 COH_AUTH_TOKEN="$COH_AUTH_TOKEN" \
  HIVE_GATEWAY_REQUEST_AUTH_TOKEN=replace-with-real-token \
  COH_ROLE=queen HIVE_GATEWAY_BIND=127.0.0.1:8080 \
  ./bin/hive-gateway

2) Point a Python example at the gateway:

python3 tools/cohesix-py/examples/lease_run.py \
  --rest http://127.0.0.1:8080 \
  --auth-token "$HIVE_GATEWAY_REQUEST_AUTH_TOKEN"

3) (Optional) Verify bounds:

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

Note: the gateway is itself a console client; avoid attaching cohsh or swarmui at the same time. RestBackend retries transient failures by default (429/500/502/503/504 and transient connection errors), using exponential backoff with a Retry-After floor when present.

Filesystem backend (Secure9P mount)

1) Mount the namespace on the host (requires coh mount):

./bin/coh --host 127.0.0.1 --port 31337 mount --at /tmp/coh-mount

2) Use the filesystem backend against that mount:

python3 tools/cohesix-py/examples/lease_run.py --mount-root /tmp/coh-mount

Notes:

Bounds and defaults

The client enforces manifest-derived defaults emitted by coh-rtc and embedded in tools/cohesix-py/cohesix/generated.py. These include:

manifest_sha256 from generated defaults is exported in receipts/evidence and can be cross-checked with REST /v1/meta/bounds. Drift prevention is enforced in build/CI by regenerating artifacts from manifest IR (coh-rtc), rather than runtime manifest reloading.

Connectivity checklist (live)

Tests (parity)

The parity tests verify the Python client matches cohsh behavior byte-for-byte:

python3 -m pytest -k cohesix_parity tools/cohesix-py/tests/test_parity.py

Orchestration/integration/playbook tests:

python3 -m pytest tools/cohesix-py/tests/test_orchestration.py -q
python3 -m pytest tools/cohesix-py/tests/test_integrations.py -q
python3 -m pytest tools/cohesix-py/tests/test_playbooks.py -q

Troubleshooting

Real-world use-case playbooks (1k+ workers)

The built-in playbook catalog covers all high-impact use cases defined for Milestone 25d discussions:

Dry-run any playbook with no control writes:

cohesix-playbook --playbook mac-release-factory --dry-run --mock

Run through the example wrapper:

python3 tools/cohesix-py/examples/use_case_playbook.py --playbook mixed-logistics-digital-twin --dry-run --mock

Design alignment

This client exists to lower adoption friction while preserving Cohesix’s core guarantees: