quickstart

From zero to a running sandbox

Four steps. The whole flow is one dependency and an API key — there is no cluster to provision and nothing to keep warm between requests.

1. 01

   Install the SDK

   TypeScript and Python clients wrap the same HTTP API.

   npm i ironbox
   export IRONBOX_API_KEY=ib_live_...

2. 02

   Create a sandbox

   No pool to warm. The call returns once the VM is already accepting commands.

   const box = await Ironbox.create({
     image: "python:3.12",
     vcpu: 2,
     network: "deny-all",   // or an allowlist
     ttlSeconds: 900,
   });

3. 03

   Run untrusted code

   Stream stdout/stderr, cap CPU and disk, kill the box at any point.

   const res = await box.run("python -c 'print(2**64)'");
   console.log(res.stdout, res.exitCode);

4. 04

   Persist and resume

   The filesystem and process state survive a pause; resume attaches the same disk.

   await box.fs.write("/work/state.json", JSON.stringify(state));
   await box.pause();
   
   const same = await Ironbox.resume(box.id);
   const state2 = await same.fs.read("/work/state.json");