# 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](capability-model.md#remote-clients-capability-forwarding-vs-the-data-bridge)
for the model.

| | Python | JavaScript |
|---|---|---|
| Install | `pip install capos` ([PyPI](https://pypi.org/project/capos/)) | `npm install capos` ([npm](https://www.npmjs.com/package/capos)) |
| 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/`:

![capos npm hello-world recording](assets/casts/hello-node.svg)

```bash
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 npm hello-world against capOS on Google Compute Engine](assets/casts/hello-node-gce.svg)

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:

![capos Python hello-world recording](assets/casts/hello-python.svg)

```bash
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 `/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](proposals/remote-session-capset-client-proposal.md).