hyperbox-mcp 0.2.1__tar.gz

hyperbox_mcp-0.2.1/LICENSE

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

hyperbox_mcp-0.2.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: hyperbox-mcp
+Version: 0.2.1
+Summary: MCP server that runs LLM-generated code in a disposable Docker/Podman container before it touches your real project.
+Author: Sanjay Jat
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sanjay7089/hyperbox-mcp
+Project-URL: Repository, https://github.com/Sanjay7089/hyperbox-mcp
+Project-URL: Documentation, https://github.com/Sanjay7089/hyperbox-mcp/tree/main/docs
+Project-URL: Issues, https://github.com/Sanjay7089/hyperbox-mcp/issues
+Project-URL: Changelog, https://github.com/Sanjay7089/hyperbox-mcp/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,sandbox,docker,podman,llm,agent,code-execution,container
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp<5,>=4.0.2
+Requires-Dist: llm-sandbox[docker,podman]<0.4,>=0.3.44
+Dynamic: license-file
+
+# HyperBox
+
+**An MCP server that runs LLM-generated code in a disposable container,
+so your agent can test its own work before it touches your project.**
+
+Your agent writes code and wants to run it. By default that happens on
+your machine, against your files, with your credentials. Usually fine.
+Occasionally it is `rm -rf`, a global install that breaks another
+project, or a script that quietly talks to production.
+
+HyperBox gives the agent somewhere else to run it:
+
+```
+create_sandbox()  →  run(code)  →  run(fixed code)  →  destroy_sandbox()
+```
+
+The agent gets real stdout, stderr and exit codes, so it can fix its code
+and try again somewhere that cannot hurt you — and only then touch your
+project.
+
+## What your agent gets
+
+Three tools, and nothing else:
+
+| Tool | What it does |
+|---|---|
+| `create_sandbox(language, backend, environment)` | A persistent, disposable container. Returns a `sandbox_id`. |
+| `run(sandbox_id, code, libraries, timeout)` | Executes code. Returns `{stdout, stderr, exit_code, success, timed_out}`. |
+| `destroy_sandbox(sandbox_id)` | Tears it down. Idempotent, and confirmed against the engine before claiming success. |
+
+Plus a `hyperbox://capabilities` resource publishing the exact limits, so
+an agent can read them instead of discovering them by failing.
+
+Within one sandbox the filesystem and installed packages persist between
+runs; variables do not, because each run is a fresh process. Write what
+you need to keep to `/work`.
+
+## What is enforced
+
+Set by the server, not negotiable by the model, and **read back off the
+real container** after creation — so a sandbox is never described as
+limited when it is not:
+
+| | |
+|---|---|
+| Memory | 1 GB, OOM-killed with a legible reason |
+| CPU | 1 core |
+| Processes | 128 PIDs |
+| Timeout | 60 s ceiling |
+| Network | detached before any submitted code runs |
+| Host filesystem | never mounted |
+| Container engine socket | never mounted |
+| Scratch space | `/work`, 64 MB tmpfs, discarded with the sandbox |
+
+Declared dependencies are the one network exception: they install in a
+separate step that reattaches the network, runs a no-op program with the
+package list, and detaches again before your code runs.
+
+## Built on
+
+- **[FastMCP](https://pypi.org/project/fastmcp/)** — the MCP server layer
+  (stdio, JSON-RPC).
+- **[llm-sandbox](https://pypi.org/project/llm-sandbox/)** — container
+  session management, behind a `Runtime` protocol so the execution
+  backend stays replaceable.
+- **Docker or Podman** — whichever you have running. Both are supported
+  and both pass the full acceptance suite.
+
+Two runtime dependencies, no compiled extensions, one `py3-none-any`
+wheel for every platform.
+
+## Install
+
+```bash
+pip install hyperbox-mcp
+```
+
+Or, to get an isolated interpreter and a stable executable path — which
+is what an MCP client needs:
+
+```bash
+uv tool install hyperbox-mcp     # or: pipx install hyperbox-mcp
+```
+
+Requires **Python 3.11+** and **Docker or Podman** running.
+
+Check the machine and fetch the sandbox image once, so a multi-gigabyte
+download never happens inside a client request:
+
+```bash
+hyperbox doctor --pull
+```
+
+## Use it: Cursor
+
+Generate the config rather than typing it — the failure mode of getting a
+path wrong is silent, with no tools appearing and no error anywhere:
+
+```bash
+hyperbox config --format cursor > .vscode/mcp.json
+```
+
+That writes:
+
+```json
+{
+  "servers": {
+    "hyperbox": {
+      "command": "/Users/you/.local/bin/hyperbox",
+      "args": [],
+      "env": { "PATH": "/Users/you/.local/bin:/usr/local/bin:/usr/bin:/bin" }
+    }
+  }
+}
+```
+
+Restart Cursor — MCP configs are read at launch. Then ask it to run
+something:
+
+> Use hyperbox to check whether this regex handles the empty string.
+
+A typical exchange looks like:
+
+```
+create_sandbox(language="python")
+  → {"sandbox_id": "6f5eaaefb938", ...}
+
+run(sandbox_id="6f5eaaefb938", code="import re; print(re.match(r'^\\d+$', ''))")
+  → {"stdout": "None\n", "exit_code": 0, "success": true}
+
+destroy_sandbox(sandbox_id="6f5eaaefb938")
+  → {"status": "destroyed"}
+```
+
+### Other clients
+
+```bash
+hyperbox config --format json          # Claude Desktop, and most clients
+hyperbox config --format antigravity   # Antigravity
+hyperbox config --format yaml          # Continue-based clients
+```
+
+`PATH` in the generated config includes your container CLI's directory,
+because clients launch servers with a trimmed environment and Docker is
+frequently invisible otherwise.
+
+## Custom environments
+
+Start sandboxes from a heavier image so you do not pay a package install
+every time:
+
+```bash
+hyperbox build data-science --custom ./Dockerfile
+hyperbox envs
+```
+
+Your agent then asks for it by name:
+`create_sandbox(environment="data-science")`. A running server picks up a
+new environment without a restart.
+
+Building is a CLI action on purpose. A build runs whatever the Dockerfile
+says — arbitrary commands, as root, with network, under none of a
+sandbox's limits — so an agent can *use* an environment but cannot create
+one.
+
+## Where the boundary sits
+
+HyperBox is developer containment, not an isolation guarantee:
+
+- **Local containers share your host's kernel.** No gVisor, no
+  Firecracker, no VM boundary of its own.
+- **Not a multi-tenant boundary.** Do not run untrusted third-party code
+  as a service with it.
+- **Code runs as root inside the container.** A non-root user breaks the
+  execution backend; that root is confined by the container boundary,
+  `no-new-privileges`, and the limits above.
+- **Dependencies come from the public index** and are not vetted.
+
+If you need a hard boundary for genuinely adversarial code, you want a VM
+or microVM sandbox, not a local container.
+
+## Commands
+
+```
+hyperbox                 Start the MCP server on stdio (default)
+hyperbox doctor          Check this machine can run sandboxes
+hyperbox config          Print a ready-to-paste MCP client config
+hyperbox envs            List environments create_sandbox can use
+hyperbox build <name>    Build an environment from a Dockerfile
+hyperbox logs            Show the server log
+```
+
+---
+
+MIT licensed. Source, full documentation and issue tracker:
+**[github.com/Sanjay7089/hyperbox-mcp](https://github.com/Sanjay7089/hyperbox-mcp)**

hyperbox_mcp-0.2.1/PYPI.md

@@ -0,0 +1,196 @@
+# HyperBox
+
+**An MCP server that runs LLM-generated code in a disposable container,
+so your agent can test its own work before it touches your project.**
+
+Your agent writes code and wants to run it. By default that happens on
+your machine, against your files, with your credentials. Usually fine.
+Occasionally it is `rm -rf`, a global install that breaks another
+project, or a script that quietly talks to production.
+
+HyperBox gives the agent somewhere else to run it:
+
+```
+create_sandbox()  →  run(code)  →  run(fixed code)  →  destroy_sandbox()
+```
+
+The agent gets real stdout, stderr and exit codes, so it can fix its code
+and try again somewhere that cannot hurt you — and only then touch your
+project.
+
+## What your agent gets
+
+Three tools, and nothing else:
+
+| Tool | What it does |
+|---|---|
+| `create_sandbox(language, backend, environment)` | A persistent, disposable container. Returns a `sandbox_id`. |
+| `run(sandbox_id, code, libraries, timeout)` | Executes code. Returns `{stdout, stderr, exit_code, success, timed_out}`. |
+| `destroy_sandbox(sandbox_id)` | Tears it down. Idempotent, and confirmed against the engine before claiming success. |
+
+Plus a `hyperbox://capabilities` resource publishing the exact limits, so
+an agent can read them instead of discovering them by failing.
+
+Within one sandbox the filesystem and installed packages persist between
+runs; variables do not, because each run is a fresh process. Write what
+you need to keep to `/work`.
+
+## What is enforced
+
+Set by the server, not negotiable by the model, and **read back off the
+real container** after creation — so a sandbox is never described as
+limited when it is not:
+
+| | |
+|---|---|
+| Memory | 1 GB, OOM-killed with a legible reason |
+| CPU | 1 core |
+| Processes | 128 PIDs |
+| Timeout | 60 s ceiling |
+| Network | detached before any submitted code runs |
+| Host filesystem | never mounted |
+| Container engine socket | never mounted |
+| Scratch space | `/work`, 64 MB tmpfs, discarded with the sandbox |
+
+Declared dependencies are the one network exception: they install in a
+separate step that reattaches the network, runs a no-op program with the
+package list, and detaches again before your code runs.
+
+## Built on
+
+- **[FastMCP](https://pypi.org/project/fastmcp/)** — the MCP server layer
+  (stdio, JSON-RPC).
+- **[llm-sandbox](https://pypi.org/project/llm-sandbox/)** — container
+  session management, behind a `Runtime` protocol so the execution
+  backend stays replaceable.
+- **Docker or Podman** — whichever you have running. Both are supported
+  and both pass the full acceptance suite.
+
+Two runtime dependencies, no compiled extensions, one `py3-none-any`
+wheel for every platform.
+
+## Install
+
+```bash
+pip install hyperbox-mcp
+```
+
+Or, to get an isolated interpreter and a stable executable path — which
+is what an MCP client needs:
+
+```bash
+uv tool install hyperbox-mcp     # or: pipx install hyperbox-mcp
+```
+
+Requires **Python 3.11+** and **Docker or Podman** running.
+
+Check the machine and fetch the sandbox image once, so a multi-gigabyte
+download never happens inside a client request:
+
+```bash
+hyperbox doctor --pull
+```
+
+## Use it: Cursor
+
+Generate the config rather than typing it — the failure mode of getting a
+path wrong is silent, with no tools appearing and no error anywhere:
+
+```bash
+hyperbox config --format cursor > .vscode/mcp.json
+```
+
+That writes:
+
+```json
+{
+  "servers": {
+    "hyperbox": {
+      "command": "/Users/you/.local/bin/hyperbox",
+      "args": [],
+      "env": { "PATH": "/Users/you/.local/bin:/usr/local/bin:/usr/bin:/bin" }
+    }
+  }
+}
+```
+
+Restart Cursor — MCP configs are read at launch. Then ask it to run
+something:
+
+> Use hyperbox to check whether this regex handles the empty string.
+
+A typical exchange looks like:
+
+```
+create_sandbox(language="python")
+  → {"sandbox_id": "6f5eaaefb938", ...}
+
+run(sandbox_id="6f5eaaefb938", code="import re; print(re.match(r'^\\d+$', ''))")
+  → {"stdout": "None\n", "exit_code": 0, "success": true}
+
+destroy_sandbox(sandbox_id="6f5eaaefb938")
+  → {"status": "destroyed"}
+```
+
+### Other clients
+
+```bash
+hyperbox config --format json          # Claude Desktop, and most clients
+hyperbox config --format antigravity   # Antigravity
+hyperbox config --format yaml          # Continue-based clients
+```
+
+`PATH` in the generated config includes your container CLI's directory,
+because clients launch servers with a trimmed environment and Docker is
+frequently invisible otherwise.
+
+## Custom environments
+
+Start sandboxes from a heavier image so you do not pay a package install
+every time:
+
+```bash
+hyperbox build data-science --custom ./Dockerfile
+hyperbox envs
+```
+
+Your agent then asks for it by name:
+`create_sandbox(environment="data-science")`. A running server picks up a
+new environment without a restart.
+
+Building is a CLI action on purpose. A build runs whatever the Dockerfile
+says — arbitrary commands, as root, with network, under none of a
+sandbox's limits — so an agent can *use* an environment but cannot create
+one.
+
+## Where the boundary sits
+
+HyperBox is developer containment, not an isolation guarantee:
+
+- **Local containers share your host's kernel.** No gVisor, no
+  Firecracker, no VM boundary of its own.
+- **Not a multi-tenant boundary.** Do not run untrusted third-party code
+  as a service with it.
+- **Code runs as root inside the container.** A non-root user breaks the
+  execution backend; that root is confined by the container boundary,
+  `no-new-privileges`, and the limits above.
+- **Dependencies come from the public index** and are not vetted.
+
+If you need a hard boundary for genuinely adversarial code, you want a VM
+or microVM sandbox, not a local container.
+
+## Commands
+
+```
+hyperbox                 Start the MCP server on stdio (default)
+hyperbox doctor          Check this machine can run sandboxes
+hyperbox config          Print a ready-to-paste MCP client config
+hyperbox envs            List environments create_sandbox can use
+hyperbox build <name>    Build an environment from a Dockerfile
+hyperbox logs            Show the server log
+```
+
+---
+
+MIT licensed. Source, full documentation and issue tracker:
+**[github.com/Sanjay7089/hyperbox-mcp](https://github.com/Sanjay7089/hyperbox-mcp)**

hyperbox_mcp-0.2.1/README.md

@@ -0,0 +1,158 @@
+# HyperBox
+
+**An MCP server that runs LLM-generated code in a disposable container,
+so your agent can test its own work before it touches your project.**
+
+[![PyPI](https://img.shields.io/pypi/v/hyperbox-mcp.svg)](https://pypi.org/project/hyperbox-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/hyperbox-mcp.svg)](https://pypi.org/project/hyperbox-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+Your agent writes code and wants to run it. By default that happens on
+your machine, against your files, with your credentials. Usually fine.
+Occasionally it is `rm -rf`, a global install that breaks another
+project, or a script that quietly talks to production.
+
+HyperBox gives the agent somewhere else to run it.
+
+```mermaid
+flowchart LR
+    w["agent writes code"] --> c["create_sandbox()"]
+    c --> r["run(code)"]
+    r -->|"stderr says what broke"| f["run(fixed code)"]
+    f --> r
+    r -->|"it works"| d["destroy_sandbox()"]
+    f -.->|"only now, and only if<br/>you have seen it pass"| host["apply to the real project"]
+```
+
+The loop matters more than any single call: the agent gets real stdout,
+stderr and exit codes, so it can fix its code and try again somewhere
+that cannot hurt you — and only then touch your project.
+
+## Quick start
+
+```bash
+pip install hyperbox-mcp     # or: uv tool install hyperbox-mcp
+hyperbox doctor --pull       # check the machine, fetch the sandbox image
+hyperbox config --format json
+```
+
+Merge that config into your MCP client and restart it. Full instructions,
+including Cursor, Antigravity and Continue-based clients, are in
+**[docs/setup.md](docs/setup.md)**.
+
+Requires Python 3.11+ and either Docker or Podman.
+
+## What your agent gets
+
+| Tool | What it does |
+|---|---|
+| `create_sandbox(language, backend, environment)` | A persistent, disposable container. Returns a `sandbox_id`. |
+| `run(sandbox_id, code, libraries, timeout)` | Executes code. Returns `{stdout, stderr, exit_code, success, timed_out}` — never a bare "it failed". |
+| `destroy_sandbox(sandbox_id)` | Tears it down. Idempotent, and confirmed against the engine before it claims success. |
+
+Plus a `hyperbox://capabilities` resource publishing the exact limits, so
+an agent can read them instead of discovering them by failing.
+
+Within one sandbox, the filesystem and installed packages persist between
+runs; variables do not, because each run is a fresh process. Write what
+you need to keep to `/work`.
+
+## Why use it
+
+- **Generated code runs outside your client's process.** No access to
+  your filesystem, your project, or the container engine.
+- **Limits are server policy, not negotiable by the model** — 1 GB
+  memory, 1 CPU, 128 processes, a 60-second ceiling, capped output. They
+  are read back off the real container, so a sandbox is never *described*
+  as limited when it is not.
+- **The network is sealed** before any submitted code runs. Declared
+  dependencies install in a separate step that closes again afterwards.
+- **Cleanup survives restarts.** Ownership lives in a registry outside
+  your repo, so a restarted server — or a second one your client launched
+  — can still find and destroy a sandbox it did not create.
+- **Failure is reported honestly.** An unreachable engine is an error,
+  not a cheerful "already cleaned up".
+
+## It contains hostile code — the proof, not the promise
+
+`tests/verify_containment.py` runs genuinely dangerous code in a real
+container. Actual output:
+
+```
+PASS  host filesystem is unreachable from inside
+        stdout: 'DENIED: FileNotFoundError'
+PASS  network is unreachable from inside
+        stdout: 'DENIED: OSError'
+PASS  container engine socket is not mounted
+        stdout: 'engine sockets present: []'
+PASS  memory exhaustion is capped, with a legible reason
+        exit_code: 137 | stderr: Killed (SIGKILL): the sandbox exceeded its memory limit of 1g.
+PASS  process explosion is capped by the PID limit
+        stdout: 'DENIED after 126 processes: BlockingIOError'
+PASS  sandbox is destroyed cleanly afterwards
+
+6/6 contained
+```
+
+The fork bomb stopped at 126 processes against a ceiling of 128. Run it
+yourself — that is why it ships as a test.
+
+## Custom environments
+
+Start sandboxes from a heavier image so you do not pay a package install
+every time:
+
+```bash
+hyperbox build data-science --custom ./Dockerfile
+hyperbox envs
+```
+
+Your agent then asks for it by name:
+`create_sandbox(environment="data-science")`. A running server picks up a
+new environment without a restart.
+
+Building is a CLI action on purpose — an agent can use an environment,
+but cannot create one. See [docs/security.md](docs/security.md).
+
+## What it does not do
+
+Be clear-eyed about the boundary:
+
+- **Local containers share your host's kernel.** This is developer
+  containment, not absolute isolation. There is no gVisor, no
+  Firecracker, no VM boundary that HyperBox itself provides.
+- **It is not a multi-tenant boundary.** Do not use it to run untrusted
+  third-party code as a service.
+- **Code runs as root inside the container.** A non-root user was tried
+  and breaks the execution backend; the reasoning is in
+  [docs/security.md](docs/security.md).
+- **Dependencies come from the public index** and are not vetted.
+
+If you need a hard boundary for genuinely adversarial code, you want a VM
+or microVM sandbox, not a local container.
+
+## Documentation
+
+- **[Setup](docs/setup.md)** — install, client configuration, environments, CLI reference
+- **[Security model](docs/security.md)** — what is enforced, how it is proven, what it does not cover
+- **[Troubleshooting](docs/troubleshooting.md)** — when something does not work
+- **[Changelog](CHANGELOG.md)**
+- **[Contributing](CONTRIBUTING.md)**
+
+## Testing
+
+There are no mocks on the sandbox path, on purpose — mocking Docker would
+prove only that the mock works. Every acceptance suite runs against a real
+container:
+
+```bash
+python tests/run_all.py docker      # and: podman
+```
+
+Takes 5–15 minutes. It also asserts that no containers were left behind.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

hyperbox_mcp-0.2.1/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "hyperbox-mcp"
+version = "0.2.1"
+description = "MCP server that runs LLM-generated code in a disposable Docker/Podman container before it touches your real project."
+# PyPI gets its own page: self-contained, no mermaid (PyPI renders it
+# as a raw code block) and no relative links into the repo tree.
+readme = "PYPI.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sanjay Jat" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "sandbox",
+    "docker",
+    "podman",
+    "llm",
+    "agent",
+    "code-execution",
+    "container",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Security",
+    "Topic :: System :: Emulators",
+]
+dependencies = [
+    "fastmcp>=4.0.2,<5",
+    "llm-sandbox[docker,podman]>=0.3.44,<0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/Sanjay7089/hyperbox-mcp"
+Repository = "https://github.com/Sanjay7089/hyperbox-mcp"
+Documentation = "https://github.com/Sanjay7089/hyperbox-mcp/tree/main/docs"
+Issues = "https://github.com/Sanjay7089/hyperbox-mcp/issues"
+Changelog = "https://github.com/Sanjay7089/hyperbox-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+hyperbox = "hyperbox_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

hyperbox_mcp-0.2.1/setup.cfg

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