pilldrops 1.0.0__tar.gz

pilldrops-1.0.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: pilldrops
+Version: 1.0.0
+Summary: Python SDK for PillDrops — AI-native sandboxes (secure code execution + app hosting)
+Home-page: https://pilldrops.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Create sandboxes, run commands and code, upload directories, launch app servers with preview URLs, and manage lifecycle — from Python. `import pilldrops` is canonical; `import sandforge` ships as a compatibility alias.

pilldrops-1.0.0/pilldrops/__init__.py

@@ -0,0 +1,24 @@
+"""PillDrops — Python SDK for AI-native sandboxes (pilldrops.com).
+
+    from pilldrops import Sandbox
+
+    with Sandbox.create(template="python-3.11") as sb:
+        print(sb.run("python -c 'print(2+2)'").stdout)   # 4
+        sb.upload("./app", "/app")                        # push a directory
+        r = sb.run("cd /app && python main.py")
+
+    # Run an app server and get a public preview URL:
+    with Sandbox.create(template="node-20", start="npm run dev", ports=[3000]) as app:
+        print(app.url)   # https://.../preview/<id>/3000/
+
+Credentials + endpoint resolve from (in order): explicit args, PILLDROPS_API_URL/
+PILLDROPS_API_KEY env (SANDFORGE_/E2B_/SANDBOX_ accepted as fallbacks), then
+~/.sandforge/config.json (written by `pilldrops login`).
+
+`import sandforge` and `import yoursandbox` keep working — they ship in the same
+distribution as compatibility aliases of this package.
+"""
+from sandforge.sandbox import Sandbox, ExecResult, Templates, config, build_image
+
+__all__ = ["Sandbox", "ExecResult", "Templates", "config", "build_image"]
+__version__ = "1.0.0"

pilldrops-1.0.0/pilldrops.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: pilldrops
+Version: 1.0.0
+Summary: Python SDK for PillDrops — AI-native sandboxes (secure code execution + app hosting)
+Home-page: https://pilldrops.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Create sandboxes, run commands and code, upload directories, launch app servers with preview URLs, and manage lifecycle — from Python. `import pilldrops` is canonical; `import sandforge` ships as a compatibility alias.

pilldrops-1.0.0/pilldrops.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+setup.py
+pilldrops/__init__.py
+pilldrops.egg-info/PKG-INFO
+pilldrops.egg-info/SOURCES.txt
+pilldrops.egg-info/dependency_links.txt
+pilldrops.egg-info/requires.txt
+pilldrops.egg-info/top_level.txt
+sandforge/__init__.py
+sandforge/sandbox.py
+tests/test_integration.py
+tests/test_sandbox.py
+yoursandbox/__init__.py
+yoursandbox/sandbox.py

pilldrops-1.0.0/pilldrops.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pilldrops-1.0.0/pilldrops.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

pilldrops-1.0.0/pilldrops.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+pilldrops
+sandforge
+yoursandbox

pilldrops-1.0.0/sandforge/__init__.py

@@ -0,0 +1,21 @@
+"""SandForge — Python SDK for AI-native sandboxes.
+
+    from sandforge import Sandbox
+
+    with Sandbox.create(template="python-3.11") as sb:
+        print(sb.run("python -c 'print(2+2)'").stdout)   # 4
+        sb.upload("./app", "/app")                        # push a directory
+        r = sb.run("cd /app && python main.py")
+
+    # Run an app server and get a public preview URL:
+    with Sandbox.create(template="node-20", start="npm run dev", ports=[3000]) as app:
+        print(app.url)   # https://.../preview/<id>/3000/
+
+Credentials + endpoint resolve from (in order): explicit args, SANDFORGE_API_URL/
+SANDFORGE_API_KEY env (E2B_/SANDBOX_ accepted as fallbacks), then ~/.sandforge/config.json
+(written by `sandforge login`).
+"""
+from .sandbox import Sandbox, ExecResult, Templates, config, build_image
+
+__all__ = ["Sandbox", "ExecResult", "Templates", "config", "build_image"]
+__version__ = "1.0.0"

pilldrops-1.0.0/sandforge/sandbox.py

@@ -0,0 +1,292 @@
+"""SandForge sandbox client. See package docstring for usage."""
+import io
+import json
+import os
+import tarfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Union
+
+import requests
+
+_CONFIG_PATH = os.environ.get("SANDFORGE_CONFIG") or str(Path.home() / ".sandforge" / "config.json")
+
+
+def config() -> Dict[str, str]:
+    """Resolve (api_url, key) from env then ~/.sandforge/config.json.
+
+    Env wins over the config file so CI can override a developer login. E2B_/
+    SANDBOX_ names are accepted so code written against those keeps working.
+    """
+    url = (os.environ.get("PILLDROPS_API_URL") or os.environ.get("SANDFORGE_API_URL")
+           or os.environ.get("E2B_API_URL") or os.environ.get("SANDBOX_API_URL") or "")
+    key = (os.environ.get("PILLDROPS_API_KEY") or os.environ.get("SANDFORGE_API_KEY")
+           or os.environ.get("E2B_API_KEY") or os.environ.get("SANDBOX_API_KEY") or "")
+    if not (url and key):
+        try:
+            with open(_CONFIG_PATH) as f:
+                c = json.load(f)
+            url = url or c.get("api_url", "")
+            key = key or c.get("key", "")
+        except (OSError, ValueError):
+            pass
+    return {"api_url": url.rstrip("/"), "key": key}
+
+
+@dataclass
+class ExecResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    truncated: bool = False
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+    def check(self) -> "ExecResult":
+        """Raise if the command failed (like subprocess.check_call)."""
+        if not self.ok:
+            raise RuntimeError(f"command exited {self.exit_code}:\n{self.stderr or self.stdout}")
+        return self
+
+
+class _Filesystem:
+    def __init__(self, sb: "Sandbox"):
+        self._sb = sb
+
+    def write(self, path: str, content: Union[str, bytes]) -> None:
+        if isinstance(content, str):
+            content = content.encode()
+        self._sb._req("POST", f"/v1/sandboxes/{self._sb.id}/files", params={"path": path},
+                      data=content, headers={"Content-Type": "application/octet-stream"})
+
+    def read(self, path: str) -> str:
+        r = self._sb._req("GET", f"/v1/sandboxes/{self._sb.id}/files", params={"path": path})
+        return r.text
+
+    def list(self, path: str = "/") -> List[Dict]:
+        r = self._sb._req("GET", f"/v1/sandboxes/{self._sb.id}/filesystem/list", params={"path": path})
+        body = r.json()
+        return body.get("entries", []) if isinstance(body, dict) else body
+
+
+class Sandbox:
+    """A running sandbox. Prefer `Sandbox.create(...)` and use it as a context
+    manager so it is always killed."""
+
+    def __init__(self, sandbox_id: str, session: requests.Session, base: str, info: Optional[dict] = None):
+        self.id = sandbox_id
+        self._s = session
+        self._base = base
+        self._info = info or {}
+        self.files = _Filesystem(self)
+
+    # ── construction ─────────────────────────────────────────────────────────
+    @classmethod
+    def create(
+        cls,
+        template: str = "python-3.11",
+        *,
+        image: Optional[str] = None,
+        start: Optional[str] = None,
+        ports: Optional[List[int]] = None,
+        env: Optional[Union[Dict[str, str], List[str]]] = None,
+        vcpu: int = 0,
+        mem_mb: int = 0,
+        storage_mb: int = 0,
+        timeout: int = 0,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> "Sandbox":
+        cfg = config()
+        base = (api_url or cfg["api_url"]).rstrip("/")
+        key = api_key or cfg["key"]
+        if not base:
+            raise RuntimeError("no API URL — set SANDFORGE_API_URL or run `sandforge login`")
+        s = requests.Session()
+        if key:
+            s.headers["Authorization"] = f"Bearer {key}"
+
+        body: Dict[str, object] = {"template": template}
+        if image:
+            body["image"] = image
+        if start:
+            body["start"] = start
+        if ports:
+            body["ports"] = list(ports)
+        if env:
+            body["env"] = ([f"{k}={v}" for k, v in env.items()] if isinstance(env, dict) else list(env))
+        if vcpu:
+            body["vcpu"] = vcpu
+        if mem_mb:
+            body["memory_mb"] = mem_mb
+        if storage_mb:
+            body["storage_mb"] = storage_mb
+        if timeout:
+            body["timeout"] = timeout
+
+        r = s.post(f"{base}/v1/sandboxes", json=body, timeout=180)
+        if r.status_code == 401:
+            raise PermissionError("invalid API key — run `sandforge login`")
+        if not r.ok:
+            raise RuntimeError(f"create failed ({r.status_code}): {r.text}")
+        data = r.json()
+        return cls(data["id"], s, base, info=data)
+
+    # ── properties ───────────────────────────────────────────────────────────
+    @property
+    def url(self) -> Optional[str]:
+        """Public preview URL for the app port (None until a port is published)."""
+        return self._info.get("url") or self._info.get("app_url")
+
+    @property
+    def template(self) -> str:
+        return self._info.get("template", "")
+
+    @property
+    def status(self) -> str:
+        return self._info.get("status") or self._info.get("state", "")
+
+    # ── execution ────────────────────────────────────────────────────────────
+    def run(self, cmd: str, cwd: str = "", timeout: int = 60) -> ExecResult:
+        r = self._req("POST", f"/v1/sandboxes/{self.id}/exec",
+                      json={"cmd": cmd, "cwd": cwd, "timeout": timeout}, timeout=timeout + 20)
+        d = r.json()
+        return ExecResult(d.get("stdout", ""), d.get("stderr", ""),
+                          d.get("exit_code", -1), d.get("truncated", False))
+
+    def run_code(self, code: str, lang: str = "python") -> ExecResult:
+        """Write a snippet to a workspace file and run it — the E2B-style convenience."""
+        ext = {"python": "py", "node": "js", "bash": "sh"}.get(lang, "txt")
+        runner = {"python": "python3", "node": "node", "bash": "bash"}.get(lang, "cat")
+        # Workspace-relative path: the /files API roots at /workspace and exec's
+        # cwd is /workspace, so a relative path is visible to both.
+        name = f"_sf_{int(time.time()*1000)}.{ext}"
+        self.files.write(name, code)
+        return self.run(f"{runner} {name}")
+
+    # ── files (directory-aware; paths are relative to the /workspace root) ────
+    def upload(self, local: str, remote: str) -> None:
+        """Upload a file or an entire directory. Paths are relative to the
+        sandbox workspace (/workspace) — e.g. upload('./app', 'app')."""
+        p = Path(local)
+        remote = remote.lstrip("/")
+        if p.is_dir():
+            self._upload_tar(p, remote)
+        else:
+            self.files.write(remote, p.read_bytes())
+
+    def _upload_tar(self, local_dir: Path, remote: str) -> None:
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+            tar.add(str(local_dir), arcname=".")
+        buf.seek(0)
+        # Upload the tar into the workspace, then untar it there via exec (cwd is
+        # /workspace, so the relative tar path and target dir both resolve).
+        tmp = f"_sf_up_{int(time.time()*1000)}.tgz"
+        self.files.write(tmp, buf.read())
+        self.run(f"mkdir -p {remote} && tar -xzf {tmp} -C {remote} && rm -f {tmp}").check()
+
+    def download(self, remote: str, local: str) -> None:
+        """Download a file (to a local path) or a directory (unpacked into local)."""
+        remote = remote.lstrip("/")
+        if self.run(f"test -d {remote} && echo DIR || echo FILE").stdout.startswith("DIR"):
+            tmp = f"_sf_dl_{int(time.time()*1000)}.tgz"
+            self.run(f"tar -czf {tmp} -C {remote} .").check()
+            r = self._req("GET", f"/v1/sandboxes/{self.id}/files?path={tmp}")
+            self.run(f"rm -f {tmp}")
+            with tarfile.open(fileobj=io.BytesIO(r.content), mode="r:gz") as t:
+                members = [m for m in t.getmembers()
+                           if not (m.name.startswith("..") or os.path.isabs(m.name))]
+                Path(local).mkdir(parents=True, exist_ok=True)
+                t.extractall(local, members=members)
+        else:
+            Path(local).write_text(self.files.read(remote))
+
+    # ── lifecycle ────────────────────────────────────────────────────────────
+    def pause(self) -> None:
+        self._req("POST", f"/v1/sandboxes/{self.id}/pause")
+
+    def resume(self) -> None:
+        self._req("POST", f"/v1/sandboxes/{self.id}/resume")
+
+    def set_timeout(self, seconds: int) -> None:
+        self._req("POST", f"/v1/sandboxes/{self.id}/timeout", json={"timeout": seconds})
+
+    def logs(self) -> list:
+        return self._req("GET", f"/v1/sandboxes/{self.id}/logs").json()
+
+    def metrics(self) -> dict:
+        return self._req("GET", f"/v1/sandboxes/{self.id}/metrics").json()
+
+    def kill(self) -> None:
+        try:
+            self._s.delete(f"{self._base}/v1/sandboxes/{self.id}", timeout=30)
+        except requests.RequestException:
+            pass
+
+    # ── plumbing ─────────────────────────────────────────────────────────────
+    def _req(self, method: str, path: str, timeout: int = 30, **kw) -> requests.Response:
+        r = self._s.request(method, f"{self._base}{path}", timeout=timeout, **kw)
+        if r.status_code == 404:
+            raise RuntimeError(f"not found: {path}")
+        if not r.ok:
+            raise RuntimeError(f"{method} {path} → {r.status_code}: {r.text[:200]}")
+        return r
+
+    def __enter__(self) -> "Sandbox":
+        return self
+
+    def __exit__(self, *_):
+        self.kill()
+
+    def __repr__(self) -> str:
+        return f"Sandbox(id={self.id!r}, template={self.template!r})"
+
+
+def build_image(context_dir: str, tag: str, *,
+                api_url: Optional[str] = None, api_key: Optional[str] = None) -> str:
+    """Build a custom image from a local context (Dockerfile at its root) on the
+    fleet and return the launchable tag:
+
+        img = build_image("./myapp", "myapp")
+        with Sandbox.create(image=img) as sb:
+            ...
+    """
+    cfg = config()
+    base = (api_url or cfg["api_url"]).rstrip("/")
+    key = api_key or cfg["key"]
+    if not base:
+        raise RuntimeError("no API URL — set SANDFORGE_API_URL or run `sandforge login`")
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        tar.add(context_dir, arcname=".")
+    buf.seek(0)
+    s = requests.Session()
+    if key:
+        s.headers["Authorization"] = f"Bearer {key}"
+    r = s.post(f"{base}/v1/images/build", params={"name": tag}, data=buf.read(),
+               headers={"Content-Type": "application/octet-stream"}, timeout=1500)
+    if not r.ok:
+        raise RuntimeError(f"image build request failed ({r.status_code}): {r.text[:300]}")
+    d = r.json()
+    if not d.get("ok"):
+        raise RuntimeError("image build failed:\n" + (d.get("log") or "")[-2000:])
+    return d["tag"]
+
+
+class Templates:
+    """List available templates."""
+
+    def __init__(self, api_url: Optional[str] = None, api_key: Optional[str] = None):
+        cfg = config()
+        self._base = (api_url or cfg["api_url"]).rstrip("/")
+        self._s = requests.Session()
+        key = api_key or cfg["key"]
+        if key:
+            self._s.headers["Authorization"] = f"Bearer {key}"
+
+    def list(self) -> list:
+        return self._s.get(f"{self._base}/v1/templates", timeout=15).json()

pilldrops-1.0.0/setup.cfg

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

pilldrops-1.0.0/setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="pilldrops",
+    version="1.0.0",
+    description="Python SDK for PillDrops — AI-native sandboxes (secure code execution + app hosting)",
+    long_description="Create sandboxes, run commands and code, upload directories, "
+                     "launch app servers with preview URLs, and manage lifecycle — from Python. "
+                     "`import pilldrops` is canonical; `import sandforge` ships as a compatibility alias.",
+    long_description_content_type="text/markdown",
+    url="https://pilldrops.com",
+    packages=find_packages(include=["pilldrops", "pilldrops.*", "sandforge", "sandforge.*",
+                                    "yoursandbox", "yoursandbox.*"]),
+    python_requires=">=3.8",
+    install_requires=["requests>=2.28"],
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3",
+    ],
+)

pilldrops-1.0.0/tests/test_integration.py

@@ -0,0 +1,94 @@
+"""Live integration test: boots bin/sandboxd and drives the SDK against it.
+
+Skips automatically if the binary or python `requests` is unavailable.
+"""
+import os
+import re
+import subprocess
+import sys
+import time
+import tempfile
+import shutil
+import socket
+
+import pytest
+
+requests = pytest.importorskip("requests")
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+BIN = os.path.join(ROOT, "bin", "sandboxd")
+sys.path.insert(0, os.path.join(ROOT, "sdk", "python"))
+
+
+def _free_port():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    p = s.getsockname()[1]
+    s.close()
+    return p
+
+
+@pytest.fixture(scope="module")
+def server():
+    if not os.path.exists(BIN):
+        pytest.skip("bin/sandboxd not built; run: go build -o bin/sandboxd ./cmd/sandboxd/")
+    port = _free_port()
+    data = tempfile.mkdtemp(prefix="sbd-it-")
+    proc = subprocess.Popen(
+        [BIN],
+        env={**os.environ, "PORT": str(port), "SANDBOXD_DATA": data},
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+    )
+    key = None
+    deadline = time.time() + 15
+    while time.time() < deadline:
+        line = proc.stdout.readline()
+        if not line:
+            continue
+        m = re.search(r"(sf_live_[a-f0-9]+)", line)
+        if m:
+            key = m.group(1)
+            break
+    assert key, "did not capture first-run API key from server output"
+    base = f"http://127.0.0.1:{port}"
+    for _ in range(50):
+        try:
+            if requests.get(base + "/health", timeout=1).ok:
+                break
+        except requests.RequestException:
+            time.sleep(0.1)
+    yield base, key
+    proc.terminate()
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+    shutil.rmtree(data, ignore_errors=True)
+
+
+def test_sdk_end_to_end(server):
+    base, key = server
+    os.environ["E2B_API_URL"] = base
+    os.environ["E2B_API_KEY"] = key
+    import importlib
+    import yoursandbox.sandbox as sbmod
+    importlib.reload(sbmod)
+    Sandbox = sbmod.Sandbox
+
+    sb = Sandbox.create(template="python-3.11")
+    try:
+        assert sb.run("echo sdk-ok").stdout.strip() == "sdk-ok"
+
+        sb.filesystem.write("a.txt", "hello")
+        assert sb.filesystem.read("a.txt") == "hello"
+
+        names = [e["name"] for e in sb.filesystem.list(".")]
+        assert "a.txt" in names
+
+        sb.filesystem.move("a.txt", "b.txt")
+        assert sb.filesystem.stat("b.txt")["name"] == "b.txt"
+
+        sb.filesystem.remove("b.txt")
+
+        assert "vcpu_seconds" in sb.metrics()
+    finally:
+        sb.kill()

pilldrops-1.0.0/tests/test_sandbox.py

@@ -0,0 +1,92 @@
+"""Unit tests for the sandforge SDK against a tiny in-process mock API."""
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from sandforge import Sandbox  # noqa: E402
+
+
+class _Handler(BaseHTTPRequestHandler):
+    created_body = None
+    exec_bodies = []
+
+    def log_message(self, *_):
+        pass
+
+    def _json(self, code, obj):
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(obj).encode())
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(n)
+        if self.path == "/v1/sandboxes":
+            _Handler.created_body = json.loads(raw)
+            self._json(201, {"id": "sb_test", "template": "node-20",
+                             "status": "running", "url": "https://x/preview/sb_test/3000/"})
+        elif self.path.endswith("/exec"):
+            _Handler.exec_bodies.append(json.loads(raw))
+            self._json(200, {"stdout": "hello\n", "stderr": "", "exit_code": 0})
+        elif self.path.endswith("/files"):
+            self._json(200, {})
+        else:
+            self._json(200, {"ok": True})
+
+    def do_DELETE(self):
+        self._json(200, {"status": "destroyed"})
+
+
+@pytest.fixture
+def server(monkeypatch):
+    _Handler.created_body = None
+    _Handler.exec_bodies = []
+    httpd = HTTPServer(("127.0.0.1", 0), _Handler)
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    base = f"http://127.0.0.1:{httpd.server_address[1]}"
+    monkeypatch.setenv("SANDFORGE_API_URL", base)
+    monkeypatch.setenv("SANDFORGE_API_KEY", "sfc_test")
+    yield base
+    httpd.shutdown()
+
+
+def test_create_forwards_all_flags(server):
+    with Sandbox.create(template="node-20", image="ghcr.io/me/app:1",
+                        start="npm run dev", ports=[3000, 8080],
+                        env={"NODE_ENV": "production"}, vcpu=2, mem_mb=1024,
+                        storage_mb=4096, timeout=600) as sb:
+        b = _Handler.created_body
+        assert b["image"] == "ghcr.io/me/app:1"
+        assert b["start"] == "npm run dev"
+        assert b["ports"] == [3000, 8080]
+        assert b["env"] == ["NODE_ENV=production"]
+        assert b["vcpu"] == 2 and b["memory_mb"] == 1024 and b["storage_mb"] == 4096
+        assert b["timeout"] == 600
+        # Preview URL comes straight from the create response.
+        assert sb.url == "https://x/preview/sb_test/3000/"
+
+
+def test_run_and_run_code(server):
+    with Sandbox.create() as sb:
+        r = sb.run("echo hello")
+        assert r.ok and r.stdout == "hello\n"
+        sb.run_code("print('hi')", lang="python")
+        # run_code writes a workspace file then execs `python3 <file>`.
+        assert any("python3 _sf_" in e["cmd"] for e in _Handler.exec_bodies)
+
+
+def test_upload_directory_tars(server, tmp_path):
+    (tmp_path / "a.txt").write_text("A")
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "sub" / "b.txt").write_text("B")
+    with Sandbox.create() as sb:
+        sb.upload(str(tmp_path), "app")
+        # A directory upload untars server-side into the workspace.
+        assert any("tar -xzf" in e["cmd"] and "app" in e["cmd"] for e in _Handler.exec_bodies)

pilldrops-1.0.0/yoursandbox/__init__.py

@@ -0,0 +1,4 @@
+from .sandbox import Sandbox, ExecResult, Templates, APIKeys
+
+__all__ = ["Sandbox", "ExecResult", "Templates", "APIKeys"]
+__version__ = "0.3.0"

pilldrops-1.0.0/yoursandbox/sandbox.py

@@ -0,0 +1,277 @@
+"""
+E2B Sandbox SDK — Full Python client for the Sandbox Platform.
+
+Usage:
+    from yoursandbox import Sandbox
+
+    with Sandbox.create() as sb:
+        sb.run("pip install requests -q")
+        result = sb.run("python -c 'import requests; print(requests.__version__)'")
+        print(result.stdout)
+
+        sb.filesystem.write("hello.txt", "Hello World!")
+        files = sb.filesystem.list("/")
+        print(files)
+"""
+import logging
+import os
+import requests
+from dataclasses import dataclass
+from typing import Optional, List, Dict
+
+logger = logging.getLogger("yoursandbox")
+
+BASE = os.environ.get("E2B_API_URL", os.environ.get("SANDBOX_API_URL", "http://localhost:8080"))
+
+
+@dataclass
+class ExecResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    truncated: bool = False
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0
+
+    def raise_on_error(self) -> "ExecResult":
+        if not self.success:
+            raise RuntimeError(f"Command failed (exit {self.exit_code}):\n{self.stderr}")
+        return self
+
+
+class _Filesystem:
+    """Filesystem operations for a sandbox."""
+
+    def __init__(self, sandbox_id: str, session: requests.Session, base: str):
+        self._id = sandbox_id
+        self._s = session
+        self._base = base
+
+    def write(self, path: str, content: "str | bytes") -> None:
+        if isinstance(content, str): content = content.encode()
+        self._s.post(f"{self._base}/v1/sandboxes/{self._id}/files",
+            params={"path": path}, data=content,
+            headers={"Content-Type": "application/octet-stream"}, timeout=30).raise_for_status()
+
+    def read(self, path: str) -> str:
+        r = self._s.get(f"{self._base}/v1/sandboxes/{self._id}/files",
+            params={"path": path}, timeout=30)
+        if r.status_code == 404: raise FileNotFoundError(f"No such file: {path}")
+        r.raise_for_status()
+        return r.text
+
+    def list(self, path: str = "/") -> List[Dict]:
+        r = self._s.get(f"{self._base}/v1/sandboxes/{self._id}/filesystem/list",
+            params={"path": path}, timeout=10)
+        r.raise_for_status()
+        body = r.json()
+        # Server wraps entries as {"entries":[…]}; return the bare list so callers
+        # can iterate DirEntry dicts as the type hint promises.
+        return body.get("entries", body) if isinstance(body, dict) else body
+
+    def mkdir(self, path: str) -> None:
+        self._s.post(f"{self._base}/v1/sandboxes/{self._id}/filesystem/mkdir",
+            json={"path": path}, timeout=10).raise_for_status()
+
+    def move(self, source: str, destination: str) -> None:
+        self._s.post(f"{self._base}/v1/sandboxes/{self._id}/filesystem/move",
+            json={"src": source, "dst": destination}, timeout=10).raise_for_status()
+
+    def remove(self, path: str) -> None:
+        self._s.post(f"{self._base}/v1/sandboxes/{self._id}/filesystem/remove",
+            json={"path": path}, timeout=10)
+
+    def stat(self, path: str) -> Dict:
+        r = self._s.get(f"{self._base}/v1/sandboxes/{self._id}/filesystem/stat",
+            params={"path": path}, timeout=10)
+        if r.status_code == 404: raise FileNotFoundError(f"No such file: {path}")
+        r.raise_for_status()
+        return r.json()
+
+
+class _Process:
+    """Process management for a sandbox."""
+
+    def __init__(self, sandbox_id: str, session: requests.Session, base: str):
+        self._id = sandbox_id
+        self._s = session
+        self._base = base
+
+    def list(self) -> List[Dict]:
+        r = self._s.get(f"{self._base}/v1/sandboxes/{self._id}/process/list", timeout=10)
+        r.raise_for_status()
+        return r.json()
+
+    def signal(self, pid: int, signal: str = "SIGTERM") -> None:
+        self._s.post(f"{self._base}/v1/sandboxes/{self._id}/process/signal",
+            json={"pid": pid, "signal": signal}, timeout=10).raise_for_status()
+
+    def kill(self, pid: int) -> None:
+        self.signal(pid, "SIGKILL")
+
+
+class Sandbox:
+    """Secure isolated sandbox for code execution."""
+
+    _BASE = BASE
+
+    def __init__(self, sandbox_id: str, session: requests.Session, info: dict = None):
+        self.id = sandbox_id
+        self._session = session
+        self._info = info or {}
+        self.filesystem = _Filesystem(sandbox_id, session, self._BASE)
+        self.process = _Process(sandbox_id, session, self._BASE)
+
+    @property
+    def url(self) -> str:
+        return self._info.get("url", f"{self._BASE}/sandbox/{self.id}/")
+
+    @property
+    def template(self) -> str:
+        return self._info.get("template", "")
+
+    @property
+    def boot_ms(self) -> int:
+        return self._info.get("boot_ms", 0)
+
+    @property
+    def app_url(self) -> Optional[str]:
+        return self._info.get("app_url")
+
+    @classmethod
+    def create(cls, template: str = "python-3.11", timeout: int = 300,
+               api_key: Optional[str] = None,
+               files: Optional[List[Dict]] = None,
+               setup: Optional[List[str]] = None,
+               start: Optional[str] = None,
+               port: Optional[int] = None) -> "Sandbox":
+        key = api_key or os.environ.get("E2B_API_KEY") or os.environ.get("SANDBOX_API_KEY")
+        session = requests.Session()
+        if key: session.headers["Authorization"] = f"Bearer {key}"
+
+        body = {"template": template, "timeout": timeout}
+        if files: body["files"] = files
+        if setup: body["setup"] = setup
+        if start: body["start"] = start
+        if port: body["port"] = port
+
+        resp = session.post(f"{cls._BASE}/v1/sandboxes", json=body, timeout=120)
+        if resp.status_code == 401: raise PermissionError("Invalid API key")
+        if resp.status_code == 429: raise RuntimeError("Server busy")
+        if not resp.ok: raise RuntimeError(f"Create failed ({resp.status_code}): {resp.text}")
+
+        data = resp.json()
+        sb = cls(sandbox_id=data["id"], session=session, info=data)
+
+        try:
+            info_resp = session.get(f"{cls._BASE}/v1/sandboxes/{data['id']}", timeout=10)
+            if info_resp.ok: sb._info.update(info_resp.json())
+        except requests.RequestException as e:
+            logger.debug("Failed to fetch sandbox info after create: %s", e)
+
+        return sb
+
+    def run(self, cmd: str, cwd: str = "", timeout: int = 30) -> ExecResult:
+        resp = self._session.post(f"{self._BASE}/v1/sandboxes/{self.id}/exec",
+            json={"cmd": cmd, "cwd": cwd, "timeout": timeout}, timeout=timeout + 15)
+        if resp.status_code == 404: raise RuntimeError(f"Sandbox {self.id} not found")
+        if resp.status_code == 403: raise PermissionError(f"Forbidden: sandbox {self.id}")
+        if not resp.ok: raise RuntimeError(f"Exec failed: {resp.text}")
+        d = resp.json()
+        return ExecResult(stdout=d["stdout"], stderr=d["stderr"],
+                          exit_code=d["exit_code"], truncated=d.get("truncated", False))
+
+    def info(self) -> dict:
+        resp = self._session.get(f"{self._BASE}/v1/sandboxes/{self.id}", timeout=10)
+        resp.raise_for_status()
+        self._info = resp.json()
+        return self._info
+
+    def pause(self) -> dict:
+        r = self._session.post(f"{self._BASE}/v1/sandboxes/{self.id}/pause", timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def resume(self) -> dict:
+        r = self._session.post(f"{self._BASE}/v1/sandboxes/{self.id}/resume", timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def set_timeout(self, seconds: int) -> dict:
+        r = self._session.post(f"{self._BASE}/v1/sandboxes/{self.id}/timeout",
+            json={"timeout": seconds}, timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def refresh(self) -> dict:
+        r = self._session.post(f"{self._BASE}/v1/sandboxes/{self.id}/refresh", timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def logs(self) -> list:
+        r = self._session.get(f"{self._BASE}/v1/sandboxes/{self.id}/logs", timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def metrics(self) -> dict:
+        r = self._session.get(f"{self._BASE}/v1/sandboxes/{self.id}/metrics", timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def history(self) -> list:
+        r = self._session.get(f"{self._BASE}/v1/sandboxes/{self.id}/history", timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def kill(self) -> None:
+        try:
+            self._session.delete(f"{self._BASE}/v1/sandboxes/{self.id}", timeout=10)
+        except requests.RequestException as e:
+            logger.debug("Failed to kill sandbox %s: %s", self.id, e)
+
+    def __enter__(self): return self
+    def __exit__(self, *_): self.kill()
+    def __repr__(self): return f"Sandbox(id={self.id!r}, template={self.template!r})"
+
+
+class Templates:
+    """List sandbox templates. Template CRUD is not yet exposed by the server."""
+
+    def __init__(self, base_url: str = None, api_key: str = None):
+        self._base = base_url or BASE
+        self._s = requests.Session()
+        key = api_key or os.environ.get("E2B_API_KEY", "")
+        if key: self._s.headers["Authorization"] = f"Bearer {key}"
+
+    def list(self) -> list:
+        return self._s.get(f"{self._base}/v1/templates", timeout=10).json()
+
+    def get(self, template_id: str) -> dict:
+        raise NotImplementedError("server exposes only GET /v1/templates (list)")
+
+    def create(self, *_, **__) -> dict:
+        raise NotImplementedError("template creation is not supported by sandboxd yet")
+
+    def update(self, *_, **__) -> dict:
+        raise NotImplementedError("template update is not supported by sandboxd yet")
+
+    def build(self, *_, **__) -> dict:
+        raise NotImplementedError("template build is not supported by sandboxd yet")
+
+    def delete(self, *_, **__) -> None:
+        raise NotImplementedError("template delete is not supported by sandboxd yet")
+
+
+class APIKeys:
+    """Manage API keys."""
+
+    def __init__(self, base_url: str = None, api_key: str = None):
+        self._base = base_url or BASE
+        self._s = requests.Session()
+        key = api_key or os.environ.get("E2B_API_KEY", "")
+        if key: self._s.headers["Authorization"] = f"Bearer {key}"
+
+    def list(self) -> list:
+        return self._s.get(f"{self._base}/v1/keys", timeout=10).json()
+
+    def create(self, name: str = "default") -> dict:
+        r = self._s.post(f"{self._base}/v1/keys", json={"name": name}, timeout=10)
+        r.raise_for_status(); return r.json()
+
+    def revoke(self, key_id: str) -> None:
+        self._s.delete(f"{self._base}/v1/keys/{key_id}", timeout=10)