cVisor — Python SDK

A ctypes FFI wrapper over the libcvisor C ABI. Linux-only.

Quick try (Docker)

Drop into a Python REPL with cvisor installed, from any machine with Docker:

docker run -it --rm \
  --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
  ghcr.io/astral-sh/uv:python3.12-alpine \
  uv run --with cvisor python

>>> from cvisor import Sandbox
>>> sb = Sandbox()
>>> print(sb.run("echo hi; uname -n").stdout)
hi
cvisor

The --security-opt flags are required: cVisor installs its own seccomp filter, which Docker's default profiles block. An Alpine (musl) image is needed — the published wheels are musllinux-tagged.

Install (uv)

uv add cvisor

Usage

from cvisor import Sandbox

with Sandbox() as sb:
    out = sb.run("echo hello")
    print(out.stdout)   # "hello\n"
    print(out.stderr)   # ""

Sandbox.run(cmd) blocks until the sandboxed command exits and returns an Output with .stdout / .stderr (str), .stdout_bytes / .stderr_bytes, and .exit_code (int, shell convention: the command's status, or 128+signo if it was killed by a signal).

Timeouts

Sandbox.run(cmd, timeout_ms=...) SIGKILLs the guest after timeout_ms milliseconds; a timed-out run reports exit code 137:

out = sb.run("sleep 30", timeout_ms=300)
assert out.exit_code == 137

Network policy

Sandbox.set_allow_network(allow) controls outbound INET/INET6 networking (allowed by default):

sb.set_allow_network(False)  # deny outbound networking

Interactive console

Launch an IPython REPL with a live sandbox preloaded:

uv run --extra console cvisor   # or: python -m cvisor

cVisor interactive console
  sb          -> a Sandbox instance
  sh("cmd")   -> run a shell command in the sandbox, printing stdout/stderr
  Sandbox     -> create your own: Sandbox()

In [1]: sh("echo hello; uname -n")
hello
cvisor

Without the console extra (IPython) it falls back to the stdlib REPL.

Development

The SDK loads libcvisor.so. Build it from the repo root and point the SDK at it via the CVISOR_LIB environment variable, or let the package resolve a copy bundled under cvisor/_native/:

# from the repo root — builds libcvisor.so into cvisor/_native/
cargo xtask ffi

# run the tests with uv
cd sdks/python
uv run pytest