Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Host-Side SDKs

Two packages, both named capos, let host programs talk to a running capOS instance. They deliberately speak different transports with different trust profiles — see Remote Clients: Capability Forwarding vs the Data Bridge for the model.

PythonJavaScript
Installpip install capos (PyPI)npm install capos (npm)
Transportremote-session CapSet gateway (capnp protocol, guest port 2327)web bridge HTTP API (the same routes the browser UI uses, guest port 8080)
Trust profilecapability forwarding — bounded by session login, broker profiles, and the session’s CapSetdata bridge — DTOs only, never an invokable capability
Sourcecapos-python/ (pyo3 binding of tools/remote-session-client)capos-js/ (pure TypeScript/ESM, zero runtime deps)

Hello, capOS (JavaScript)

A real run against a live capOS kernel — install from the registry, launch, and responses served by the in-guest web UI over the userspace network stack:

capos npm hello-world recording

npm install capos
node examples/hello.mjs --base-url http://127.0.0.1:34567 \
  --account operator --password capos

The example logs in, then reads the session view, the redacted MOTD, and the CapSet listing — all data served by the guest.

The same hello, against capOS on a cloud VM

The identical client flow, this time against capOS booted on a real Google Compute Engine instance. The instance has no public address; it is reached only over a private, VPC-internal path, never a public endpoint. The recording shows the live cloud proof first — the instance identity (e2-small, its internal IP, RUNNING) and the guest’s serial boot markers (kernel start, DHCP lease on the virtio NIC, the userspace network stack’s listener, and the web UI serving) — then installs the published client and says hello:

capos npm hello-world against capOS on Google Compute Engine

capOS self-serves the web UI and the same /api routes over its userspace network stack on the instance’s virtio NIC; the login, session, redacted MOTD, and CapSet responses are all served by the guest.

Hello, capOS (Python)

The Python binding speaks the CapSet gateway protocol itself. Its live hello-world recording lands here together with the capos 0.1.4 release.

The proofs behind the endpoints

Both SDK endpoints are proven live by QEMU gates in this repository:

  • make run-remote-session-capset-interop — the CapSet gateway served on port 2327 over the userspace network stack (login, CapSet round-trip, missing-cap and wrong-interface denials, stale-after-logout), with the retired kernel TCP listener verifiably absent.
  • make run-cloud-prod-remote-session-web-ui-l4 — the self-served Web UI and its /api routes over the userspace smoltcp stack, driven end-to-end by a browser-level harness.

The boot manifests behind these gates are system-remote-session-capset-interop.cue and system-cloud-prod-remote-session-web-ui-l4.cue; the client protocol design is recorded in the Remote Session CapSet Client proposal.