SDKs

TypeScript and Python. Each has one method per MCP tool, with the same names.

TypeScript

@groundbox/sdk, for Node 22 or newer, with no runtime dependencies.

import { Groundbox } from "@groundbox/sdk";

const groundbox = new Groundbox(); // GROUNDBOX_API_KEY, or { apiKey: "gbx_..." }

const sandbox = await groundbox.create_sandbox({ cpus: 2 });
await groundbox.write_file(sandbox.id, "/home/runner/hello.txt", "hi\n");
const result = await groundbox.run_command(sandbox.id, "cat hello.txt && uname -a");
console.log(result.exit_code, result.stdout);

const copy = await groundbox.fork_sandbox(sandbox.id);
await groundbox.delete_sandbox(copy.id);
await groundbox.delete_sandbox(sandbox.id);

Python

groundbox, for Python 3.9 or newer, standard library only.

from groundbox import Groundbox

gb = Groundbox()  # GROUNDBOX_API_KEY, or Groundbox(api_key="gbx_...")

sandbox = gb.create_sandbox(cpus=2)
gb.write_file(sandbox["id"], "/home/runner/hello.txt", "hi\n")
result = gb.run_command(sandbox["id"], "cat hello.txt && uname -a")
print(result["exit_code"], result["stdout"])

copy = gb.fork_sandbox(sandbox["id"])
gb.delete_sandbox(copy["id"])
gb.delete_sandbox(sandbox["id"])

A failed call raises a GroundboxError with the API's code, the HTTP status and the request id.

Create an account and get an API key.