# 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)) |
| 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 (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](assets/casts/hello-node.svg)

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