Metadata-Version: 2.5
Name: cvisor
Version: 0.2.0
Summary: In-process Linux sandbox — Python SDK (ctypes FFI over libcvisor)
Project-URL: Homepage, https://github.com/tsirysndr/cVisor
Project-URL: Repository, https://github.com/tsirysndr/cVisor
Author: butter.dev
License: MIT
Keywords: isolation,linux,sandbox,seccomp
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: console
Requires-Dist: ipython>=8; extra == 'console'
Description-Content-Type: text/markdown

# 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:

```bash
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
```

```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)

```bash
uv add cvisor
```

## Usage

```python
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:

```python
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):

```python
sb.set_allow_network(False)  # deny outbound networking
```

## Interactive console

Launch an IPython REPL with a live sandbox preloaded:

```bash
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/`:

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

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