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.