Metadata-Version: 2.4
Name: capos
Version: 0.1.4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Development Status :: 2 - Pre-Alpha
Summary: Host-side Python bindings for capOS, the capability operating system: a remote-session client over the CapSet forwarding protocol (https://cap-os.dev).
Keywords: capos,capability,operating-system,sdk
Author: Andrew Grigorev
License: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://cap-os.dev
Project-URL: Repository, https://github.com/ei-grad/capos

# capos (Python)

Host-side Python bindings for [capOS](https://cap-os.dev), 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

```bash
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`](examples/hello_live.py) documents how to boot a VM
that forwards host `127.0.0.1:2327` to it — then:

```console
$ 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:

![capos live hello-world](https://cap-os.dev/assets/casts/hello-python.svg)

## Using the client

```python
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/`](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.

