capos (Python)

Host-side Python bindings for capOS, a research capability operating system where every resource is a typed Cap'n Proto capability.

This package is the working base for the host-side capOS SDK: it binds capOS's in-repo host remote-session client, which speaks the CapSet forwarding protocol that a running capOS exposes over its userspace network stack. That protocol is the concrete shape of the capos Rust crate's reserved remote transport, surfaced here in Python. Today it covers connecting, authenticating, listing the forwarded CapSet, and reading session metadata; more of the typed capability surface follows.

Install

pip install capos

Prebuilt wheels target Linux x86_64, CPython 3.9+ (abi3). On other platforms pip falls back to the source distribution, which builds the Cap'n Proto schema and therefore needs the pinned Cap'n Proto compiler on the build host.

Quickstart against a live capOS

The hello-world is a real conversation with a running kernel, not a canned string. Bring up a capOS instance that serves the remote-session gateway on guest port 2327 over its userspace network stack — the capOS repo proves this path with make run-remote-session-capset-interop, and examples/hello_live.py documents how to boot a VM that forwards host 127.0.0.1:2327 to it — then:

$ python examples/hello_live.py --host 127.0.0.1 --port 2327
connecting to capOS at 127.0.0.1:2327 ...
logged in as operator (profile operator)
capOS says:   _       __     __                             __
 | |     / /__  / /________  ____ ___  ___     / /_____
 | | /| / / _ \/ / ___/ __ \/ __ `__ \/ _ \   / __/ __ \
 | |/ |/ /  __/ / /__/ /_/ / / / / / /  __/  / /_/ /_/ /
 |__/|__/\___/_/\___/\____/_/ /_/ /_/\___/   \__/\____/
 ... (live welcome banner) ...
forwarded capabilities:
  - session (interface 0x80b87169c39aaf1c)
  - system_info (interface 0xfbbdc602980cb986)
  - adventure (interface 0xd5dc40d973e75b84)
  - chat (interface 0xd5dc40d973e75b84)

That output is captured from the published package talking to a real capOS VM:

Using the client

import capos

with capos.Client(host="127.0.0.1", port=2327) as client:
    client.login_password("operator", "capos", profile="operator")
    print(client.system_motd())
    for cap in client.list_capset():
        print(cap)

See examples/ for runnable scripts.

Changelog

• 0.1.4 — the hello-world is now a real live run against a capOS kernel (examples/hello_live.py); the static hello() placeholder was removed.

Links

• Project: https://cap-os.dev
• Source: https://github.com/ei-grad/capos

Licensed under either of MIT or Apache-2.0 at your option.