Python
OpenShell provider: one sandbox per agent, with a registry and network profiles
Devika Verma4181039ac4b3
diff --git a/coworker/agent.py b/coworker/agent.pyindex 2260141f..ee2e9350 100644--- a/coworker/agent.py+++ b/coworker/agent.py@@ -338,7 +338,11 @@ def build_engine(model_settings = {**(model_settings or {}), "reasoning_effort": config.reasoning_effort}# The session's workspace decides where commands run: in this process (`direct`, the# default, today's behaviour) or in a tool runner behind a sandbox provider.- sandbox_workspace = open_workspace(cwd=ws) if ws is not None else None+ sandbox_workspace = (+ open_workspace(cwd=ws, roots=root_list or None, session_id=session_id or "", agent=agent.name)+ if ws is not None+ else None+ )executor = sandbox_workspace.executor if sandbox_workspace is not None else Nonetodo = TodoList()context = AgentContext(diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.pynew file mode 100644index 00000000..f3a352f0--- /dev/null+++ b/coworker/sandbox/providers/openshell.py@@ -0,0 +1,280 @@+"""The OpenShell provider: one OpenShell sandbox per agent, the tool runner inside it.++Lifecycle goes through the `openshell` CLI (create, get, delete). The runner's pipe is the+gateway's gRPC method `ExecSandboxInteractive`, a live two-way stream with no terminal.+Design: ocw-context/docs/sandbox-design.md. What the spike on OpenShell 0.0.116 taught us+is in ocw-context/docs/sandbox-spike-openshell.md and is referred to below by letter.++What a sandbox gets:+- the session's folders as bind mounts at the SAME absolute paths, read-only where the+ session has them read-only, and nothing else of the machine;+- the runner as a read-only mount (never part of an image), started as the sandbox's main+ command, so it lives as long as the sandbox and a cut stream only loses the relay;+- a whole policy rendered by us: the folders, the uid and gid that own them (E), a+ network profile, and Landlock as a hard requirement;+- no credential providers at all. Keys never enter an agent's sandbox.+"""++from __future__ import annotations++import json+import logging+import os+import queue+import shutil+import subprocess+import sys+import tempfile+import threading+import time+import uuid+from pathlib import Path+from typing import Any, Optional, Sequence++import yaml++from ..bundle import build_runner_zipapp+from ..transport import Transport+from . import openshell_policy as policy+from . import openshell_wire as wire++log = logging.getLogger(__name__)++PINNED_VERSION = "0.0.116" # ruling 24: one pinned release until NVIDIA ships GA+DEFAULT_IMAGE = "ghcr.io/nvidia/openshell-community/sandboxes/base@sha256:aeef1c63f00e2913ea002ccb3aaf925f338b5c5d70e63576f0d95c16a138044e"+LABEL = "openworker"+_SOCKET = f"{policy.RUNTIME_DIR}/owr/r.sock"+_CLI_TIMEOUT = 120+++class OpenShellUnavailable(RuntimeError):+ """OpenShell is not installed, not running, or not the version we test against. The+ message says what to do; callers show it as it is."""+++def _cli(*args: str, timeout: float = _CLI_TIMEOUT, check: bool = True) -> subprocess.CompletedProcess:+ exe = shutil.which("openshell")+ if exe is None:+ raise OpenShellUnavailable("OpenShell is not installed on this machine (no `openshell` command). Run `openworker machine sandbox setup`, or install OpenShell yourself.")+ # stdin must be closed: without a terminal, `openshell sandbox exec` reads ALL of stdin+ # before it sends anything (spike finding B), so an inherited open stdin hangs it.+ done = subprocess.run(+ [exe, *args], stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=timeout, env={**os.environ, "NO_COLOR": "1"}+ )+ if check and done.returncode != 0:+ raise RuntimeError(f"`openshell {' '.join(args[:3])}` failed: {(done.stderr or done.stdout).strip()[-400:]}")+ return done+++def preflight() -> dict[str, Any]:+ """Refuse early, with a message a person can act on."""+ version = _cli("--version", timeout=15).stdout.strip().split()[-1]+ if version != PINNED_VERSION:+ raise OpenShellUnavailable(f"OpenShell {version} is installed; OpenWorker is tested with {PINNED_VERSION} only. Install that version (`openworker machine sandbox setup`).")+ status = _cli("status", timeout=30, check=False)+ if status.returncode != 0 or "Connected" not in status.stdout:+ raise OpenShellUnavailable("The OpenShell gateway is not running or cannot be reached (`openshell status`). On a headless machine, check `systemctl --user status openshell-gateway` and `loginctl enable-linger`.")+ return {"version": version}+++def _gateway() -> tuple[str, Path]:+ """(host:port, folder with the client certificate) of the active gateway."""+ home = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "openshell"+ name = (home / "active_gateway").read_text(encoding="utf-8").strip()+ meta = json.loads((home / "gateways" / name / "metadata.json").read_text(encoding="utf-8"))+ endpoint = str(meta["gateway_endpoint"]).split("://", 1)[-1].rstrip("/")+ return endpoint, home / "gateways" / name / "mtls"+++class OpenShellProvider:+ name = "openshell"++ def __init__(+ self,+ *,+ roots: Sequence[dict[str, Any]],+ cwd: Optional[str] = None,+ profile: str = policy.DEFAULT_PROFILE,+ image: Optional[str] = None,+ label: str = "",+ ) -> None:+ """`roots`: [{"path", "writable"}], primary first. `label`: who this sandbox is for+ (session and agent), stored on the sandbox so leftovers can be found."""+ if not roots:+ raise ValueError("an OpenShell sandbox needs at least one folder")+ self.roots = [{"path": str(Path(r["path"]).expanduser().resolve()), "writable": bool(r.get("writable"))} for r in roots]+ self.cwd = str(Path(cwd).expanduser().resolve()) if cwd else self.roots[0]["path"]+ self.profile = profile+ self.image = image or os.environ.get("OPENWORKER_SANDBOX_IMAGE") or DEFAULT_IMAGE+ # A label value may hold letters, digits, '-', '_' and '.', and at most 63 characters.+ self.label = "".join(c if c.isalnum() or c in "-_." else "-" for c in label)[:63].strip("-_.")+ self.sandbox_name = f"ow-{uuid.uuid4().hex[:12]}"+ self.sandbox_id: Optional[str] = None+ self._runner = build_runner_zipapp()+ self._tmp = tempfile.mkdtemp(prefix="ow-openshell-")++ def describe(self) -> dict[str, Any]:+ return {+ "provider": self.name,+ "enforcement": "full",+ "reason": f"OpenShell {PINNED_VERSION}: Landlock and seccomp on every process, network profile '{self.profile}', no keys inside",+ "sandbox": self.sandbox_name,+ "image": self.image,+ }++ # -- lifecycle --------------------------------------------------------------------+ def create(self) -> None:+ preflight()+ for root in self.roots:+ if not os.path.isdir(root["path"]):+ raise RuntimeError(f"folder does not exist on this machine: {root['path']}")+ uid, gid = (os.getuid(), os.getgid()) if sys.platform.startswith("linux") else (None, None)+ policy_file = Path(self._tmp) / "policy.yaml"+ policy_file.write_text(yaml.safe_dump(policy.render(self.roots, profile=self.profile, uid=uid, gid=gid), sort_keys=False), encoding="utf-8")+ driver_config = json.dumps(policy.mounts(self.roots, str(self._runner.parent)))+ command = [policy.PYTHON, "-S", f"{policy.RUNNER_MOUNT}/{self._runner.name}", "serve", "--socket", _SOCKET, "--cwd", self.cwd]+ args = [+ "sandbox", "create", "--name", self.sandbox_name, "--from", self.image,+ "--no-tty", "--detach", "--no-auto-providers",+ "--policy", str(policy_file), "--driver-config-json", driver_config,+ "--label", f"{LABEL}=1", "--env", f"HOME={policy.RUNTIME_DIR}",+ ] # fmt: skip+ if self.label:+ args += ["--label", f"{LABEL}-owner={self.label}"]+ try:+ _cli(*args, "--", *command, timeout=600) # the first create pulls the image+ except RuntimeError as exc:+ if "bind" in str(exc).lower() and "enable" in str(exc).lower():+ raise OpenShellUnavailable("The OpenShell gateway does not allow bind mounts, so it cannot give a sandbox your folders. Set `enable_bind_mounts = true` under `[openshell.drivers.docker]` in the gateway config (`openworker machine sandbox setup` does this).") from exc+ raise+ self._wait_ready()+ # Spike finding K: the first exec after a sandbox turns Ready hangs until it times+ # out, and the next one works. Spend that on a throwaway call.+ try:+ _cli("sandbox", "exec", "--name", self.sandbox_name, "--no-tty", "--timeout", "5", "--", "true", timeout=10, check=False)+ except subprocess.TimeoutExpired:+ pass++ def _wait_ready(self, seconds: float = 120) -> None:+ deadline = time.monotonic() + seconds+ phase = "?"+ while time.monotonic() < deadline:+ done = _cli("sandbox", "get", self.sandbox_name, "-o", "json", timeout=30, check=False)+ if done.returncode == 0:+ info = json.loads(done.stdout)+ sandbox = info.get("sandbox", info)+ phase = str(sandbox.get("phase") or sandbox.get("status", {}).get("phase") or "")+ self.sandbox_id = sandbox.get("id") or sandbox.get("metadata", {}).get("id") or self.sandbox_id+ if phase.lower().endswith("ready"):+ return+ if phase.lower().endswith(("error", "completed")):+ break+ time.sleep(1.0)+ raise RuntimeError(f"the OpenShell sandbox {self.sandbox_name} did not become ready (phase: {phase})")++ def open_runner(self) -> Transport:+ if not self.sandbox_id:+ raise RuntimeError("the sandbox has not been created")+ command = [policy.PYTHON, "-S", f"{policy.RUNNER_MOUNT}/{self._runner.name}", "attach", "--socket", _SOCKET]+ return GrpcExecTransport(self.sandbox_id, command)++ def verify(self, client: Any) -> None:+ """After connecting: every folder must really be reachable inside (spike finding F:+ a path that already exists in the image can silently block a mount)."""+ for root in self.roots:+ info = client.call("fs.list", {"path": root["path"], "limit": 1}, timeout=30)+ if "entries" not in info:+ raise RuntimeError(f"the folder {root['path']} is not reachable inside the sandbox")++ def destroy(self) -> None:+ try:+ _cli("sandbox", "delete", self.sandbox_name, timeout=90, check=False)+ except (subprocess.TimeoutExpired, OpenShellUnavailable):+ pass+ shutil.rmtree(self._tmp, ignore_errors=True)+++def list_our_sandboxes() -> list[dict[str, Any]]:+ """Every sandbox on this gateway that OpenWorker created (for the registry's clean-up)."""+ done = _cli("sandbox", "list", "--selector", f"{LABEL}=1", "-o", "json", timeout=60, check=False)+ if done.returncode != 0 or not done.stdout.strip():+ return []+ data = json.loads(done.stdout)+ return data.get("sandboxes", data) if isinstance(data, dict) else data+++class GrpcExecTransport:+ """The runner's pipe: OpenShell's `ExecSandboxInteractive` stream, no terminal."""++ def __init__(self, sandbox_id: str, command: list[str]) -> None:+ try:+ import grpc+ except ImportError as exc: # an optional extra, needed for this provider only+ raise OpenShellUnavailable("The OpenShell provider needs the `grpcio` package: pip install 'openworker[openshell]'.") from exc+ endpoint, certs = _gateway()+ credentials = grpc.ssl_channel_credentials(+ root_certificates=(certs / "ca.crt").read_bytes(),+ private_key=(certs / "tls.key").read_bytes(),+ certificate_chain=(certs / "tls.crt").read_bytes(),+ )+ host = endpoint.rsplit(":", 1)[0]+ options = [("grpc.ssl_target_name_override", "localhost")] if host in ("127.0.0.1", "::1") else []+ self._channel = grpc.secure_channel(endpoint, credentials, options=options)+ self._outgoing: "queue.Queue[Optional[bytes]]" = queue.Queue()+ self._incoming: "queue.Queue[Optional[bytes]]" = queue.Queue()+ self._buffer = b""+ self._closed = False+ call = self._channel.stream_stream(wire.METHOD, request_serializer=lambda b: b, response_deserializer=lambda b: b)+ self._call = call(self._requests(wire.encode_start(sandbox_id, command)))+ threading.Thread(target=self._pump, daemon=True).start()++ def _requests(self, start: bytes):+ yield start+ while True:+ data = self._outgoing.get()+ if data is None:+ return+ yield wire.encode_stdin(data)++ def _pump(self) -> None:+ try:+ for message in self._call:+ kind, data, code = wire.decode_event(message)+ if kind == "stdout" and data:+ self._incoming.put(data)+ elif kind == "stderr" and data:+ log.debug("runner relay: %s", data.decode("utf-8", "replace").rstrip())+ elif kind == "exit":+ log.debug("runner relay exited with %s", code)+ break+ except Exception as exc: # grpc.RpcError: the stream broke; the client reconnects+ if not self._closed:+ log.info("OpenShell exec stream ended: %s", exc)+ self._incoming.put(None)++ def send(self, frame: bytes) -> None:+ if self._closed:+ raise OSError("the stream is closed")+ self._outgoing.put(frame)++ def recv_line(self) -> Optional[bytes]:+ while b"\n" not in self._buffer:+ chunk = self._incoming.get()+ if chunk is None:+ self._incoming.put(None)+ return None+ self._buffer += chunk+ line, _, self._buffer = self._buffer.partition(b"\n")+ return line + b"\n"++ def close(self) -> None:+ self._closed = True+ self._outgoing.put(None)+ try:+ self._call.cancel()+ except Exception:+ pass+ try:+ self._channel.close()+ except Exception:+ passdiff --git a/coworker/sandbox/providers/openshell_policy.py b/coworker/sandbox/providers/openshell_policy.pynew file mode 100644index 00000000..d119a8ff--- /dev/null+++ b/coworker/sandbox/providers/openshell_policy.py@@ -0,0 +1,93 @@+"""Render an OpenShell policy from OUR words: the session's folders, a user id, a network+profile. We always supply the whole policy and never rely on the one an image ships with.++What the spike showed (ocw-context/docs/sandbox-spike-openshell.md):+- a bind mount is not enough, the policy must list the path too (finding D);+- the sandbox must run with the uid and gid that own the folders (finding E);+- `landlock.compatibility: hard_requirement` makes a kernel without Landlock refuse to run.+"""++from __future__ import annotations++import copy+from typing import Any, Optional, Sequence++RUNNER_MOUNT = "/opt/openworker"+RUNTIME_DIR = "/tmp" # the runner's socket and HOME live here; always read-write++# Read-only system paths every sandbox needs to run programs at all. With Landlock as a hard+# requirement EVERY listed path must exist in the image, or the sandbox refuses to start+# (seen with `/app`, which OpenShell's own default policy lists but the base image lacks).+# So this is the smallest set, all present in a merged-/usr Linux image; `/bin`, `/sbin`+# and `/lib64` are links into `/usr` there and need no entry of their own.+_SYSTEM_READ_ONLY = ["/usr", "/lib", "/etc", "/proc", "/dev/urandom", "/var/log"]++# NVIDIA's base image keeps its developer tools (a uv-managed Python that `python3` on PATH+# points to, a virtual environment) under `/sandbox`. Read-only, so the agent can use them.+_IMAGE_TOOLS_READ_ONLY = ["/sandbox"]++# The runner itself uses the system Python, which needs nothing outside `/usr`.+PYTHON = "/usr/bin/python3"++# Any program may use an allowed destination. The wall we want here is WHERE an agent's+# commands can connect, not which program does the connecting.+_ANY_BINARY = [{"path": "/**"}]+++def _hosts(name: str, hosts: Sequence[str]) -> dict[str, Any]:+ return {"name": name, "endpoints": [{"host": h, "port": 443} for h in hosts], "binaries": [dict(b) for b in _ANY_BINARY]}+++_CODE_HOSTS = _hosts(+ "code-hosts",+ ["github.com", "api.github.com", "codeload.github.com", "objects.githubusercontent.com", "raw.githubusercontent.com", "gitlab.com"],+)+_PACKAGES = _hosts(+ "package-registries",+ ["pypi.org", "files.pythonhosted.org", "registry.npmjs.org", "crates.io", "static.crates.io", "index.crates.io", "proxy.golang.org", "sum.golang.org"],+)+_SEARCH = _hosts("search-apis", ["api.search.brave.com", "api.tavily.com", "html.duckduckgo.com", "duckduckgo.com"])++PROFILES: dict[str, dict[str, dict[str, Any]]] = {+ # git and package registries: enough to clone, install and push.+ "strict": {"code_hosts": _CODE_HOSTS, "packages": _PACKAGES},+ # plus the search APIs.+ "standard": {"code_hosts": _CODE_HOSTS, "packages": _PACKAGES, "search": _SEARCH},+}+DEFAULT_PROFILE = "strict"+++def render(+ roots: Sequence[dict[str, Any]],+ *,+ profile: str = DEFAULT_PROFILE,+ uid: Optional[int] = None,+ gid: Optional[int] = None,+) -> dict[str, Any]:+ """`roots`: [{"path": absolute path, "writable": bool}], primary first."""+ if profile not in PROFILES:+ raise ValueError(f"unknown network profile {profile!r} (known: {', '.join(sorted(PROFILES))})")+ read_write = [RUNTIME_DIR, "/dev/null", "/dev/pts", *[str(r["path"]) for r in roots if r.get("writable")]]+ read_only = [*_SYSTEM_READ_ONLY, *_IMAGE_TOOLS_READ_ONLY, RUNNER_MOUNT, *[str(r["path"]) for r in roots if not r.get("writable")]]+ policy: dict[str, Any] = {+ "version": 1,+ "filesystem_policy": {"include_workdir": False, "read_only": read_only, "read_write": read_write},+ "landlock": {"compatibility": "hard_requirement"},+ "process": {+ "run_as_user": str(uid) if uid is not None else "sandbox",+ "run_as_group": str(gid) if gid is not None else "sandbox",+ },+ "network_policies": copy.deepcopy(PROFILES[profile]), # no shared objects: plain YAML, no anchors+ }+ return policy+++def mounts(roots: Sequence[dict[str, Any]], runner_dir: str) -> dict[str, Any]:+ """Driver config for the Docker driver: every folder at the same absolute path it has on+ the machine, and the runner's folder read-only."""+ binds = [+ {"type": "bind", "source": str(r["path"]), "target": str(r["path"]), "read_only": not r.get("writable")}+ for r in roots+ ]+ binds.append({"type": "bind", "source": runner_dir, "target": RUNNER_MOUNT, "read_only": True})+ return {"docker": {"mounts": binds}}diff --git a/coworker/sandbox/providers/openshell_wire.py b/coworker/sandbox/providers/openshell_wire.pynew file mode 100644index 00000000..42d4786f--- /dev/null+++ b/coworker/sandbox/providers/openshell_wire.py@@ -0,0 +1,97 @@+"""The three protobuf messages of OpenShell's `ExecSandboxInteractive`, by hand.++Only this one streaming call goes over gRPC (the CLI cannot stream input without a+terminal; spike finding B). Its messages are tiny, so they are encoded and decoded here+with the protobuf wire format directly, which keeps generated code and the protobuf+runtime out of OpenWorker. Field numbers are those of OpenShell 0.0.116 (`proto/+openshell.proto`); the provider refuses any other version.++ message ExecSandboxInput { oneof payload { ExecSandboxRequest start = 1; bytes stdin = 2; } }+ message ExecSandboxRequest { string sandbox_id = 1; repeated string command = 2; ... bool tty = 7; }+ message ExecSandboxEvent { oneof payload { Stdout stdout = 1; Stderr stderr = 2; Exit exit = 3; } }+ message ExecSandboxStdout { bytes data = 1; } (Stderr alike)+ message ExecSandboxExit { int32 exit_code = 1; }+"""++from __future__ import annotations++from typing import Iterator, Optional++METHOD = "/openshell.v1.OpenShell/ExecSandboxInteractive"+_LEN, _VARINT = 2, 0+++def _varint(value: int) -> bytes:+ out = bytearray()+ while True:+ byte = value & 0x7F+ value >>= 7+ if value:+ out.append(byte | 0x80)+ else:+ out.append(byte)+ return bytes(out)+++def _field(number: int, payload: bytes) -> bytes:+ return _varint((number << 3) | _LEN) + _varint(len(payload)) + payload+++def encode_start(sandbox_id: str, command: list[str]) -> bytes:+ request = _field(1, sandbox_id.encode("utf-8"))+ for part in command:+ request += _field(2, part.encode("utf-8"))+ # tty (field 7) is left at its default, false: no terminal on the stream.+ return _field(1, request)+++def encode_stdin(data: bytes) -> bytes:+ return _field(2, data)+++def _fields(buf: bytes) -> Iterator[tuple[int, int, object]]:+ pos = 0+ while pos < len(buf):+ key, pos = _read_varint(buf, pos)+ number, kind = key >> 3, key & 7+ if kind == _VARINT:+ value, pos = _read_varint(buf, pos)+ yield number, kind, value+ elif kind == _LEN:+ size, pos = _read_varint(buf, pos)+ yield number, kind, buf[pos : pos + size]+ pos += size+ elif kind == 5:+ pos += 4+ elif kind == 1:+ pos += 8+ else:+ raise ValueError(f"unsupported protobuf wire type {kind}")+++def _read_varint(buf: bytes, pos: int) -> tuple[int, int]:+ shift = value = 0+ while True:+ byte = buf[pos]+ pos += 1+ value |= (byte & 0x7F) << shift+ if not byte & 0x80:+ return value, pos+ shift += 7+++def decode_event(buf: bytes) -> tuple[str, Optional[bytes], Optional[int]]:+ """(kind, data, exit_code) with kind one of "stdout", "stderr", "exit", "other"."""+ for number, kind, value in _fields(buf):+ if kind != _LEN or not isinstance(value, bytes):+ continue+ if number in (1, 2):+ data = b"".join(v for n, k, v in _fields(value) if n == 1 and k == _LEN and isinstance(v, bytes))+ return ("stdout" if number == 1 else "stderr"), data, None+ if number == 3:+ code = 0+ for n, k, v in _fields(value):+ if n == 1 and k == _VARINT and isinstance(v, int):+ code = v - (1 << 64) if v >= (1 << 63) else v # int32 travels sign-extended+ return "exit", None, code+ return "other", None, Nonediff --git a/coworker/sandbox/registry.py b/coworker/sandbox/registry.pynew file mode 100644index 00000000..490fb77b--- /dev/null+++ b/coworker/sandbox/registry.py@@ -0,0 +1,162 @@+"""The sandbox registry: which sandboxes this server started, for whom, and where.++It answers three questions: how many sandboxes run on this machine, which sandbox belongs+to this session and agent, and (later) on which machine a tool call has to go. Rows carry a+`machine_id` from the first version, though it is always this machine for now, so that+placing a runner on another machine later needs no new shape.++It also keeps things tidy: a cap per machine, and clean-up of sandboxes whose server is+gone (a crash, a kill) so they do not pile up.+"""++from __future__ import annotations++import json+import os+import sqlite3+import threading+import time+from pathlib import Path+from typing import Any, Optional++from ..secrets import state_dir++LOCAL_MACHINE = "local"+MAX_ENV = "OPENWORKER_SANDBOX_MAX"+DEFAULT_MAX = 20++_SCHEMA = """+CREATE TABLE IF NOT EXISTS sandboxes (+ name TEXT PRIMARY KEY,+ provider TEXT NOT NULL,+ machine_id TEXT NOT NULL,+ session_id TEXT NOT NULL DEFAULT '',+ agent TEXT NOT NULL DEFAULT '',+ roots TEXT NOT NULL DEFAULT '[]',+ profile TEXT NOT NULL DEFAULT '',+ enforcement TEXT NOT NULL DEFAULT '',+ state TEXT NOT NULL,+ server_pid INTEGER NOT NULL,+ created_at REAL NOT NULL,+ last_used_at REAL NOT NULL+);+"""+++class SandboxLimitReached(RuntimeError):+ pass+++def _alive(pid: int) -> bool:+ try:+ os.kill(pid, 0)+ except ProcessLookupError:+ return False+ except PermissionError:+ return True+ return True+++class SandboxRegistry:+ def __init__(self, path: Optional[Path] = None) -> None:+ self.path = Path(path) if path is not None else state_dir() / "sandbox" / "registry.db"+ self.path.parent.mkdir(parents=True, exist_ok=True)+ self._lock = threading.Lock()+ with self._connect() as db:+ db.executescript(_SCHEMA)++ def _connect(self) -> sqlite3.Connection:+ db = sqlite3.connect(self.path, timeout=10)+ db.row_factory = sqlite3.Row+ return db++ # -- writes -----------------------------------------------------------------------+ def check_room(self, machine_id: str = LOCAL_MACHINE) -> None:+ limit = int(os.environ.get(MAX_ENV) or DEFAULT_MAX)+ running = self.count(machine_id)+ if running >= limit:+ raise SandboxLimitReached(+ f"{running} sandboxes are already running on this machine (the limit is {limit}; set {MAX_ENV} to change it)"+ )++ def record(+ self,+ name: str,+ *,+ provider: str,+ session_id: str = "",+ agent: str = "",+ roots: Optional[list] = None,+ profile: str = "",+ enforcement: str = "",+ machine_id: str = LOCAL_MACHINE,+ ) -> None:+ now = time.time()+ with self._lock, self._connect() as db:+ db.execute(+ "INSERT OR REPLACE INTO sandboxes VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",+ (name, provider, machine_id, session_id, agent, json.dumps(roots or []), profile, enforcement, "ready", os.getpid(), now, now),+ )++ def touch(self, name: str) -> None:+ with self._lock, self._connect() as db:+ db.execute("UPDATE sandboxes SET last_used_at = ? WHERE name = ?", (time.time(), name))++ def close(self, name: str) -> None:+ with self._lock, self._connect() as db:+ db.execute("DELETE FROM sandboxes WHERE name = ?", (name,))++ # -- reads ------------------------------------------------------------------------+ def list(self, machine_id: Optional[str] = None) -> list[dict[str, Any]]:+ query, args = "SELECT * FROM sandboxes", ()+ if machine_id is not None:+ query, args = query + " WHERE machine_id = ?", (machine_id,)+ with self._connect() as db:+ rows = [dict(r) for r in db.execute(query + " ORDER BY created_at", args)]+ for row in rows:+ row["roots"] = json.loads(row["roots"])+ return rows++ def count(self, machine_id: str = LOCAL_MACHINE) -> int:+ return len(self.list(machine_id))++ def find(self, session_id: str, agent: str = "") -> Optional[dict[str, Any]]:+ for row in self.list():+ if row["session_id"] == session_id and (not agent or row["agent"] == agent):+ return row+ return None++ # -- clean-up ---------------------------------------------------------------------+ def reap(self) -> list[str]:+ """Remove sandboxes whose server process is gone, and OpenShell sandboxes that carry+ our label but that no living server owns. Returns the names removed."""+ removed: list[str] = []+ rows = self.list(LOCAL_MACHINE)+ dead = [r for r in rows if not _alive(int(r["server_pid"]))]+ owned = {r["name"] for r in rows if r not in dead}+ openshell_names: set[str] = set()+ if any(r["provider"] == "openshell" for r in dead) or _openshell_present():+ from .providers import openshell++ try:+ listed = openshell.list_our_sandboxes()+ except Exception:+ listed = []+ openshell_names = {str(s.get("name") or s.get("metadata", {}).get("name") or "") for s in listed} - {""}+ for name in sorted(openshell_names - owned):+ try:+ openshell._cli("sandbox", "delete", name, timeout=90, check=False)+ removed.append(name)+ except Exception:+ pass+ for row in dead:+ self.close(row["name"])+ if row["name"] not in removed and row["provider"] != "openshell":+ removed.append(row["name"])+ return removed+++def _openshell_present() -> bool:+ import shutil++ return shutil.which("openshell") is not Nonediff --git a/coworker/sandbox/workspace.py b/coworker/sandbox/workspace.pyindex 4a890ae7..9f5db3e8 100644--- a/coworker/sandbox/workspace.py+++ b/coworker/sandbox/workspace.py@@ -22,6 +22,7 @@ from .runner.executor import ExecutorPROVIDER_ENV = "OPENWORKER_SANDBOX_PROVIDER"DIRECT = "direct"RUNNER_LOCAL = "runner-local"+OPENSHELL = "openshell"class Workspace(ABC):@@ -52,19 +53,48 @@ class DirectWorkspace(Workspace):class RunnerWorkspace(Workspace):- def __init__(self, provider: Any, *, cwd: str | Path, shell: str = "main") -> None:+ def __init__(+ self,+ provider: Any,+ *,+ cwd: str | Path,+ shell: str = "main",+ registry: Any = None,+ session_id: str = "",+ agent: str = "",+ ) -> None:from .client import RunnerClientfrom .executor import RunnerExecutorself.provider = provider+ self.registry = registry+ self._registered: Optional[str] = None+ if registry is not None:+ registry.reap() # sandboxes left behind by a server that is gone+ registry.check_room()provider.create()try:self.client = RunnerClient(provider.open_runner)self.hello = self.client.connect()+ verify = getattr(provider, "verify", None)+ if verify is not None:+ verify(self.client) # e.g. every folder is really reachable insideexcept Exception:provider.destroy()raiseself._executor = RunnerExecutor(self.client, cwd=str(Path(cwd).expanduser().resolve()), shell=shell)+ if registry is not None:+ info = provider.describe()+ self._registered = str(info.get("sandbox") or f"{info['provider']}-{id(self):x}")+ registry.record(+ self._registered,+ provider=info["provider"],+ session_id=session_id,+ agent=agent,+ roots=getattr(provider, "roots", None),+ profile=getattr(provider, "profile", ""),+ enforcement=info.get("enforcement", ""),+ )@propertydef executor(self) -> Executor:@@ -79,14 +109,26 @@ class RunnerWorkspace(Workspace):finally:self.client.close()self.provider.destroy()+ if self.registry is not None and self._registered:+ self.registry.close(self._registered)def provider_name(explicit: Optional[str] = None) -> str:return (explicit or os.environ.get(PROVIDER_ENV) or DIRECT).strip().lower()-def open_workspace(*, cwd: str | Path, provider: Optional[str] = None) -> Workspace:- """The session's workspace for the configured provider. `direct` unless told otherwise."""+def open_workspace(+ *,+ cwd: str | Path,+ provider: Optional[str] = None,+ roots: Optional[list] = None,+ session_id: str = "",+ agent: str = "",+) -> Workspace:+ """The session's workspace for the configured provider. `direct` unless told otherwise.+ `roots`: the session's RootDir list (primary first); without it the workspace folder is+ the only, writable, root. `session_id` and `agent` say who the sandbox is for; they go+ into the registry and onto the sandbox as a label."""name = provider_name(provider)if name == DIRECT:return DirectWorkspace(cwd=cwd)@@ -94,4 +136,19 @@ def open_workspace(*, cwd: str | Path, provider: Optional[str] = None) -> Workspfrom .providers.runner_local import RunnerLocalProviderreturn RunnerWorkspace(RunnerLocalProvider(cwd=cwd), cwd=cwd)- raise ValueError(f"unknown sandbox provider: {name!r} (known: {DIRECT}, {RUNNER_LOCAL})")+ if name == OPENSHELL:+ from .providers.openshell import OpenShellProvider++ listed = [{"path": str(r.path), "writable": bool(r.writable)} for r in (roots or [])]+ listed = listed or [{"path": str(cwd), "writable": True}]+ from .registry import SandboxRegistry++ label = "-".join(part for part in (session_id[:24], agent[:24]) if part)+ return RunnerWorkspace(+ OpenShellProvider(roots=listed, cwd=str(cwd), label=label),+ cwd=cwd,+ registry=SandboxRegistry(),+ session_id=session_id,+ agent=agent,+ )+ raise ValueError(f"unknown sandbox provider: {name!r} (known: {DIRECT}, {OPENSHELL}, {RUNNER_LOCAL})")diff --git a/pyproject.toml b/pyproject.tomlindex 10144b3b..b6f6919d 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -54,6 +54,8 @@ messaging = ["python-telegram-bot>=21", "slack-bolt>=1.18", "aiohttp>=3.9"]browser = ["playwright>=1.44"]# AWS Bedrock provider (lazy-imported; desktop builds bundle it, pip users opt in).bedrock = ["boto3>=1.34"]+# OpenShell sandbox provider: the runner's stream is a gRPC call to the OpenShell gateway.+openshell = ["grpcio>=1.60"][project.scripts]openworker = "coworker.cli:main"diff --git a/tests/test_sandbox_openshell.py b/tests/test_sandbox_openshell.pynew file mode 100644index 00000000..3848256c--- /dev/null+++ b/tests/test_sandbox_openshell.py@@ -0,0 +1,244 @@+"""The OpenShell provider.++The first half runs anywhere: policy rendering, the hand-made stream messages, the refusal+messages. The second half needs a machine with OpenShell running and is skipped unless+`OPENWORKER_TEST_OPENSHELL=1` (it creates real sandboxes; see the design doc, section 11).+"""++from __future__ import annotations++import os+import subprocess+import threading+import time+from pathlib import Path++import pytest+import yaml++from coworker.sandbox.providers import openshell, openshell_policy as policy, openshell_wire as wire++ROOTS = [{"path": "/home/sam/code/app", "writable": True}, {"path": "/home/sam/reference", "writable": False}]+++# -- anywhere -----------------------------------------------------------------------------+++def test_policy_lists_every_folder_and_nothing_else_of_the_machine():+ rendered = policy.render(ROOTS, uid=1000, gid=1000)+ fs = rendered["filesystem_policy"]+ assert "/home/sam/code/app" in fs["read_write"] and "/home/sam/code/app" not in fs["read_only"]+ assert "/home/sam/reference" in fs["read_only"] and "/home/sam/reference" not in fs["read_write"]+ assert policy.RUNNER_MOUNT in fs["read_only"] # the agent cannot change the runner+ assert not any(p.startswith("/home/") and p not in {r["path"] for r in ROOTS} for p in fs["read_only"] + fs["read_write"])+ assert rendered["landlock"]["compatibility"] == "hard_requirement" # never run open+ assert rendered["process"] == {"run_as_user": "1000", "run_as_group": "1000"} # the folders' owner+++def test_policy_is_plain_yaml_without_shared_objects():+ text = yaml.safe_dump(policy.render(ROOTS), sort_keys=False)+ assert "&id" not in text and "*id" not in text+++def test_network_profiles():+ strict = policy.render(ROOTS, profile="strict")["network_policies"]+ standard = policy.render(ROOTS, profile="standard")["network_policies"]+ hosts = lambda p: {e["host"] for entry in p.values() for e in entry["endpoints"]} # noqa: E731+ assert {"github.com", "pypi.org", "registry.npmjs.org"} <= hosts(strict)+ assert "api.tavily.com" not in hosts(strict) and "api.tavily.com" in hosts(standard)+ assert all(entry["binaries"] for entry in strict.values()) # OpenShell requires the field+ with pytest.raises(ValueError):+ policy.render(ROOTS, profile="wide-open")+++def test_folders_are_mounted_at_the_same_absolute_path():+ mounts = policy.mounts(ROOTS, "/var/lib/openworker/sandbox")["docker"]["mounts"]+ assert {"type": "bind", "source": "/home/sam/code/app", "target": "/home/sam/code/app", "read_only": False} in mounts+ assert {"type": "bind", "source": "/home/sam/reference", "target": "/home/sam/reference", "read_only": True} in mounts+ assert {"type": "bind", "source": "/var/lib/openworker/sandbox", "target": policy.RUNNER_MOUNT, "read_only": True} in mounts+++def test_stream_messages_match_the_protobuf_wire_format():+ # ExecSandboxInput{start: ExecSandboxRequest{sandbox_id:"abc", command:["bash","-c"]}}+ assert wire.encode_start("abc", ["bash", "-c"]).hex() == "0a0f0a0361626312046261736812022d63"+ assert wire.encode_stdin(b"hi\n").hex() == "1203" + b"hi\n".hex()+ assert wire.decode_event(bytes.fromhex("0a070a0568656c6c6f")) == ("stdout", b"hello", None)+ assert wire.decode_event(bytes.fromhex("12050a03657272")) == ("stderr", b"err", None)+ assert wire.decode_event(bytes.fromhex("1a020803")) == ("exit", None, 3)+ assert wire.decode_event(bytes.fromhex("1a00")) == ("exit", None, 0)+ big = b"x" * 70000 # a length that needs a three-byte varint+ kind, data, _ = wire.decode_event(wire._field(1, wire._field(1, big)))+ assert (kind, data) == ("stdout", big)+++def test_missing_openshell_is_refused_with_a_message_a_person_can_act_on(monkeypatch):+ monkeypatch.setattr(openshell.shutil, "which", lambda name: None)+ with pytest.raises(openshell.OpenShellUnavailable) as err:+ openshell.preflight()+ assert "not installed" in str(err.value) and "sandbox setup" in str(err.value)+++def test_another_version_or_a_stopped_gateway_is_refused(monkeypatch):+ def fake(answers):+ def run(argv, **kwargs):+ assert kwargs.get("stdin") == subprocess.DEVNULL # an open stdin hangs the CLI+ out, code = answers[argv[1]]+ return subprocess.CompletedProcess(argv, code, out, "")++ return run++ monkeypatch.setattr(openshell.shutil, "which", lambda name: "/usr/bin/openshell")+ monkeypatch.setattr(openshell.subprocess, "run", fake({"--version": ("openshell 9.9.9\n", 0)}))+ with pytest.raises(openshell.OpenShellUnavailable, match="tested with"):+ openshell.preflight()+ ok_version = (f"openshell {openshell.PINNED_VERSION}\n", 0)+ monkeypatch.setattr(openshell.subprocess, "run", fake({"--version": ok_version, "status": ("Status: Disconnected", 1)}))+ with pytest.raises(openshell.OpenShellUnavailable, match="not running"):+ openshell.preflight()+ monkeypatch.setattr(openshell.subprocess, "run", fake({"--version": ok_version, "status": ("Status: Connected", 0)}))+ assert openshell.preflight() == {"version": openshell.PINNED_VERSION}+++def test_registry_counts_caps_and_forgets(tmp_path, monkeypatch):+ from coworker.sandbox.registry import SandboxLimitReached, SandboxRegistry++ reg = SandboxRegistry(tmp_path / "registry.db")+ reg.record("ow-a", provider="openshell", session_id="s1", agent="lead", roots=ROOTS, profile="strict", enforcement="full")+ reg.record("ow-b", provider="openshell", session_id="s1", agent="worker")+ assert reg.count() == 2 and reg.find("s1", "worker")["name"] == "ow-b"+ assert reg.list()[0]["roots"] == ROOTS and reg.list()[0]["machine_id"] == "local"+ monkeypatch.setenv("OPENWORKER_SANDBOX_MAX", "2")+ with pytest.raises(SandboxLimitReached, match="limit is 2"):+ reg.check_room()+ reg.close("ow-a")+ reg.check_room()+ assert [r["name"] for r in reg.list()] == ["ow-b"]+++def test_registry_reaps_rows_of_a_server_that_is_gone(tmp_path, monkeypatch):+ from coworker.sandbox import registry as registry_mod++ reg = registry_mod.SandboxRegistry(tmp_path / "registry.db")+ reg.record("owr-local-1", provider="runner-local", session_id="s1")+ reg.record("owr-local-2", provider="runner-local", session_id="s2")+ gone = subprocess.Popen(["true"])+ gone.wait()+ with reg._connect() as db:+ db.execute("UPDATE sandboxes SET server_pid = ? WHERE name = ?", (gone.pid, "owr-local-1"))+ monkeypatch.setattr(registry_mod, "_openshell_present", lambda: False)+ assert reg.reap() == ["owr-local-1"]+ assert [r["name"] for r in reg.list()] == ["owr-local-2"] # its server (this process) lives+++# -- on a machine with OpenShell -----------------------------------------------------------++live = pytest.mark.skipif(os.environ.get("OPENWORKER_TEST_OPENSHELL") != "1", reason="needs a running OpenShell gateway")+++def folder():+ """A real folder outside the image's own paths, owned by this user."""+ path = Path(os.environ.get("OPENWORKER_TEST_FOLDER", "/home/sam/code")) / f"t-{os.getpid()}-{int(time.time())}"+ path.mkdir(parents=True)+ yield path+ subprocess.run(["rm", "-rf", str(path)], check=False)+++def _open(folder, **kwargs):+ from coworker.roots import RootDir+ from coworker.sandbox.workspace import open_workspace++ roots = kwargs.pop("roots", None) or [RootDir(path=folder, writable=True)]+ return open_workspace(cwd=folder, provider="openshell", roots=roots, **kwargs), roots+++@live+def test_a_session_in_a_real_sandbox(folder):+ (folder / "hello.txt").write_text("from the machine\n")+ ws, roots = _open(folder, session_id="s-test", agent="swe-lead")+ try:+ assert ws.describe()["enforcement"] == "full" and ws.describe()["runner"]["os"] == "Linux"+ row = ws.registry.find("s-test", "swe-lead")+ assert row["name"] == ws.provider.sandbox_name and row["enforcement"] == "full" and row["profile"] == "strict"+ ex = ws.executor+ assert ex.run("cat hello.txt && cd /tmp && export KEEP=yes")["exit_code"] == 0+ assert ex.run("echo $KEEP $PWD")["output"].split() == ["yes", "/tmp"] # one persistent shell+ assert ex.run(f"echo made-inside > {folder}/out.txt")["exit_code"] == 0+ assert (folder / "out.txt").read_text() == "made-inside\n" # same path, the real folder+ assert (folder / "out.txt").stat().st_uid == os.getuid() # and the right owner+ outside = ex.run(f"ls {Path.home()} 2>&1; cat {Path.home()}/.ssh/authorized_keys 2>&1")+ assert "Permission denied" in outside["output"] or "No such file" in outside["output"]+ blocked = ex.run("curl -sS -m 8 -o /dev/null -w '%{http_code}' https://example.com; echo")+ assert blocked["output"].strip().endswith("000") # not in the strict profile+ allowed = ex.run("curl -sS -m 15 -o /dev/null -w '%{http_code}' https://api.github.com/zen; echo")+ assert allowed["output"].strip().endswith("200")++ from coworker.agents.base import AgentContext+ from coworker import catalog++ tools = {t.__name__: t for t in catalog.expand(["code_files", "search"], AgentContext(workspace=folder, executor=ex, roots=roots, sandbox=ws))}+ tools["write_file"]("notes/a.md", "TODO: written by a tool\n")+ assert "written by a tool" in tools["read_file"]("notes/a.md")["content"]+ assert tools["grep"]("TODO")["count"] == 1+ with pytest.raises(PermissionError):+ tools["write_file"]("/etc/owned", "x")+ finally:+ ws.close()+ assert ws.registry.find("s-test") is None # forgotten when the session's workspace closes+ assert ws.provider.sandbox_name not in subprocess.run(["openshell", "sandbox", "list"], stdin=subprocess.DEVNULL, capture_output=True, text=True).stdout+++@live+def test_a_cut_stream_resumes_in_a_real_sandbox(folder):+ ws, _ = _open(folder)+ try:+ ex = ws.executor+ ex.run("cd /tmp && export KEEP=yes")+ box: dict = {}+ worker = threading.Thread(target=lambda: box.update(ex.run("sleep 3; echo finished-while-away", timeout=60)))+ worker.start()+ time.sleep(1.0)+ ws.client._transport.close() # the gRPC stream is cut while the command runs+ worker.join(timeout=60)+ assert "finished-while-away" in box.get("output", "")+ assert ws.client.restarts == 0+ assert ex.run("echo $KEEP $PWD")["output"].split() == ["yes", "/tmp"]+ finally:+ ws.close()+++@live+def test_two_agents_share_a_folder_and_a_read_only_folder_stays_read_only(folder):+ from coworker.roots import RootDir++ shared, reference = folder / "shared", folder / "reference"+ shared.mkdir()+ reference.mkdir()+ (reference / "spec.md").write_text("the spec\n")+ roots = [RootDir(path=shared, writable=True), RootDir(path=reference, writable=False)]+ lead, _ = _open(shared, roots=roots, session_id="s-team", agent="lead")+ worker, _ = _open(shared, roots=roots, session_id="s-team", agent="worker")+ try:+ assert lead.provider.sandbox_name != worker.provider.sandbox_name # one sandbox per agent+ lead.executor.run("echo from-lead > handoff.txt")+ assert worker.executor.run("cat handoff.txt")["output"].strip() == "from-lead"+ assert worker.executor.run(f"cat {reference}/spec.md")["output"].strip() == "the spec"+ refused = worker.executor.run(f"echo x > {reference}/new.txt")+ assert refused["exit_code"] != 0 and not (reference / "new.txt").exists()+ finally:+ lead.close()+ worker.close()+++@live+def test_a_sandbox_left_behind_by_a_dead_server_is_removed(folder):+ """A server that crashed cannot delete its sandbox. The next one does."""+ from coworker.sandbox.providers.openshell import OpenShellProvider, list_our_sandboxes+ from coworker.sandbox.registry import SandboxRegistry++ orphan = OpenShellProvider(roots=[{"path": str(folder), "writable": True}], label="orphan")+ orphan.create() # created, never recorded by a living server+ names = lambda: {str(s.get("name")) for s in list_our_sandboxes()} # noqa: E731+ assert orphan.sandbox_name in names()+ removed = SandboxRegistry().reap()+ assert orphan.sandbox_name in removed and orphan.sandbox_name not in names()