agvisor 0.1.0__py3-none-any.whl

agvisor/__init__.py

@@ -0,0 +1,5 @@
+"""Throwaway gVisor (runsc) sandboxes for coding agents, driven through the docker CLI."""
+from .limits import Limits
+from .sandbox import Sandbox, create_sandbox, list_sandboxes
+
+__all__ = ["Limits", "Sandbox", "create_sandbox", "list_sandboxes"]

agvisor/desktop.py

@@ -0,0 +1,41 @@
+"""GUI sandbox specifics: the GNOME-over-RDP image details and the token for gateway/gateway.js."""
+import base64
+import hmac
+import json
+import os
+import time
+
+GUI_IMAGE = "systemd-debian-gnome"  # built from the gVisor repo, see README
+GUI_USER = "gnome"
+GUI_HOME = f"/home/{GUI_USER}"  # persisted for named gui sandboxes (assumed home of GUI_USER: verify on the image)
+RDP_PORT = 3389
+
+
+def make_token(key: bytes, rdp_port: int, password: str, ttl: int = 300) -> str:
+    """Token for <agvisor-desktop> (needs `pip install agvisor[web]`). Valid for `ttl` seconds to *open* a session.
+
+    `key` is the 32-byte secret gateway/gateway.js also has. guacamole-lite can only decrypt AES-CBC, which does
+    not detect tampering: a client could flip IV bits and turn `{"expiration": 1...` into `9...`, making an
+    expired token last for centuries. So the token is encrypt-then-MAC: gateway.js checks the HMAC first.
+    """
+    from cryptography.hazmat.primitives import padding
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+    if len(key) != 32:
+        raise ValueError("key must be exactly 32 bytes (same as AGVISOR_KEY, hex-decoded)")
+    # one secret, two purposes: derive separate AES and HMAC keys (gateway.js derives them the same way)
+    enc_key, mac_key = (hmac.digest(key, label, "sha256") for label in (b"agvisor-enc", b"agvisor-mac"))
+
+    msg = json.dumps({
+        "expiration": int((time.time() + ttl) * 1000),  # checked by gateway.js
+        "connection": {"type": "rdp", "settings": {
+            "hostname": "127.0.0.1", "port": str(rdp_port),  # guacd runs on the docker host
+            "username": GUI_USER, "password": password,
+            "security": "any", "ignore-cert": True, "resize-method": "display-update"}},
+    }).encode()
+    iv, pad = os.urandom(16), padding.PKCS7(128).padder()
+    enc = Cipher(algorithms.AES(enc_key), modes.CBC(iv)).encryptor()
+    ct = enc.update(pad.update(msg) + pad.finalize()) + enc.finalize()
+    mac = hmac.HMAC(mac_key, iv + ct, "sha256").digest()  # over the exact bytes gateway.js will verify
+    b64 = lambda b: base64.b64encode(b).decode()  # guacamole-lite token format, plus `mac` (it ignores it)
+    return b64(json.dumps({"iv": b64(iv), "value": b64(ct), "mac": b64(mac)}).encode())

agvisor/limits.py

@@ -0,0 +1,32 @@
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Limits:
+    """Resource limits, enforced by gVisor/cgroups on the machine hosting the sandbox.
+
+    cpus    CPU cores, fractions allowed (0.5).
+    memory  Hard RAM cap in docker syntax ("512m", "4g"). Swap is disabled.
+    pids    Max processes/threads (stops fork bombs).
+    shm     /dev/shm size ("1g"). Default: docker's 64m, or 1g for gui.
+    disk    Hard cap on the root filesystem: everything the sandbox writes outside /workspace and /tmp ("5g").
+            A whole number + optional k/m/g/t (no decimals, no "gb"). It does NOT cover the /workspace volume of a
+            named sandbox (a plain host directory: unbounded), and /tmp is RAM, counted in `memory`.
+    """
+
+    cpus: float = 2.0
+    memory: str = "2g"
+    pids: int = 512
+    shm: str | None = None
+    disk: str = "5g"
+
+    def __post_init__(self):
+        # docker reads 0 as "unlimited": 0 must not silently remove a cap the caller asked for
+        mem = re.match(r"\d+(\.\d+)?", str(self.memory))
+        if not (self.cpus > 0 and self.pids > 0 and mem and float(mem.group()) > 0):
+            raise ValueError(f"cpus, memory and pids must be > 0, got {self}")
+        # runsc reads "0" as unlimited and rejects "1.5g"/"2gb" only when the container starts: fail here instead
+        disk = re.fullmatch(r"(\d+)[kmgtKMGT]?", str(self.disk))
+        if not (disk and int(disk[1]) > 0):
+            raise ValueError(f"disk must be a whole number > 0 plus optional k/m/g/t (e.g. '5g'), got {self.disk!r}")

agvisor/sandbox.py

@@ -0,0 +1,253 @@
+import codecs
+import collections
+import os
+import re
+import secrets
+import subprocess
+import uuid
+
+from .desktop import GUI_HOME, GUI_IMAGE, GUI_USER, RDP_PORT, make_token
+from .limits import Limits
+
+_KEEP = 100_000  # exec(on_output=) keeps only this many trailing characters: the rest already went to on_output
+_MARK = "/tmp/.agvisor_active"  # idle_ttl: every exec() touches it; PID 1 exits once it is older than idle_ttl
+# gui: RDP checks GNOME Remote Desktop's own credentials file, which the image bakes as gnome:gnome, NOT the unix
+# password. Run as GUI_USER with the file on stdin and its path as $1: store ours, wait for the desktop to boot
+# (up to 120 s), restart the RDP service (it reads the file only at startup), wait until it listens on 3389 (0D3D).
+_RDP_CREDS = f"{GUI_HOME}/.local/share/gnome-remote-desktop/credentials.ini"
+_RDP_SETUP = r"""set -e
+umask 077
+cat > "$1"
+export XDG_RUNTIME_DIR=/run/user/$(id -u)
+S=gnome-remote-desktop-headless.service
+wait_for() { n=0; until "$@"; do n=$((n+1)); [ $n -le 120 ] || { echo "desktop not ready after 120s: $*" >&2; exit 1; }; sleep 1; done; }
+wait_for systemctl --user is-active --quiet $S
+systemctl --user restart $S
+wait_for grep -qE ':0D3D [0-9A-F:]+ 0A' /proc/net/tcp /proc/net/tcp6
+"""
+_RUNC = ("runc", "io.containerd.runc.v2")  # --privileged (gui) is only simulated under gVisor, real under these
+
+
+class Sandbox:
+    """host=None -> local docker; host="ssh://user@vm" -> docker on a remote VM/server."""
+
+    def __init__(self, image=None, *, gui=False, limits=Limits(), network="bridge", lifetime=None,
+                 idle_ttl=None, name=None, host=None, runtime="runsc"):
+        self.gui, self.limits, self.network, self.lifetime, self.host = gui, limits, network, lifetime, host
+        self.idle_ttl, self.runtime = idle_ttl, runtime
+        # strict like `name`: it ends up in --runtime=. And never plain runc for a gui: it is run --privileged
+        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", runtime) or (gui and runtime in _RUNC):
+            raise ValueError(f"invalid runtime {runtime!r}: must be a gVisor (runsc) runtime registered in docker")
+        self.image = image or (GUI_IMAGE if gui else "ubuntu:24.04")
+        if self.image.startswith("-"):  # `docker run ... IMAGE` would parse it as a flag, e.g. --privileged
+            raise ValueError(f"invalid image name: {self.image!r}")
+        if lifetime is not None and (gui or lifetime <= 0):
+            raise ValueError("lifetime must be > 0 seconds and is only supported for headless sandboxes")
+        if idle_ttl is not None and (gui or idle_ttl <= 0):
+            raise ValueError("idle_ttl must be > 0 seconds and is only supported for headless sandboxes")
+        # strict: `name` ends up in --name and --volume, where a ',' or ':' would inject mount options
+        if name is not None and not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,62}", name):
+            raise ValueError(f"invalid name {name!r}: letters, digits, '_', '.', '-' only (max 63)")
+        self.persistent = name is not None
+        self.name = f"agvisor-{name or uuid.uuid4().hex[:8]}"  # also the name of the data volume
+        self.data_dir = (GUI_HOME if gui else "/workspace") if self.persistent else None  # survives stop()
+        self.rdp_port = self.password = None  # set by start() when gui; user is GUI_USER
+        self._running = False
+
+    def _docker(self, *args, input=None, check=True):
+        cmd = ["docker", *(["-H", self.host] if self.host else []), *args]
+        r = subprocess.run(cmd, input=input, capture_output=True, text=True)
+        if check and r.returncode:
+            raise RuntimeError(r.stderr.strip())
+        return r
+
+    def _stream(self, *args, on_output):
+        """Like _docker, but calls on_output(text) as each chunk arrives. stderr is merged into stdout."""
+        cmd = ["docker", *(["-H", self.host] if self.host else []), *args]
+        p = subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+        dec, tail, kept = codecs.getincrementaldecoder("utf-8")("replace"), collections.deque(), 0  # a chunk can end mid-character
+        while chunk := os.read(p.stdout.fileno(), 4096):
+            if text := dec.decode(chunk):
+                tail.append(text)
+                kept += len(text)
+                while kept - len(tail[0]) >= _KEEP:  # a runaway `yes` must not fill our memory
+                    kept -= len(tail.popleft())
+                on_output(text)
+        p.wait()
+        return subprocess.CompletedProcess(cmd, p.returncode, "".join(tail), "")
+
+    def run_args(self):
+        l = self.limits
+        a = ["run", "-d", f"--runtime={self.runtime}", f"--name={self.name}",
+             f"--cpus={l.cpus}", f"--memory={l.memory}", f"--memory-swap={l.memory}",
+             f"--pids-limit={l.pids}", f"--network={self.network}",
+             # gVisor caps the rootfs overlay (a file on the host disk): writes past it get ENOSPC. Per-container,
+             # no daemon setting needed. `root:` only: `all:` would also overlay /workspace and stop it persisting.
+             f"--annotation=dev.gvisor.flag.overlay2=root:self,size={l.disk}"]
+        if self.lifetime or self.idle_ttl:  # PID 1 ends on its own: the container exits, then --rm deletes it, even if we crash
+            a.append("--rm")
+        a.append("--label=agvisor=1")  # what list_sandboxes() finds
+        if self.persistent:
+            a.append(f"--label=agvisor.name={self.name.removeprefix('agvisor-')}")
+        if self.data_dir:  # a docker volume is a host directory: it is outside gVisor's discarded rootfs overlay
+            a.append(f"--volume={self.name}:{self.data_dir}")
+            if not self.gui:
+                a.append(f"--workdir={self.data_dir}")  # relative paths in exec() land on persistent storage
+        if self.gui:  # --privileged only grants simulated caps inside gVisor, not host access
+            a += ["--privileged", f"--shm-size={l.shm or '1g'}", f"--publish=127.0.0.1::{RDP_PORT}"]
+        elif l.shm:
+            a.append(f"--shm-size={l.shm}")
+        if not self.gui:  # PID 1 is `sleep`, which never reaps orphans: they stay zombies and eat the pids limit
+            a.append("--init")  # (gui: systemd is PID 1 and reaps)
+        return a + [self.image] + self._pid1()
+
+    def _pid1(self):
+        if self.gui:
+            return []
+        if not self.idle_ttl:
+            return ["sleep", str(self.lifetime or "infinity")]
+        # exits when the marker is older than idle_ttl (checked every 5s); a missing marker counts as expired.
+        # `timeout` adds lifetime as a hard cap on top.
+        watch = (f"touch {_MARK}; while [ $(( $(date +%s) - $(stat -c %Y {_MARK} 2>/dev/null || echo 0) )) "
+                 f"-lt {self.idle_ttl} ]; do sleep 5; done")
+        return (["timeout", str(self.lifetime)] if self.lifetime else []) + ["sh", "-c", watch]
+
+    def _left_running(self):
+        """A named container an earlier session never stopped: resume it, processes and all."""
+        if not self.persistent:
+            return False
+        r = self._docker("inspect", "-f", "{{.State.Running}}", self.name, check=False)
+        return r.stdout.strip() == "true"
+
+    def start(self):
+        if self._running:  # create_sandbox() already started it, then `with` calls start() again
+            return self
+        resumed = self._left_running()  # limits/image args are ignored then: they were fixed at creation
+        if not resumed:
+            if self.persistent:  # a stopped leftover would block the name; its data lives in the volume
+                self._docker("rm", "-f", self.name, check=False)
+            self._docker(*self.run_args())
+        self._running = True  # the container exists from here, so stop() must clean up if setup fails
+        try:
+            if self.gui:  # random host port + random password instead of the image's gnome:gnome
+                out = self._docker("port", self.name, f"{RDP_PORT}/tcp").stdout
+                self.rdp_port = int(out.splitlines()[0].rsplit(":", 1)[1])
+                self.password = secrets.token_urlsafe(12)  # urlsafe: no quote that could break the file below
+                self._docker("exec", "-i", "-u", "root", self.name, "chpasswd",
+                             input=f"{GUI_USER}:{self.password}\n")  # sudo / console login
+                creds = f"[RDP]\ncredentials={{'username': <'{GUI_USER}'>, 'password': <'{self.password}'>}}\n"
+                self._docker("exec", "-i", "-u", GUI_USER, self.name, "sh", "-c", _RDP_SETUP, "sh", _RDP_CREDS,
+                             input=creds)  # RDP login; stdin keeps the password out of `ps`. Returns once RDP listens
+        except BaseException:
+            if resumed:  # never destroy a container (and its processes) that we merely re-attached to
+                self._running = False
+            else:
+                self.stop()
+            raise
+        return self
+
+    def exec(self, cmd, *, input=None, timeout=120, on_output=None):
+        """Run a shell command inside. Returns CompletedProcess; returncode 124 = timed out.
+        `on_output(text)` is called with output as it is produced (stderr merged into stdout, which then holds
+        only the last ~100 KB; it must not raise, and can't be combined with `input`).
+        That needs GNU `timeout`, i.e. a Debian/Ubuntu-based image. Alpine's busybox returns 143 instead and kills
+        only the shell: the children of a compound command (`a; b`) keep running."""
+        if self.idle_ttl:
+            if timeout + 6 >= self.idle_ttl:  # +5 = the kill grace below, +1 = the watchdog compares whole seconds
+                raise ValueError(f"timeout={timeout}s must stay below idle_ttl={self.idle_ttl}s, "
+                                 "or the sandbox could expire in the middle of the command")
+            # activity = an exec starting or ending (the trap also fires on `exit`)
+            cmd = f"trap 'touch {_MARK} 2>/dev/null' EXIT; touch {_MARK} 2>/dev/null; {cmd}"
+        argv = ["timeout", "-k", "5", str(timeout), "sh", "-c", cmd]  # kills inside, not just the client
+        if on_output:
+            if input is not None:
+                raise ValueError("on_output can't be combined with input")
+            return self._stream("exec", "-i", self.name, *argv, on_output=on_output)
+        return self._docker("exec", "-i", self.name, *argv, input=input, check=False)
+
+    def desktop_token(self, key: bytes, ttl=300):
+        """Token for <agvisor-desktop>. Mint it server-side only: it carries the RDP password.
+        Replayable until `ttl` runs out."""
+        if self.rdp_port is None:
+            raise ValueError("start() a gui=True sandbox first")
+        return make_token(key, self.rdp_port, self.password, ttl)
+
+    def stop(self):
+        """Remove the container and free its CPU/RAM. A named sandbox keeps its data volume."""
+        self._docker("rm", "-f", self.name, check=False)
+        self._running = False
+
+    def delete(self):
+        """stop() and also erase the persistent data, so create_sandbox(name=...) starts from scratch."""
+        self.stop()
+        if self.persistent:
+            self._docker("volume", "rm", "-f", self.name, check=False)
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, *_):
+        self.stop()
+
+
+def list_sandboxes(host: str | None = None) -> list[Sandbox]:
+    """Every agvisor sandbox on that docker host, running or not, as handles: exec(), stop() and delete() work.
+    Anonymous ones (leaked by a crashed process) are included, so this is also how you find and kill them.
+    Don't start() a stopped handle: that makes a fresh default-image container."""
+    out = Sandbox(host=host)._docker("ps", "-a", "--filter", "label=agvisor",
+                                     "--format", '{{.Names}} {{.State}} {{.Label "agvisor.name"}}').stdout
+    boxes = []
+    for line in out.splitlines():
+        cname, state, *label = line.split()  # an empty label leaves no third field
+        sb = Sandbox(name=label[0] if label else None, host=host)
+        if not label:
+            sb.name = cname  # anonymous: its random container name is all there is
+        sb._running = state == "running"
+        boxes.append(sb)
+    return boxes
+
+
+def create_sandbox(
+    image: str | None = None,
+    *,
+    gui: bool = False,
+    limits: Limits = Limits(),
+    network: str = "bridge",
+    lifetime: int | None = None,
+    idle_ttl: int | None = None,
+    name: str | None = None,
+    host: str | None = None,
+    runtime: str = "runsc",
+) -> Sandbox:
+    """Create and start a gVisor sandbox. Use `with create_sandbox(...) as sb:` or call sb.stop() yourself.
+
+    image     Image to run. Default: ubuntu:24.04, or the GNOME desktop image when gui=True.
+    gui       True -> GNOME desktop over RDP (sb.rdp_port, sb.password, sb.desktop_token()). start() returns once the
+              desktop has booted and RDP listens (~30-60 s).
+    limits    Limits(cpus, memory, pids, shm, disk). Default: 2 cores, 2g RAM, 512 processes, 5g root disk.
+              Reusable across sandboxes. `disk` doesn't cover the /workspace volume of a named sandbox.
+    name      Makes the sandbox resumable. Files in sb.data_dir (/workspace; the gnome home when gui) are kept
+              in a docker volume on the host machine and survive stop(), `with` exit and lifetime expiry.
+              create_sandbox(name=same) later gets them back: it re-attaches to the container if an earlier
+              session left it running (processes and installed packages intact), else makes a fresh one on the
+              same volume. sb.delete() erases the data. Default: anonymous, nothing is kept.
+              There is NO ownership check: anyone who passes the same name gets that sandbox, so namespace
+              names per tenant yourself. The volume has no size cap either (limits.disk covers the rest).
+
+    network  "bridge" (internet access, default), "none" (headless only: gui needs its RDP port) or the name of a
+              docker network you created. A host firewall that drops traffic from docker0 blocks the gateway from
+              reaching a gui sandbox there: use a network of its own.
+    runtime  The docker runtime, default "runsc". Name a second one (e.g. "runsc-gui", same runsc plus the GUI
+              flags) to keep the strict one for headless sandboxes. Must be a gVisor runtime: plain runc is
+              refused for gui, which runs --privileged.
+    lifetime  Seconds until the sandbox destroys itself, even if your process dies. Headless only.
+              Default: lives until stop().
+    idle_ttl  Seconds without an exec() before the sandbox destroys itself, even if your process dies. The clock
+              restarts when each exec() starts and ends; background processes don't count. exec(timeout=) must be
+              shorter. A named sandbox keeps its files, and create_sandbox(name=same) later makes a fresh
+              container. Combine with lifetime for a hard cap. Headless only. Fixed at creation.
+    host     Which machine supplies the resources. None -> docker on this machine (or $DOCKER_HOST).
+              "ssh://user@host" -> docker on a remote VM/server, e.g. an EC2 or Azure VM.
+    """
+    return Sandbox(image, gui=gui, limits=limits, network=network, lifetime=lifetime, idle_ttl=idle_ttl,
+                   name=name, host=host, runtime=runtime).start()

agvisor-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: agvisor
+Version: 0.1.0
+Summary: gVisor sandboxes for coding agents, with resource limits and optional GUI
+Author: Sadok Barbouche
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.12
+Provides-Extra: web
+Requires-Dist: cryptography>=42; extra == 'web'
+Description-Content-Type: text/markdown
+
+# agvisor
+
+gVisor (`runsc`) sandboxes for coding agents. Thin wrapper over the `docker` CLI: CPU/memory/pids limits, optional GNOME desktop over RDP.
+
+> **Alpha, and not security-audited.** Read [Security](#security) before running code you don't trust.
+
+## Host setup (Linux VM or server)
+
+Install [gVisor](https://gvisor.dev/docs/user_guide/install/), then register the runtime in `/etc/docker/daemon.json` and `systemctl reload docker` (a *restart* bounces every running container unless `live-restore` is on).
+The two `runtimeArgs` are only needed for GUI sandboxes (systemd needs cgroup v2, `sudo` needs suid). Register them as a **second** runtime, so headless sandboxes keep the strict one, and pass `runtime="runsc-gui"` with `gui=True`:
+
+```json
+{"runtimes": {"runsc": {"path": "/usr/local/bin/runsc"},
+              "runsc-gui": {"path": "/usr/local/bin/runsc",
+                            "runtimeArgs": ["--in-sandbox-cgroup=v2", "--allow-suid"]}}}
+```
+
+(Putting the args on `runsc` itself also works and needs no `runtime=`, but then every sandbox on the host gets them.)
+
+**On AWS/Azure/GCP VMs:** with `network="bridge"` a sandbox can reach the cloud metadata endpoint (`169.254.169.254`) and read the VM's instance credentials. Block it on the host (untested here): `sudo iptables -I DOCKER-USER -d 169.254.169.254 -j DROP`, or use `network="none"`.
+
+GUI image (x86_64), from the [gVisor systemd post](https://gvisor.dev/blog/2026/09/17/systemd-in-gvisor/):
+
+```sh
+git clone https://github.com/google/gvisor.git && cd gvisor
+docker build -t systemd-debian-gnome \
+  -f images/systemd-user/systemd-debian-gnome/Dockerfile.x86_64 images/systemd-user/systemd-debian-gnome
+```
+
+The image is ~8 GB and the build takes ~30 min on 2 vCPUs (checked on a 2 vCPU / 4 GB VM: peak ~1.5 GB RAM). A desktop needs about 0.7 GB RAM idle, so give it `memory="1536m"` or more.
+
+**Host firewall:** if yours drops traffic from `docker0` (e.g. `INPUT -i docker0 -j DROP`, a common way to keep sandboxes away from the host), the gateway can't reach a desktop on the default bridge: guacd hangs without an error. Create a network for desktops (`docker network create desktops`) and pass `network="desktops"`. Your egress rules don't apply to it, so don't run untrusted code there.
+
+## Use
+
+```python
+from agvisor import Limits
+from agvisor.sandbox import create_sandbox   # creates AND starts the sandbox
+
+SMALL = Limits(cpus=1, memory="512m", pids=128)   # define once, reuse for any number of sandboxes
+
+with create_sandbox(limits=SMALL, lifetime=3600) as sb:                      # headless
+    r = sb.exec("python3 -c 'print(1+1)'", timeout=30)
+    print(r.returncode, r.stdout)
+
+with create_sandbox(gui=True, limits=Limits(cpus=4, memory="6g")) as sb:     # desktop
+    print(f"RDP 127.0.0.1:{sb.rdp_port}  user=gnome  password={sb.password}")
+    input("press enter to destroy")
+
+sb = create_sandbox(host="ssh://user@my-vm")   # same thing, on a remote VM/server (e.g. EC2, Azure)
+sb.stop()                                      # without `with`, you stop it yourself
+```
+
+| param | meaning |
+|---|---|
+| `image` | default `ubuntu:24.04`, or the GNOME image when `gui=True` |
+| `gui` | GNOME desktop over RDP, with a random RDP password (not the image's `gnome:gnome`). `start()` waits for the desktop to boot: ~30-60 s |
+| `runtime` | docker runtime, default `runsc`. With a separate GUI runtime: `"runsc-gui"`. Must be a gVisor runtime: plain `runc` is refused for `gui` (it runs `--privileged`, which is only simulated under gVisor) |
+| `limits` | `Limits(cpus, memory, pids, shm, disk)`: default 2 cores, `2g`, 512 processes, docker's `/dev/shm` size, `5g` root disk. Zero or negative values are rejected (docker and runsc would read 0 as unlimited) |
+| `network` | `"bridge"` (internet, default), `"none"` (headless only) or the name of a docker network you created |
+| `lifetime` | seconds until the sandbox deletes itself, even if your process dies (headless only) |
+| `idle_ttl` | seconds without an `exec()` before the sandbox deletes itself, even if your process dies (headless only). Expiry can lag by up to ~5s. See below |
+| `name` | makes the sandbox resumable, see below |
+| `host` | `None` = docker on this machine (or `$DOCKER_HOST`); `"ssh://user@host"` = docker on a remote VM/server |
+
+`sb.exec(cmd, input=None, timeout=120)` runs `sh -c cmd` inside and returns a `CompletedProcess`; on timeout the command is killed and `returncode` is 124. That relies on GNU `timeout`, so use Debian/Ubuntu-based images (`python:3.12-slim`, `ubuntu`). On Alpine (busybox) the code is 143 and only the shell is killed: the children of a compound command (`a; b`) keep running. Also don't set an `ENTRYPOINT` in your image: agvisor starts it with `sleep infinity` as arguments.
+
+Under gVisor, the limits behave differently from plain docker (checked on real `runsc`):
+- `pids` budgets the sandbox runtime's *host threads*, not guest processes: an idle sandbox already uses ~35. Keep the default (512): at 64–128, a fork storm made `fork` fail with `Out of memory` and, pushed harder, killed the sandbox.
+- Going over `memory` or `pids` kills the **whole sandbox**, not one process, and the host doesn't notice. Afterwards `exec` returns `returncode` 1 or 128 with `is not running` or `WaitPID` in stderr. Call `create_sandbox(name=...)` again: it starts a fresh container on the same `/workspace` volume.
+- `disk` caps the **root filesystem** (runsc's `overlay2` annotation, checked on release-20261026.0): past it, writes fail with `No space left on device` and the sandbox keeps running. Whole number + `k/m/g/t`: `1.5g` and `2gb` are rejected. It does **not** cover `/tmp`, which gVisor backs with RAM (counted in `memory`), nor the `/workspace` volume of a named sandbox: that is a plain host directory with **no size cap**, so a runaway agent can fill the host's disk through it. Until that has a cap, keep `/var/lib/docker` on a disk of its own, and don't share it with anything you care about. `tests/test_gvisor_disk.py` checks the cap against real gVisor.
+- Inside, `uname -r` reports `4.19.0-gvisor` and `/sys/fs/cgroup` and `/sys/class/net` don't exist (use `/proc/net/dev`).
+
+### Resuming a sandbox
+
+```python
+with create_sandbox("python:3.12", name="my-project") as sb:   # session 1
+    sb.exec("git clone https://github.com/me/repo && python -m venv .venv && .venv/bin/pip install -r repo/requirements.txt")
+# the container is gone (CPU/RAM freed), /workspace is kept
+
+with create_sandbox("python:3.12", name="my-project") as sb:   # session 2, days later
+    sb.exec("ls -a")                                            # -> repo/ .venv/   (cwd is /workspace)
+
+create_sandbox(name="my-project").delete()          # forget it: erases the data too
+```
+
+- **Kept:** everything under `sb.data_dir` (`/workspace`; the `gnome` home for `gui=True`), in a docker volume `agvisor-<name>`.
+- **Not kept:** processes, and anything outside `data_dir` (e.g. `apt install`): gVisor discards the rootfs overlay when the container is destroyed. Work in `/workspace` (venvs, repos, caches), or bake system packages into your image.
+- **Keep everything:** don't call `stop()`. The container stays running and the next `create_sandbox(name=...)` re-attaches to it with processes and installed packages intact. (`limits`/`image` are then ignored: they were fixed at creation.)
+- The volume lives on the docker host. On a cloud VM, keep `/var/lib/docker` on a persistent disk (EBS / managed disk), not instance-store, and resume on the same VM. Don't set `--overlay2=all:*` in the `runsc` args: it would stop volumes persisting.
+
+For a remote host the RDP port is on that host's `127.0.0.1`: tunnel it with `ssh -L`.
+`network="none"` cuts network access (headless only: GUI needs the published port).
+
+### Expiry and cleanup
+
+```python
+from agvisor import list_sandboxes
+
+sb = create_sandbox(name="u42", idle_ttl=900, lifetime=4 * 3600)   # gone after 15 idle minutes, or 4h at most
+for sb in list_sandboxes(host="ssh://user@my-vm"):                 # every agvisor sandbox on that docker host
+    print(sb.name); sb.stop()                                      # exec(), stop() and delete() work on these handles
+```
+
+- `idle_ttl`: the clock restarts when each `exec()` starts and ends; background processes don't count. `exec(timeout=)` must be shorter than `idle_ttl` (else `ValueError`), so a command can't outlive the sandbox. It is fixed at creation, like `limits`.
+- A named sandbox that expires keeps its files: the next `create_sandbox(name=...)` makes a fresh container on the same volume. `delete()` is what erases them: run it from your own retention job.
+- `list_sandboxes()` also finds anonymous sandboxes left behind by a crashed process. Don't `start()` a stopped handle: it would make a fresh default-image container.
+
+## GUI in a web page (React, Next.js, Vue, plain HTML)
+
+Browsers can't speak RDP, so there is a gateway in between: `browser <-wss-> gateway/gateway.js <-> guacd <-RDP-> sandbox`.
+Start both on the docker host with the compose file (`pip install 'agvisor[web]'` for the token helper):
+
+```sh
+export AGVISOR_KEY=$(openssl rand -hex 32)   # shared by the gateway and your backend; compose refuses to start without it
+docker compose up -d --build                 # guacd + gateway, both on 127.0.0.1; gateway on :8090 (GATEWAY_PORT to change)
+```
+
+The compose file pins both images by digest, binds `guacd` to loopback (its image defaults to `0.0.0.0`, an open RDP proxy on host networking), and runs the gateway as a non-root, read-only container. Linux only: both use the host network. Without Docker: `cd gateway && npm install && npm start`, plus `guacd` bound to `127.0.0.1`.
+
+Put the gateway behind your TLS reverse proxy (so the page uses `wss://`) and your auth. In your backend, after the user is authorised:
+
+```python
+sb = create_sandbox(gui=True)
+token = sb.desktop_token(bytes.fromhex(os.environ["AGVISOR_KEY"]), ttl=60)  # server-side only: it holds the RDP password
+# return {"gateway": "wss://your.host/desktop", "token": token} to the page
+```
+
+In the page, give the element a size and pass both values (the component is `web/`, npm package `agvisor-desktop`):
+
+```jsx
+import "agvisor-desktop";   // React / Next.js ('use client'): safe to import during SSR, it does nothing on the server
+<agvisor-desktop gateway={gateway} token={token} style={{ width: "100%", height: 600 }} />
+```
+
+```html
+<!-- Vue: compilerOptions.isCustomElement = (tag) => tag === "agvisor-desktop"; plain HTML: <script type="module"> -->
+<agvisor-desktop :gateway="gateway" :token="token" style="width:100%;height:600px"></agvisor-desktop>
+```
+
+A new `token` reconnects. The element fires an `error` event (`e.detail` = message) when the connection fails or drops, e.g. a rejected or expired token: mint a fresh one and set it. TypeScript needs a JSX `IntrinsicElements` entry for the tag.
+A token only has to be valid when the session *opens*, but anyone holding it can open one until `ttl` runs out.
+In `web/`: `npm test` checks the token round trip against the real gateway with a fake guacd; `npm run test:browser` runs the component in real Chrome (render, mouse, keyboard, resize, errors, cleanup).
+
+## Security
+
+**This is alpha software and nobody has audited it.** gVisor shrinks the part of the kernel that sandboxed code can reach; it is not a guarantee, and this library's own code has not been reviewed for flaws. Don't use it as the boundary for hostile multi-tenant workloads without a review of your own, and keep `runsc` up to date (tested with release-20261026.0). Known gaps:
+
+- **Whoever can run `docker` on the host controls every sandbox**, and is effectively root on that host. agvisor adds no authentication or authorization: put your own in front of it.
+- **`name=` has no ownership check.** `create_sandbox(name="x")` re-attaches to whatever running container is called `agvisor-x`, removes a stopped one of that name, and `list_sandboxes()` returns every sandbox on the host. If a tenant can choose the name, they can attach to, run commands in, stop and `delete()` another tenant's sandbox. Build names yourself (e.g. `f"{tenant_id}-{run_id}"`) and check ownership before you pass them in.
+- **`/workspace` has no size cap.** `Limits(disk=)` only caps the root filesystem. The `/workspace` volume of a named sandbox is a plain host directory, so a runaway or hostile process can fill the host's disk through it. Anonymous sandboxes have no volume: their writes fall under `disk` (and RAM-backed `/tmp` under `memory`). For named ones, put `/var/lib/docker` on a disk of its own, so a full disk doesn't take other services down with it.
+- **Sandboxes on one docker network can reach each other.** That is Docker's default: every sandbox on `"bridge"` (the default) or on a network you share between tenants can connect to the others' open ports. Use `network="none"`, a separate network per tenant or run, or a network created with `-o com.docker.network.bridge.enable_icc=false` (from Docker's documentation; not tested with agvisor).
+- **`network="bridge"` also reaches the outside:** the internet, services listening on the host itself (through the bridge gateway), and on a cloud VM the metadata endpoint that serves instance credentials (see Host setup). Block what you don't want on the host's firewall, or use `network="none"`.
+- **`gui=True` runs `--privileged`.** Under gVisor that only grants simulated capabilities; under plain `runc` it would be real, so agvisor refuses `runc` for GUI sandboxes. The RDP password is random per sandbox and the gateway token is encrypted and authenticated, but anyone holding a token can open a session until it expires.
+
+To report a vulnerability, email sadokbarbouche1@outlook.com instead of opening a public issue (details in `SECURITY.md`).
+
+## CI and dependency updates
+
+- `.github/workflows/ci.yml` runs on every PR, every push to `main`, and weekly (new advisories appear without commits):
+  `test` (Python tests, the gateway token round trip, and the component in real Chrome), `audit` (`pip-audit` on the locked Python deps, `npm audit` + registry-signature check on `web/`), `semgrep` (code scan of the Python, the JS and the workflows).
+- `.github/dependabot.yml` opens weekly update PRs for `uv`, `npm` and the GitHub Actions themselves (minor+patch grouped, 7-day cooldown). Those PRs run the same checks.
+- Not configurable from a workflow, set these in the repo settings: make `test`, `audit` and `semgrep` required checks on `main`, and turn on Dependabot alerts.
+- Run it locally: `uv run python tests/test_args.py`, then in `web/`: `npm test` and `npm run test:browser` (after `npm ci` in both `web/` and `gateway/`), plus `uvx pip-audit …`, `uvx semgrep …` (exact commands in `ci.yml`).

agvisor-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+agvisor/__init__.py,sha256=h-1ms1prVX4wyA9kWnBBcD2hjy7FlDvw3z-HUMzFqMc,248
+agvisor/desktop.py,sha256=TDZNOrOtAxybpIUAmbrp0hlkh5T61OHWTIS1huDeuCw,2294
+agvisor/limits.py,sha256=iz-nNa0sobFvVYSCe5CQ_zOuJ9wPISVZmUouQWRxbLM,1558
+agvisor/sandbox.py,sha256=InF_qB2OshVI3L6ijHSntoTIHRfKJf87J3lIz0c-y0E,15461
+agvisor-0.1.0.dist-info/METADATA,sha256=_5zhNA4DhWMENagI5Uq1BJg8SCbXY1ukADPW9zkEu6M,15183
+agvisor-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+agvisor-0.1.0.dist-info/licenses/LICENSE,sha256=NZFmIqfLTHG2I92UuRS0w_wV6TR1MEKhSnX2mxN_EAo,1072
+agvisor-0.1.0.dist-info/RECORD,,

agvisor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agvisor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sadok Barbouche
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.