forkd 0.1.2__tar.gz

forkd-0.1.2/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: forkd
+Version: 0.1.2
+Summary: Open-source fork-on-write microVM sandbox primitive (E2B-compatible surface)
+Author-email: Deeplethe <info@deeplethe.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/deeplethe/forkd
+Project-URL: Source, https://github.com/deeplethe/forkd
+Project-URL: Issues, https://github.com/deeplethe/forkd/issues
+Keywords: sandbox,firecracker,microvm,fork,ai-agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# forkd — Python SDK
+
+E2B-compatible sandbox API backed by [forkd](https://github.com/deeplethe/forkd).
+
+```python
+from forkd import Sandbox
+
+with Sandbox() as sandbox:
+    result = sandbox.commands.run("python3 -c 'import numpy; print(numpy.zeros(3))'")
+    print(result.stdout)        # [0. 0. 0.]
+    print(result.exit_code)     # 0
+```
+
+Or with explicit lifecycle:
+
+```python
+sandbox = Sandbox()
+result = sandbox.commands.run("echo hello")
+sandbox.kill()
+```
+
+## Bonus: warmed-state eval
+
+If your snapshot parent imported numpy, you can skip subprocess overhead
+and use the warmed PID-1 interpreter directly:
+
+```python
+with Sandbox() as sandbox:
+    out = sandbox.eval("numpy.zeros(5).tolist()")   # ~8 ms
+    # vs commands.run("python3 -c '...'") which is ~108 ms (fresh subprocess)
+```
+
+## Requirements
+
+The `forkd` Rust CLI must be installed and on `PATH`, plus a parent snapshot
+must already exist (`forkd snapshot --tag pyagent ...`). See the main
+[README](https://github.com/deeplethe/forkd) for the full setup.
+
+## Status
+
+Pre-alpha. Currently supports:
+- `Sandbox()` / `Sandbox.create()` — spawn one sandbox
+- `sandbox.commands.run(cmd)` — run command, get stdout/stderr/exit_code
+- `sandbox.eval(expr)` — eval Python in warmed PID 1
+- `sandbox.kill()` — terminate
+
+Not yet (blocked on issues #1 + #4):
+- Multiple concurrent `Sandbox()` instances (all share parent's MAC/IP)
+- `sandbox.files.read/write` — filesystem operations
+- Streaming output

forkd-0.1.2/README.md

@@ -0,0 +1,50 @@
+# forkd — Python SDK
+
+E2B-compatible sandbox API backed by [forkd](https://github.com/deeplethe/forkd).
+
+```python
+from forkd import Sandbox
+
+with Sandbox() as sandbox:
+    result = sandbox.commands.run("python3 -c 'import numpy; print(numpy.zeros(3))'")
+    print(result.stdout)        # [0. 0. 0.]
+    print(result.exit_code)     # 0
+```
+
+Or with explicit lifecycle:
+
+```python
+sandbox = Sandbox()
+result = sandbox.commands.run("echo hello")
+sandbox.kill()
+```
+
+## Bonus: warmed-state eval
+
+If your snapshot parent imported numpy, you can skip subprocess overhead
+and use the warmed PID-1 interpreter directly:
+
+```python
+with Sandbox() as sandbox:
+    out = sandbox.eval("numpy.zeros(5).tolist()")   # ~8 ms
+    # vs commands.run("python3 -c '...'") which is ~108 ms (fresh subprocess)
+```
+
+## Requirements
+
+The `forkd` Rust CLI must be installed and on `PATH`, plus a parent snapshot
+must already exist (`forkd snapshot --tag pyagent ...`). See the main
+[README](https://github.com/deeplethe/forkd) for the full setup.
+
+## Status
+
+Pre-alpha. Currently supports:
+- `Sandbox()` / `Sandbox.create()` — spawn one sandbox
+- `sandbox.commands.run(cmd)` — run command, get stdout/stderr/exit_code
+- `sandbox.eval(expr)` — eval Python in warmed PID 1
+- `sandbox.kill()` — terminate
+
+Not yet (blocked on issues #1 + #4):
+- Multiple concurrent `Sandbox()` instances (all share parent's MAC/IP)
+- `sandbox.files.read/write` — filesystem operations
+- Streaming output

forkd-0.1.2/forkd/__init__.py

@@ -0,0 +1,10 @@
+"""forkd — open-source fork-on-write microVM sandbox primitive.
+
+This Python SDK provides an E2B-compatible Sandbox API. Under the hood,
+each Sandbox is a forked microVM child managed by the `forkd` Rust CLI.
+"""
+
+from .sandbox import CommandResult, Sandbox
+
+__version__ = "0.0.1"
+__all__ = ["Sandbox", "CommandResult"]

forkd-0.1.2/forkd/sandbox.py

@@ -0,0 +1,190 @@
+"""E2B-compatible Sandbox wrapper around forkd's guest agent."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import socket
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Optional, Sequence, Union
+
+
+@dataclass
+class CommandResult:
+    """Result of `sandbox.commands.run(...)`. Mirrors E2B's API."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+class _CommandsProxy:
+    """Implements the `sandbox.commands` namespace from E2B's API."""
+
+    def __init__(self, sandbox: "Sandbox") -> None:
+        self._sandbox = sandbox
+
+    def run(
+        self,
+        cmd: Union[str, Sequence[str]],
+        timeout: int = 30,
+    ) -> CommandResult:
+        """Run a command inside the sandbox and return its output.
+
+        `cmd` can be a string (executed via `sh -c`) or a list/tuple of
+        argv tokens (executed directly).
+        """
+        if isinstance(cmd, str):
+            args = ["/bin/sh", "-c", cmd]
+        else:
+            args = list(cmd)
+        resp = self._sandbox._send({"action": "exec", "args": args, "timeout": timeout})
+        if "error" in resp and "stdout" not in resp:
+            return CommandResult(stdout="", stderr=resp["error"], exit_code=1)
+        return CommandResult(
+            stdout=resp.get("stdout", ""),
+            stderr=resp.get("stderr", ""),
+            exit_code=int(resp.get("exit_code", -1)),
+        )
+
+
+class Sandbox:
+    """Open one forked microVM sandbox, E2B-compatible surface.
+
+    Example
+    -------
+    >>> with Sandbox() as sb:
+    ...     print(sb.commands.run("echo hi").stdout)
+    hi
+    """
+
+    DEFAULT_TAG = os.environ.get("FORKD_TAG", "pyagent")
+    DEFAULT_TARGET = os.environ.get("FORKD_TARGET", "10.42.0.2:8888")
+
+    def __init__(
+        self,
+        tag: Optional[str] = None,
+        target: Optional[str] = None,
+        timeout: int = 30,
+        *,
+        spawn: bool = True,
+    ) -> None:
+        self.tag = tag or self.DEFAULT_TAG
+        self.target = target or self.DEFAULT_TARGET
+        self.timeout = timeout
+        self.commands = _CommandsProxy(self)
+        self._fork_proc: Optional[subprocess.Popen] = None
+        if spawn:
+            self._spawn()
+
+    # ----- public API -----------------------------------------------------
+
+    def eval(self, code: str) -> object:
+        """Evaluate a Python expression against the warmed PID-1 interpreter.
+
+        This is *not* part of E2B's API but is the killer move of forkd:
+        the parent VM's Python interpreter already imported numpy etc.,
+        so simple `eval` calls return in single-digit milliseconds vs
+        ~100 ms for a fresh `python3 -c "..."` subprocess.
+        """
+        resp = self._send({"action": "eval", "code": code})
+        if "error" in resp:
+            raise RuntimeError(f"forkd eval: {resp['error']}")
+        return resp.get("result")
+
+    def ping(self) -> dict:
+        """Probe the guest agent. Returns dict with 'pong' and 'numpy_version'."""
+        return self._send({"action": "ping"})
+
+    @classmethod
+    def create(cls, *args, **kwargs) -> "Sandbox":
+        """Alias for `Sandbox(...)` matching E2B's `Sandbox.create()` style."""
+        return cls(*args, **kwargs)
+
+    def kill(self) -> None:
+        """Terminate the underlying forked microVM."""
+        if self._fork_proc is None:
+            return
+        self._fork_proc.terminate()
+        try:
+            self._fork_proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self._fork_proc.kill()
+        self._fork_proc = None
+
+    # ----- context manager ------------------------------------------------
+
+    def __enter__(self) -> "Sandbox":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.kill()
+
+    # ----- internals ------------------------------------------------------
+
+    def _spawn(self) -> None:
+        if shutil.which("forkd") is None:
+            raise RuntimeError(
+                "the `forkd` Rust CLI must be on PATH. "
+                "Build it with `cargo build --release -p forkd-cli` and add "
+                "target/release to PATH."
+            )
+
+        # Capture stderr so we can show why a fork failed.
+        self._fork_proc = subprocess.Popen(
+            [
+                "forkd",
+                "fork",
+                "--tag",
+                self.tag,
+                "-n",
+                "1",
+                "--settle-secs",
+                "3600",
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+        )
+
+        # Poll the agent until it responds (~150 ms typical).
+        deadline = time.time() + 30
+        last_err: Optional[Exception] = None
+        while time.time() < deadline:
+            try:
+                self.ping()
+                return
+            except (OSError, socket.error) as e:
+                last_err = e
+                # If forkd itself died, bubble its stderr up — that's the
+                # actually useful information.
+                rc = self._fork_proc.poll() if self._fork_proc else None
+                if rc is not None and rc != 0:
+                    err_bytes = self._fork_proc.stderr.read() if self._fork_proc.stderr else b""
+                    raise RuntimeError(
+                        f"forkd fork --tag {self.tag} exited with code {rc}:\n"
+                        f"{err_bytes.decode(errors='replace')}"
+                    )
+                time.sleep(0.1)
+        self.kill()
+        raise RuntimeError(
+            f"sandbox didn't come up at {self.target} within 30s "
+            f"(last error: {last_err})"
+        )
+
+    def _send(self, msg: dict) -> dict:
+        host, _, port_s = self.target.rpartition(":")
+        port = int(port_s)
+        with socket.create_connection((host, port), timeout=5) as s:
+            s.settimeout(self.timeout + 5)
+            s.sendall((json.dumps(msg) + "\n").encode())
+            s.shutdown(socket.SHUT_WR)
+            buf = bytearray()
+            while True:
+                chunk = s.recv(65536)
+                if not chunk:
+                    break
+                buf.extend(chunk)
+        return json.loads(buf.decode())

forkd-0.1.2/forkd.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: forkd
+Version: 0.1.2
+Summary: Open-source fork-on-write microVM sandbox primitive (E2B-compatible surface)
+Author-email: Deeplethe <info@deeplethe.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/deeplethe/forkd
+Project-URL: Source, https://github.com/deeplethe/forkd
+Project-URL: Issues, https://github.com/deeplethe/forkd/issues
+Keywords: sandbox,firecracker,microvm,fork,ai-agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# forkd — Python SDK
+
+E2B-compatible sandbox API backed by [forkd](https://github.com/deeplethe/forkd).
+
+```python
+from forkd import Sandbox
+
+with Sandbox() as sandbox:
+    result = sandbox.commands.run("python3 -c 'import numpy; print(numpy.zeros(3))'")
+    print(result.stdout)        # [0. 0. 0.]
+    print(result.exit_code)     # 0
+```
+
+Or with explicit lifecycle:
+
+```python
+sandbox = Sandbox()
+result = sandbox.commands.run("echo hello")
+sandbox.kill()
+```
+
+## Bonus: warmed-state eval
+
+If your snapshot parent imported numpy, you can skip subprocess overhead
+and use the warmed PID-1 interpreter directly:
+
+```python
+with Sandbox() as sandbox:
+    out = sandbox.eval("numpy.zeros(5).tolist()")   # ~8 ms
+    # vs commands.run("python3 -c '...'") which is ~108 ms (fresh subprocess)
+```
+
+## Requirements
+
+The `forkd` Rust CLI must be installed and on `PATH`, plus a parent snapshot
+must already exist (`forkd snapshot --tag pyagent ...`). See the main
+[README](https://github.com/deeplethe/forkd) for the full setup.
+
+## Status
+
+Pre-alpha. Currently supports:
+- `Sandbox()` / `Sandbox.create()` — spawn one sandbox
+- `sandbox.commands.run(cmd)` — run command, get stdout/stderr/exit_code
+- `sandbox.eval(expr)` — eval Python in warmed PID 1
+- `sandbox.kill()` — terminate
+
+Not yet (blocked on issues #1 + #4):
+- Multiple concurrent `Sandbox()` instances (all share parent's MAC/IP)
+- `sandbox.files.read/write` — filesystem operations
+- Streaming output

forkd-0.1.2/forkd.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+forkd/__init__.py
+forkd/sandbox.py
+forkd.egg-info/PKG-INFO
+forkd.egg-info/SOURCES.txt
+forkd.egg-info/dependency_links.txt
+forkd.egg-info/top_level.txt

forkd-0.1.2/forkd.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forkd-0.1.2/forkd.egg-info/top_level.txt

@@ -0,0 +1 @@
+forkd

forkd-0.1.2/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forkd"
+version = "0.1.2"
+description = "Open-source fork-on-write microVM sandbox primitive (E2B-compatible surface)"
+readme = "README.md"
+authors = [{name = "Deeplethe", email = "info@deeplethe.com"}]
+license = {text = "Apache-2.0"}
+requires-python = ">=3.9"
+keywords = ["sandbox", "firecracker", "microvm", "fork", "ai-agents"]
+
+[project.urls]
+Homepage = "https://github.com/deeplethe/forkd"
+Source = "https://github.com/deeplethe/forkd"
+Issues = "https://github.com/deeplethe/forkd/issues"
+
+[tool.setuptools]
+packages = ["forkd"]

forkd-0.1.2/setup.cfg

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