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.
| Python | JavaScript | |
|---|---|---|
| Install | pip install capos (PyPI) | npm install capos (npm) |
| Published surface | 0.1.4: login, session metadata, MOTD, and CapSet listing | 0.1.2: login, session metadata, MOTD, and CapSet listing |
| Source-tree addition | Unreleased Client.system_info() | Unreleased Client.systemInfo() |
| Transport | remote-session CapSet gateway (capnp protocol, guest port 2327) | web bridge HTTP API (the same routes the browser UI uses, guest port 8080) |
| Trust profile | capability forwarding — bounded by session login, broker profiles, and the session’s CapSet | data bridge — DTOs only, never an invokable capability |
| Source | capos-python/ (pyo3 binding of tools/remote-session-client) | capos-js/ (pure TypeScript/ESM, zero runtime deps) |
Hello, capOS from the JavaScript source tree
A real run against a live capOS kernel, with responses served by the in-guest
web UI over the userspace network stack. The checkout’s example now calls the
unreleased systemInfo() API, so build and run it from capos-js/:
npm ci
npm run build
node examples/hello.mjs --base-url http://127.0.0.1:34567 \
--account operator --password capos
The example logs in, then reads build identity, the session view, the redacted
MOTD, and the CapSet listing — all data served by the guest. npm 0.1.2 does
not contain systemInfo(); its recording covers the other live calls.
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 uses the released client surface to say hello:
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 from the Python source tree
The Python binding speaks the CapSet gateway protocol itself. The current
checkout’s example calls the unreleased system_info() API; the
run-remote-session-capset-interop gate builds that extension from source and
drives it against the remote-session gateway on port 2327:
make run-remote-session-capset-interop
The proof logs in over the capability protocol, reads the kernel build identity,
and checks the exact hello line. PyPI 0.1.4 does not contain system_info();
the published recording covers session, MOTD, and CapSet reads.
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), plus the source-built Python SDK’s exact kernel build-identity line, with the retired kernel TCP listener verifiably absent.make run-cloud-prod-remote-session-web-ui-l4— the self-served Web UI and its/apiroutes 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.