kosa8 for Python

Python client for kosa8: microVM sandboxes for AI agents, with checkpoint, rewind, fork and explore. The counterpart of @kosa8/sdk, method for method.

No dependencies. It talks to the local kosa8 daemon over its unix socket, or to a remote kosa8 worker.

pip install kosa8

Quickstart

from kosa8 import Kosa8Client

k = Kosa8Client()
k.create_sandbox(name="demo", egress="deny")   # a microVM with its own kernel, no network
sb = k.sandbox("demo")

sb.pull("alpine:latest")
print(sb.run("alpine:latest", ["sh", "-c", "echo hello"]).stdout)

sb.checkpoint(label="before the risky bit")    # memory, processes and disk
sb.run("alpine:latest", ["sh", "-c", "rm -rf /data"])
sb.rewind()                                    # back, processes resumed

forks = sb.fork(4)                             # four live copies
sb.delete()

What's in it

k.sandbox(id) returns a handle with the same methods bound to one sandbox.

Checkpoints share the CLI's store (~/.kosa8/checkpoints.json, under the same flock), so kosa8 rewind sees checkpoints taken here and the other way round.

Connecting

Errors

Every daemon error is raised as a typed exception carrying the daemon's own message and remediation: Kosa8BadRequestError (400), Kosa8AuthError (401), Kosa8PolicyError (403), Kosa8ApprovalRequiredError (403 needing a signed approval: repeat the call with approval=<id>), Kosa8NotFoundError (404), Kosa8ConflictError (409), Kosa8UnsupportedError (501), Kosa8ConnectionError, Kosa8StreamError (output kept), Kosa8TimeoutError.

Tests

PYTHONPATH=src:tests python3 -m unittest discover -s tests

License

MIT