Rookhold

Run short-lived Python, Node, and Bash code with hard limits—and keep a verifiable receipt of what happened.

Current release: v0.8.0. Downloads and direct SDK packages are available now. Named PyPI and npm installs remain deferred while maintainer registry accounts are activated.

Rookhold is for applications, agents, evaluators, graders, and automations that receive a short piece of code but should not hand it the host machine. It is a bounded job runner—not a persistent workspace, browser environment, remote IDE, or general-purpose cloud sandbox.

Try Rookhold locally

Choose the complete Rookhold app bundle. It contains the unified rookhold command, remote client, MCP adapter, offline verifier, and setup templates.

| Your computer | App bundle | |---|---| | Windows, 64-bit | Download for Windows | | Mac with Apple Silicon | Download for Mac | | Linux x86_64 | Download for Linux |

Extract the archive, then run one trusted local job:

$ rookhold run python 'print(6 * 7)'
42

status       succeeded
network      host
isolation    none
receipt      saved to .rookhold/runs/019…/receipt.json

WARNING: isolation is none; this run did not contain untrusted code.

On macOS or Linux, run chmod +x rookhold rookhold-cli rookhold-mcp rookhold-verify once after extracting. On Windows, use rookhold.exe.

[!WARNING] With no configured endpoint, rookhold run starts a temporary loopback-only service for code you trust. It has host networking and no sandbox boundary. Do not use this mode for hostile or mutually untrusted code.

Connected to a guarded Linux service, the same command can require and report the gVisor boundary:

$ ROOKHOLD_BASE_URL=https://executor.example \
  ROOKHOLD_API_KEY=repl…[redacted] \
  rookhold run python 'print(6 * 7)' \
    --minimum-isolation gvisor-application-kernel
42

status       succeeded
network      disabled
isolation    gvisor-application-kernel
receipt      saved to .rookhold/runs/019…/receipt.json

The CLI explicitly requests allow_network: false; the guarded service must also report disabled networking and the required isolation class.

Read the quickstart · Deploy the secure boundary · Share 60-second feedback

Add Rookhold to an application

The Rookhold SDK is the client library for your code. It does not create a secure Linux execution boundary by itself; point it at a Rookhold service for untrusted workloads.

Python

Install the v0.8.0 release wheel:

pip install https://github.com/sambai-dev/rookhold/releases/download/v0.8.0/rookhold-0.8.0-py3-none-any.whl

from rookhold import Rookhold

result = Rookhold.from_env().run("python", "print(6 * 7)")
print(result.stdout)

TypeScript

Install the v0.8.0 release tarball:

npm install https://github.com/sambai-dev/rookhold/releases/download/v0.8.0/rookhold-0.8.0.tgz

Named PyPI and npm installs are temporarily deferred while maintainer registry accounts are activated. The release-hosted packages above contain the same SDKs.

import { Rookhold } from "rookhold";

const result = await Rookhold.fromEnv().run({
  language: "python",
  code: "print(6 * 7)",
});
console.log(result.stdout);

Python guide · TypeScript guide · API reference

Connect to an existing Rookhold server

The Rookhold client is the smallest download for a person or MCP host that already has a Rookhold endpoint. It does not include the local service.

| Your computer | Standalone client | |---|---| | Windows, 64-bit | Download the Windows client | | Mac with Apple Silicon | Download the Mac client | | Linux x86_64 | Download the Linux client |

Run it normally for the operator terminal, or register the same file with the mcp-server argument in Claude Code, OpenCode, Hermes, or another MCP host. The model never chooses the service URL, API key, language allowlist, or required isolation class.

rookhold setup claude-code
rookhold setup opencode
rookhold setup hermes

Adding Rookhold does not disable a host's built-in shell or other execution tools. Remove or deny those routes when a model must cross only the Rookhold boundary.

CLI guide · MCP guide · Integration templates

What Rookhold does

For every submitted job, Rookhold:

1. authenticates the caller and checks admission policy;
2. applies server-controlled time, memory, process, file, and output limits;
3. runs the job using the configured execution provider;
4. preserves bounded output, events, cancellation state, and artifacts; and
5. records the effective runtime posture and receipt.

The API and persisted store remain the source of truth. The CLI, SDKs, MCP adapter, and dashboard are views over the same contracts.

Three useful recipes

• Run an LLM-generated function—submit generated source without evaluating it inside the agent process.
• Apply a user-defined JSON transform—send structured input and read structured output.
• Grade code against hidden tests—bound evaluation time and retain the result record.

See every recipe or start from the Next.js and FastAPI examples.

Is Rookhold right for the task?

| Use Rookhold for | Keep using the normal workspace for | |---|---| | short generated or user-supplied scripts | editing a repository | | stateless transforms, checks, and evaluators | persistent files and package installation | | jobs needing limits, cancellation, or evidence | browsers, ports, and long-running services | | execution behind a separately controlled API | trusted development already isolated well enough |

Using both is normal. Rookhold owns short execution policy and evidence; it does not replace the rest of an agent or application runtime.

Before running untrusted code

The guarded production profile is Linux x86_64-only. macOS, Windows, and other Linux architectures support only the unisolated same-trust development provider. Production uses a dedicated Linux x86_64 VM, pinned gVisor runsc, a private root filesystem, cgroup v2, scoped credentials, and non-skipping containment checks.

The service container has host-equivalent outer authority even though each job runs inside a separate gVisor workload. Do not place it on a shared multi-tenant Docker host.

Read the security boundary before accepting untrusted jobs.

Documentation

• Getting started
• Installation choices
• Execution model
• Receipts and verification
• Deployment and operations
• Compatibility
• Feedback
• Release process

Contributing

Start with CONTRIBUTING.md. The repository separates:

• Tier A—docs, examples, and integrations;
• Tier B—SDK, CLI, and public API work; and
• Tier C—authentication, execution, storage, receipts, and isolation.

Tier A changes should not inherit security-core ceremony. Tier C changes must prove the root invariant, regression, adversarial cases, and final exact-head validation.

Build from source

Prebuilt releases are the normal path. Contributors need Rust 1.98 and the job runtimes they intend to test:

git clone https://github.com/sambai-dev/rookhold.git
cd rookhold
cargo build --locked --workspace

Run the complete checks from CONTRIBUTING.md before opening a pull request.

License

Rookhold is released under the MIT License.