Skip to content
Python

OpenShell provider: one sandbox per agent, with a registry and network profiles

Devika Verma4181039ac4b3
diff --git a/coworker/agent.py b/coworker/agent.py
index 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 None
todo = TodoList()
context = AgentContext(
diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.py
new file mode 100644
index 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:
+ pass
diff --git a/coworker/sandbox/providers/openshell_policy.py b/coworker/sandbox/providers/openshell_policy.py
new file mode 100644
index 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.py
new file mode 100644
index 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, None
diff --git a/coworker/sandbox/registry.py b/coworker/sandbox/registry.py
new file mode 100644
index 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 None
diff --git a/coworker/sandbox/workspace.py b/coworker/sandbox/workspace.py
index 4a890ae7..9f5db3e8 100644
--- a/coworker/sandbox/workspace.py
+++ b/coworker/sandbox/workspace.py
@@ -22,6 +22,7 @@ from .runner.executor import Executor
PROVIDER_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 RunnerClient
from .executor import RunnerExecutor
self.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 inside
except Exception:
provider.destroy()
raise
self._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", ""),
+ )
@property
def 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) -> Worksp
from .providers.runner_local import RunnerLocalProvider
return 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.toml
index 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.py
new file mode 100644
index 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()