xqo-docker 3.0.0__tar.gz

xqo_docker-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dudikkocak
+
+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.

xqo_docker-3.0.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: xqo-docker
+Version: 3.0.0
+Summary: Docker sandbox backend for xqo run_code
+Author: dudikkocak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dudikkocak/xqo
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xqo<4,>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# xqo-docker
+
+The `docker` sandbox backend for [xqo](https://github.com/dudikkocak/xqo)'s `run_code`: each run happens in a
+throwaway container with no network (unless the user grants it), memory, CPU and process limits, and the host
+user's uid. Python projects get a uv venv inside the image; Node, Go, Rust and .NET projects use their official
+images when the toolchains plugin is installed.
+
+```bash
+pip install xqo-docker
+```
+
+```json
+"sandbox": {"backend": "docker"}
+```
+
+With the plugin installed, `"backend": "auto"` picks Docker whenever the daemon answers and falls back to `local`
+otherwise. `"plugins": {"disable": ["docker"]}` turns it off without uninstalling. `/api/plugins` shows whether the
+daemon answered (`status.daemon`).
+
+Needs the `docker` CLI and a running daemon (Docker Desktop, Docker Engine or a compatible one). The image is set
+with `sandbox.image` (default `astral/uv:python3.12-bookworm-slim`); it needs `uv` and `python` on its PATH.

xqo_docker-3.0.0/README.md

@@ -0,0 +1,21 @@
+# xqo-docker
+
+The `docker` sandbox backend for [xqo](https://github.com/dudikkocak/xqo)'s `run_code`: each run happens in a
+throwaway container with no network (unless the user grants it), memory, CPU and process limits, and the host
+user's uid. Python projects get a uv venv inside the image; Node, Go, Rust and .NET projects use their official
+images when the toolchains plugin is installed.
+
+```bash
+pip install xqo-docker
+```
+
+```json
+"sandbox": {"backend": "docker"}
+```
+
+With the plugin installed, `"backend": "auto"` picks Docker whenever the daemon answers and falls back to `local`
+otherwise. `"plugins": {"disable": ["docker"]}` turns it off without uninstalling. `/api/plugins` shows whether the
+daemon answered (`status.daemon`).
+
+Needs the `docker` CLI and a running daemon (Docker Desktop, Docker Engine or a compatible one). The image is set
+with `sandbox.image` (default `astral/uv:python3.12-bookworm-slim`); it needs `uv` and `python` on its PATH.

xqo_docker-3.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xqo-docker"
+version = "3.0.0"
+description = "Docker sandbox backend for xqo run_code"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "dudikkocak"}]
+dependencies = [
+  "xqo>=3.0,<4",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-timeout>=2.3"]
+
+[project.urls]
+Homepage = "https://github.com/dudikkocak/xqo"
+
+[project.entry-points."xqo.plugins"]
+docker = "xqo_docker:DockerPlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]

xqo_docker-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xqo_docker-3.0.0/src/xqo_docker/__init__.py

@@ -0,0 +1,25 @@
+"""xqo-docker: the "docker" sandbox backend for run_code (throwaway containers, no network unless granted,
+toolchain images). With it installed, "sandbox": {"backend": "auto"} picks Docker when the daemon answers; without it
+(or with "plugins": {"disable": ["docker"]}) runs use the local backend."""
+from __future__ import annotations
+
+import importlib
+
+from xqo.api import Plugin, docker_available
+
+__version__ = "3.0.0"
+
+
+class DockerPlugin(Plugin):
+    name = "docker"
+    description = "Docker sandbox backend for run_code"
+
+    @classmethod
+    def register(cls) -> None:
+        importlib.import_module(f"{__name__}.backend")  # registers "docker" with register_backend
+
+    def configure(self, ctx, cfg):
+        return {"backend": "docker"}
+
+    def status(self) -> dict:
+        return {**self.obj, "daemon": docker_available()}

xqo_docker-3.0.0/src/xqo_docker/backend.py

@@ -0,0 +1,123 @@
+"""Docker sandbox backend (plugin): throwaway containers for run_code, with toolchain images and offline runs.
+The core keeps the `local` backend and the shared run/venv machinery."""
+from __future__ import annotations
+
+import asyncio
+import os
+import uuid
+from pathlib import Path, PurePosixPath
+
+from xqo.api import (DOCKER_PATH, Backend, Sandbox, current_toolchains, docker_available, docker_kill, docker_user,
+                     is_python_project, mount_hint, net_args, register_backend, setup_net_args, uv_pip_command)
+
+@register_backend
+class DockerBackend(Backend):
+    """A throwaway container: no network, memory/CPU/pid limits, the host user's uid. Python projects get a uv venv;
+    Node/Go/Rust/.NET projects run in their official image (at the version the project asks for), and mixed projects
+    in a composite image built once. Dependencies are installed by setup containers (network on, `setup_network`)
+    into the task's .deps-docker dir and shared download caches, which runs mount instead of copying."""
+    name = "docker"
+    toolchains = True
+    isolates_network = True
+
+    def available(self) -> bool:
+        return docker_available()
+
+    async def command(self, sb, work, command, env_dir, comps, network=False):
+        cfg, res, run_cmd = sb.config, {}, command
+        image, mounts, env = cfg.image, [], {}
+        toolchains = current_toolchains()  # the toolchains plugin, or None
+        if toolchains and env_dir is not None and cfg.toolchains and any(c.kind != "python" for c in comps):
+            plan = toolchains.docker_plan(work, comps, cfg)
+            image = plan["image"]
+            info = {"kind": "image", "image": image, "tools": plan["tools"]}
+            if plan["dockerfile"]:
+                built = await sb.build_image(image, plan["dockerfile"], env_dir.parent / ".deps-docker")
+                info.update(built)
+            res["toolchains"] = [info]
+            if not info.get("error"):
+                deps = env_dir.parent / ".deps-docker"
+                runner = DockerRunner(sb, image, work, deps, toolchains.cache_root(cfg.cache_dir) / "docker")
+                prep = await toolchains.prepare(runner, work, comps, deps, cfg, {"HOME": "/tmp"})
+                res["toolchains"] += prep.info
+                env = {**prep.env, **({} if network or cfg.network else DOCKER_RUN_OFFLINE)}
+                mounts = runner.mounts()
+                if prep.managed and (note := toolchains.install_note(command)):
+                    res["notes"] = [note]
+        container = f"orch-run-{uuid.uuid4().hex[:12]}"  # named, so a cancel can kill it
+        argv = ["docker", "run", "--rm", "-i", "--name", container, "--memory", cfg.memory, "--cpus", cfg.cpus,
+                "--pids-limit", "256", *docker_user(), "-v", f"{work}:/work", *mounts, "-w", "/work",
+                "-e", "HOME=/tmp"]
+        argv += [x for k, v in env.items() if k != "HOME" for x in ("-e", f"{k}={v}")]
+        if env_dir is not None and cfg.venv and is_python_project(work):
+            denv = env_dir.with_name(env_dir.name + "-docker")
+            venv = await sb.prepare_docker_env(work, denv, image)
+            res["venv"] = venv
+            if not venv.get("error"):  # run inside the task's venv; uv run/sync use it too
+                argv += ["-v", f"{denv}:/venv", "-e", "VIRTUAL_ENV=/venv/env", "-e", "UV_PROJECT_ENVIRONMENT=/venv/env",
+                         "-e", "UV_CACHE_DIR=/venv/cache", "-e", "UV_PYTHON_INSTALL_DIR=/venv/python",
+                         "-e", f"PATH=/venv/env/bin:{DOCKER_PATH}"]
+                run_cmd = uv_pip_command(command)
+        if network:  # approved by the user for this run: the host's CA and proxies, like setup containers
+            argv += net_args(cfg)
+        elif not cfg.network:
+            argv += ["--network", "none"]
+        argv += [image, "sh", "-c", run_cmd]
+        return {"argv": argv, "env": None, "run_cmd": run_cmd, "container": container, "result": res}
+
+
+# runs have no network: tools fail fast instead of trying to download
+DOCKER_RUN_OFFLINE = {"GOPROXY": "off", "GOTOOLCHAIN": "local", "CARGO_NET_OFFLINE": "true",
+                      "npm_config_prefer_offline": "true"}
+
+
+class DockerRunner:
+    """toolchains.prepare's setup commands, each in a throwaway container of the run's image: the run copy at /work,
+    the task's deps at /deps, the shared download caches at /cache; network on unless setup_network is false."""
+    versions = False   # the image is the version
+    host_env = False
+
+    def __init__(self, sb: "Sandbox", image: str, work: Path, deps: Path, cache: Path):
+        self.sb, self.image, self.work, self.deps, self.cache = sb, image, work, deps, cache
+        deps.mkdir(parents=True, exist_ok=True)  # made by us, not by Docker (it would make them root's)
+        cache.mkdir(parents=True, exist_ok=True)
+
+    def deps_view(self, deps: Path):
+        return PurePosixPath("/deps")
+
+    def mounts(self) -> list[str]:
+        return ["-v", f"{self.deps}:/deps", "-v", f"{self.cache}:/cache"]
+
+    def where(self, p: Path) -> str:
+        """A host path under the run copy or the deps dir, as the container sees it."""
+        for host, ctr in ((self.work, "/work"), (self.deps, "/deps")):
+            try:
+                return (PurePosixPath(ctr) / p.relative_to(host).as_posix()).as_posix()
+            except ValueError:
+                pass
+        raise ValueError(f"{p} is not mounted")
+
+    def exe(self, argv: list[str], env: dict) -> list[str]:
+        return ["corepack", *argv] if argv[0] in ("pnpm", "yarn") else argv  # node images ship corepack
+
+    def link(self, target: Path, link: Path) -> None:
+        os.symlink(self.where(target), link, target_is_directory=True)  # dangling on the host, valid inside
+
+    async def sh(self, argv, cwd: Path, env: dict, timeout: float):
+        cfg = self.sb.config
+        name = f"orch-setup-{uuid.uuid4().hex[:12]}"
+        dargv = ["docker", "run", "--rm", "-i", "--name", name, "--memory", cfg.memory, "--cpus", cfg.cpus,
+                 "--pids-limit", "512", *docker_user(), "-v", f"{self.work}:/work", *self.mounts(),
+                 *setup_net_args(cfg), "-w", self.where(cwd),
+                 *[x for k, v in env.items() for x in ("-e", f"{k}={v}")]]
+        if not cfg.setup_network:
+            dargv += ["--network", "none"]
+        try:
+            code, out = await self.sb._sh([*dargv, self.image, *argv], self.work, dict(os.environ), timeout)
+        except asyncio.CancelledError:
+            await docker_kill(name)
+            raise
+        if code == -1:
+            await docker_kill(name)
+        return code, (mount_hint(out) + "\n" + out) if code == 125 and mount_hint(out) else out
+

xqo_docker-3.0.0/src/xqo_docker.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: xqo-docker
+Version: 3.0.0
+Summary: Docker sandbox backend for xqo run_code
+Author: dudikkocak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dudikkocak/xqo
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xqo<4,>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# xqo-docker
+
+The `docker` sandbox backend for [xqo](https://github.com/dudikkocak/xqo)'s `run_code`: each run happens in a
+throwaway container with no network (unless the user grants it), memory, CPU and process limits, and the host
+user's uid. Python projects get a uv venv inside the image; Node, Go, Rust and .NET projects use their official
+images when the toolchains plugin is installed.
+
+```bash
+pip install xqo-docker
+```
+
+```json
+"sandbox": {"backend": "docker"}
+```
+
+With the plugin installed, `"backend": "auto"` picks Docker whenever the daemon answers and falls back to `local`
+otherwise. `"plugins": {"disable": ["docker"]}` turns it off without uninstalling. `/api/plugins` shows whether the
+daemon answered (`status.daemon`).
+
+Needs the `docker` CLI and a running daemon (Docker Desktop, Docker Engine or a compatible one). The image is set
+with `sandbox.image` (default `astral/uv:python3.12-bookworm-slim`); it needs `uv` and `python` on its PATH.

xqo_docker-3.0.0/src/xqo_docker.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/xqo_docker/__init__.py
+src/xqo_docker/backend.py
+src/xqo_docker.egg-info/PKG-INFO
+src/xqo_docker.egg-info/SOURCES.txt
+src/xqo_docker.egg-info/dependency_links.txt
+src/xqo_docker.egg-info/entry_points.txt
+src/xqo_docker.egg-info/requires.txt
+src/xqo_docker.egg-info/top_level.txt
+tests/test_docker.py

xqo_docker-3.0.0/src/xqo_docker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xqo_docker-3.0.0/src/xqo_docker.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xqo.plugins]
+docker = xqo_docker:DockerPlugin

xqo_docker-3.0.0/src/xqo_docker.egg-info/requires.txt

@@ -0,0 +1,5 @@
+xqo<4,>=3.0
+
+[dev]
+pytest>=8
+pytest-timeout>=2.3

xqo_docker-3.0.0/src/xqo_docker.egg-info/top_level.txt

@@ -0,0 +1 @@
+xqo_docker

xqo_docker-3.0.0/tests/test_docker.py

@@ -0,0 +1,126 @@
+"""The docker sandbox backend, driven by a fake `docker` script (no daemon needed), plus one real-daemon run."""
+import asyncio
+import json
+import os
+import subprocess
+
+import pytest
+
+from xqo.api import Sandbox, SandboxConfig, build, docker_available, mount_hint
+from xqo.sandbox import format_result  # not part of the plugin API; used here only to check the report text
+
+posix_only = pytest.mark.skipif(os.name == "nt", reason="the fake docker is a sh script")
+PREFIX = "python -c 'import sys; print(sys.prefix)'"
+DENIED = ("docker: Error response from daemon: mounts denied:\nThe path /tmp/orch-run-cgm9yxvr/work is not shared "
+          "from the host and is not known to Docker.\nYou can configure shared paths from Docker -> Preferences...\n")
+
+
+def fake_docker(tmp_path, monkeypatch, script):
+    bin_ = tmp_path / "bin"
+    bin_.mkdir()
+    (bin_ / "docker").write_text("#!/bin/sh\n" + script)
+    (bin_ / "docker").chmod(0o755)
+    monkeypatch.setenv("PATH", f"{bin_}{os.pathsep}{os.environ['PATH']}")
+
+
+def project(tmp_path, reqs="# no deps\n"):
+    ws = tmp_path / "ws"
+    ws.mkdir(parents=True)
+    (ws / "m.py").write_text("print('ok')\n")
+    (ws / "requirements.txt").write_text(reqs)
+    return ws
+
+
+def test_plugin_is_found_and_active(tmp_path):
+    cfg = tmp_path / "agents.json"
+    cfg.write_text(json.dumps({"agents": [{"name": "planner", "skills": ["planning"]}]}))
+    bus = build(cfg, tmp_path / "artifacts", str(tmp_path / "logs" / "events.jsonl"), mock=True, departments="none")
+    st = bus.plugins.states["docker"]
+    assert st.state == "active" and st.source == "xqo_docker:DockerPlugin"
+    assert Sandbox(SandboxConfig(backend="docker")).network_requestable
+
+
+@posix_only
+def test_run_with_network_drops_none_and_offline_env(tmp_path, monkeypatch):
+    log = tmp_path / "docker.log"
+    fake_docker(tmp_path, monkeypatch, f'printf "%s\\n" "$@" > "{log}"\n')
+    ca = tmp_path / "ca.pem"
+    ca.write_text("x")
+    sb = Sandbox(SandboxConfig(backend="docker", venv=False, ca_file=str(ca)))
+    asyncio.run(sb.run(tmp_path / "ws", "curl https://example.com", network=True))
+    argv = log.read_text().splitlines()
+    assert "none" not in argv and f"{ca.resolve()}:/etc/ssl/orch-ca.pem:ro" in argv
+    asyncio.run(sb.run(tmp_path / "ws", "curl https://example.com"))
+    argv = log.read_text().splitlines()
+    assert argv[argv.index("--network") + 1] == "none" and not any("orch-ca" in a for a in argv)
+
+
+@posix_only
+def test_mounts_the_run_dir_copy(tmp_path, monkeypatch):
+    log = tmp_path / "docker.log"
+    fake_docker(tmp_path, monkeypatch, f'printf "%s\\n" "$@" > "{log}"\n')
+    ws = tmp_path / "ws"
+    ws.mkdir()
+    root = tmp_path / "runs"
+    r = asyncio.run(Sandbox(SandboxConfig(backend="docker", run_dir=str(root))).run(ws, "true"))
+    mount = next(a for a in log.read_text().splitlines() if a.endswith(":/work"))
+    assert mount.startswith(str(root.resolve()) + os.sep + "orch-run-") and r["exit_code"] == 0 and "error" not in r
+    assert not list(root.glob("orch-run-*"))  # removed after the run
+
+
+@posix_only
+def test_mounts_denied_reported_with_a_fix(tmp_path, monkeypatch):
+    assert "File Sharing" in mount_hint(DENIED)
+    fake_docker(tmp_path, monkeypatch, f"cat >&2 <<'X'\n{DENIED}X\nexit 125\n")
+    ws = tmp_path / "ws"
+    ws.mkdir()
+    (ws / "requirements.txt").write_text("# none\n")
+    sb = Sandbox(SandboxConfig(backend="docker", run_dir=str(tmp_path / "runs")))
+    r = asyncio.run(sb.run(ws, "python -m unittest", env_dir=tmp_path / "task" / ".venv"))
+    assert r["exit_code"] == 125 and "File Sharing" in r["error"] and "File Sharing" in r["venv"]["error"]
+    out = format_result(r)
+    assert "[sandbox ERROR: Docker can't mount" in out and "[venv ERROR: Docker can't mount" in out
+
+
+FAKE_DOCKER = """printf '%s\\0' "$@" >> "$XQO_FAKE_DOCKER_LOG"; printf '\\036' >> "$XQO_FAKE_DOCKER_LOG"\n"""
+
+
+@posix_only
+def test_venv_made_with_uv_in_the_image(tmp_path, monkeypatch):
+    fake_docker(tmp_path, monkeypatch, FAKE_DOCKER)
+    log = tmp_path / "docker.log"
+    monkeypatch.setenv("XQO_FAKE_DOCKER_LOG", str(log))
+    ws, env = project(tmp_path), tmp_path / "task" / ".venv"
+    (ws / "tests").mkdir()
+    sb = Sandbox(SandboxConfig(backend="docker"))
+    r = asyncio.run(sb.run(ws, "pytest -q", env_dir=env))
+    calls = lambda: [c.split("\0")[:-1] for c in log.read_text().split("\x1e")[:-1]]  # noqa: E731
+    setup, run = calls()
+    script = setup[-1]
+    assert f"{env}-docker:/venv" in setup and setup[:2] == ["run", "--rm"]
+    assert "uv venv --quiet /venv/env" in script and "uv pip install --quiet --python /venv/env/bin/python -r requirements.txt" in script
+    assert "pytest" in script and "-m venv" not in script and "\npip " not in script
+    assert SandboxConfig().image in setup and "--network" not in setup  # deps may be downloaded during setup
+    assert f"{env}-docker:/venv" in run and "VIRTUAL_ENV=/venv/env" in run and run[run.index("none") - 1] == "--network"
+    assert r["venv"]["tool"] == "uv" and r["venv"]["created"] and r["venv"]["installed"] == ["requirements.txt"]
+    (tmp_path / "task" / ".venv-docker" / "env").mkdir()  # what the image's uv would have made
+    r = asyncio.run(sb.run(ws, "pytest -q", env_dir=env))  # same deps: no setup container
+    assert r["venv"].get("reused") and len(calls()) == 3
+    r = asyncio.run(sb.run(ws, "pip install x", env_dir=env))
+    assert calls()[-1][-1] == "uv pip install x" and r["ran"] == calls()[-1][-1] and "VIRTUAL_ENV=/venv/env" in calls()[-1]
+
+
+IMAGE = SandboxConfig().image
+
+
+def _image_ready():
+    return docker_available() and subprocess.run(["docker", "image", "inspect", IMAGE], capture_output=True).returncode == 0
+
+
+@pytest.mark.skipif(not _image_ready(), reason=f"docker or the {IMAGE} image is not available")
+def test_real_docker_runs_in_uv_venv(tmp_path):
+    ws, env = project(tmp_path), tmp_path / "task" / ".venv"
+    r = asyncio.run(Sandbox(SandboxConfig(backend="docker", timeout=60)).run(ws, PREFIX + " && uv --version", env_dir=env))
+    assert r["exit_code"] == 0, r
+    assert r["stdout"].splitlines()[0] == "/venv/env" and r["stdout"].splitlines()[1].startswith("uv ")
+    assert (tmp_path / "task" / ".venv-docker" / "env").is_dir()