# Move from Runloop to Groundbox

Runloop is winding down its services. [Its transition page](https://docs.runloop.ai/docs/transitions/overview) says transition support for existing customers ran through November 13, 2026. This page maps each part of the Runloop API to Groundbox, with the Runloop call and the Groundbox call side by side in TypeScript and Python, and says plainly where Groundbox has nothing that matches.

A Runloop devbox becomes a Groundbox sandbox: a Linux VM you start, run commands in, move files in and out of, pause and delete through the API. Most calls map one to one. The Runloop calls below are from `@runloop/api-client` and `runloop_api_client` 3.0.0; the Groundbox calls are from `@groundbox/sdk` and the `groundbox` Python package.

## The move, step by step

1. **Copy out what you need while Runloop still answers.** Runloop's transition guides say that devbox IDs, blueprints and snapshots do not move to another provider. Download the files you want to keep with `downloadFile` (a tar of a folder is one call), and save each blueprint's Dockerfile and setup commands. Secret values cannot be read back from Runloop, so take them from where you keep them.
2. **Get a Groundbox key.** Sign up, create an API key and set `GROUNDBOX_API_KEY`. Install `@groundbox/sdk` or `pip install groundbox`. New accounts start on the free plan, with every feature and $5 of usage, no card. Until a card is on file, sandboxes are held to 2 sandboxes at a time, 2 vCPU, 4 GB, 1 hour each.
3. **Rebuild blueprints as templates** (below) and set your secrets with `set_secret`.
4. **Swap the calls** with the map below. The SDK methods are named after the API's own operations, so a search for `runloop.devboxes.` in your code finds every place to change.
5. **Run your agent's own tests** against Groundbox before you move traffic. Compare exit codes and outputs, not timings.

## Concept map

| Runloop | Groundbox | Section |
| --- | --- | --- |
| Devbox | Sandbox: a Linux VM | Code |
| `create` | `create_sandbox` | Code |
| `retrieve`, `list` | `get_sandbox`, `list_sandboxes` | Code |
| `shutdown` | `delete_sandbox`, or `stop_sandbox` to keep the disk | Code |
| `executeSync`, `executeAndAwaitCompletion` | `run_command` | Code |
| `executeAsync`, `executions` | `start_command`, `get_command`, `get_command_output` | Code |
| `readFileContents`, `writeFileContents` | `read_text_file`, `write_file` | Code |
| `uploadFile`, `downloadFile` | `write_file`, `upload_files`, `read_file` | Code |
| `suspend`, `resume` | `pause_sandbox`, `resume_sandbox` | Code |
| `snapshotDisk`, `snapshot_id` | `keep_snapshot`, `snapshot_id` | Code |
| Blueprints | Templates | Code |
| `enableTunnel`, tunnels | `expose_port`, previews | Code |
| `environment_variables` | `env` | Code |
| Secrets, `secrets` | `set_secret`, `env_from_secrets` | Code |
| `gateways`, `mcp` credentials | **No equivalent** | Workaround |
| `code_mounts`, code mounts | **No equivalent** | Workaround |
| `file_mounts` | `write_file`, or a template's `files` | Code |
| Object mounts | **No equivalent** | Workaround |
| `resource_size_request`, `custom_cpu_cores` | `cpus`, `memory_gb`, `disk_gb` | Code |
| `architecture: "arm64"` | **No equivalent** | Workaround |
| `keep_alive_time_seconds`, `keepAlive` | `timeout_minutes`, `on_timeout`, `update_sandbox` | Code |
| `after_idle` to suspend | `idle_timeout_seconds` | Code |
| `after_idle` to shut down | **No equivalent** | Workaround |
| Network policies | `allow_hosts`, `deny_hosts` | Code |
| MCP server | Groundbox MCP server | Code |
| Benchmarks and scenarios | **No equivalent** | Workaround |

## Client and key

Both SDKs read the key from the environment. Runloop's REST client is the `Runloop` class (its object SDK, `RunloopSDK`, wraps the same calls). Groundbox's TypeScript and Python clients have the same method names.

```
// Runloop
import Runloop from "@runloop/api-client";
const runloop = new Runloop(); // RUNLOOP_API_KEY

// Groundbox: npm i @groundbox/sdk
import { Groundbox } from "@groundbox/sdk";
const groundbox = new Groundbox(); // GROUNDBOX_API_KEY
```

```
# Runloop
from runloop_api_client import Runloop
runloop = Runloop()  # RUNLOOP_API_KEY

# Groundbox: pip install groundbox
from groundbox import Groundbox
gb = Groundbox()  # GROUNDBOX_API_KEY
```

## Create, get, list and shut down

`create_sandbox` usually returns a running sandbox; commands sent while it is still `queued` wait for it, and `wait_for_sandbox` waits explicitly. A sandbox has no name field: put a name, and anything else you filter on, in `metadata`, which `list_sandboxes` filters by. Runloop's `shutdown` ends a devbox; on Groundbox that is `delete_sandbox`. `stop_sandbox` is the middle ground: the VM goes away, the disk stays, and `start_sandbox` boots it again with the same id.

```
// Runloop
const devbox = await runloop.devboxes.createAndAwaitRunning({
  name: "agent-1",
  launch_parameters: { resource_size_request: "MEDIUM" },
});
await runloop.devboxes.retrieve(devbox.id);
for await (const each of runloop.devboxes.list({ status: "running" })) console.log(each.id);
await runloop.devboxes.shutdown(devbox.id);

// Groundbox
let sandbox = await groundbox.create_sandbox({ cpus: 2, memory_gb: 4, metadata: { name: "agent-1" } });
sandbox = await groundbox.wait_for_sandbox(sandbox.id); // running, or failed with sandbox.error
await groundbox.get_sandbox(sandbox.id);
const { data } = await groundbox.list_sandboxes({ status: "running", metadata: { name: "agent-1" } });
await groundbox.delete_sandbox(sandbox.id);
```

```
# Runloop
devbox = runloop.devboxes.create_and_await_running(
    name="agent-1",
    launch_parameters={"resource_size_request": "MEDIUM"},
)
runloop.devboxes.retrieve(devbox.id)
for each in runloop.devboxes.list(status="running"):
    print(each.id)
runloop.devboxes.shutdown(devbox.id)

# Groundbox
sandbox = gb.create_sandbox(cpus=2, memory_gb=4, metadata={"name": "agent-1"})
sandbox = gb.wait_for_sandbox(sandbox["id"])  # running, or failed with sandbox["error"]
gb.get_sandbox(sandbox["id"])
running = gb.list_sandboxes(status="running", metadata={"name": "agent-1"})["data"]
gb.delete_sandbox(sandbox["id"])
```

## Run a command and wait

`run_command` is Runloop's `executeSync` and `executeAndAwaitCompletion` in one call. A string runs with `sh -c`; a list is a program and its arguments with no shell. The result has `exit_code` (Runloop's `exit_status`), `stdout`, `stderr`, `duration_ms` and `timed_out`. A non-zero exit code is a result, not an error. The wait is `timeout_s`: 60 seconds by default, 3600 at most. For longer work, start the command in the background.

```
// Runloop
const done = await runloop.devboxes.executeAndAwaitCompletion(devbox.id, { command: "python -V" });
console.log(done.exit_status, done.stdout);

// Groundbox
const result = await groundbox.run_command(sandbox.id, "python -V", { timeout_s: 600 });
console.log(result.exit_code, result.stdout, result.stderr);
await groundbox.run_command(sandbox.id, ["git", "commit", "-m", "No shell: $HOME stays as written"]);
```

```
# Runloop
done = runloop.devboxes.execute_and_await_completion(devbox.id, command="python -V")
print(done.exit_status, done.stdout)

# Groundbox
result = gb.run_command(sandbox["id"], "python -V", timeout_s=600)
print(result["exit_code"], result["stdout"], result["stderr"])
gb.run_command(sandbox["id"], ["git", "commit", "-m", "No shell: $HOME stays as written"])
```

## Run a command in the background

`start_command` returns at once with the command's id, like `executeAsync` with its `execution_id`. The command runs on with nobody connected. `get_command` has its `state` (`running`, `exited` or `lost`) and `exit_code`; `get_command_output` reads its output from any point. In Python, `follow_command` yields the output as it comes. In TypeScript, `attach_command` streams it and `kill_command` ends it. [Commands](https://groundbox.dev/docs/sandboxes#commands) has streams, stdin and terminals.

```
// Runloop
const started = await runloop.devboxes.executeAsync(devbox.id, { command: "npm test" });
const finished = await runloop.devboxes.executions.awaitCompleted(devbox.id, started.execution_id);
console.log(finished.exit_status, finished.stdout);

// Groundbox
const command = await groundbox.start_command(sandbox.id, "npm test", { cwd: "/home/runner/app" });
let state = await groundbox.get_command(sandbox.id, command.id);
while (state.state === "running") {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  state = await groundbox.get_command(sandbox.id, command.id);
}
const output = await groundbox.get_command_output(sandbox.id, command.id); // read on from output.seq while output.more
console.log(state.exit_code, output.stdout);
```

```
# Runloop
started = runloop.devboxes.execute_async(devbox.id, command="npm test")
finished = runloop.devboxes.executions.await_completed(started.execution_id, devbox.id)
print(finished.exit_status, finished.stdout)

# Groundbox
command = gb.start_command(sandbox["id"], "npm test", cwd="/home/runner/app")
for part in gb.follow_command(sandbox["id"], command["id"]):
    print(part["stdout"], end="")
print(gb.get_command(sandbox["id"], command["id"])["exit_code"])
```

## Read, write, upload and download files

Runloop takes paths relative to the devbox user's home folder. Groundbox takes absolute paths, and the home folder is `/home/runner` on Groundbox's own image. `write_file` takes text or bytes, so it covers both `writeFileContents` and `uploadFile`, and makes parent folders. `read_file` returns bytes and `read_text_file` text. The TypeScript SDK's `upload_files` sends a whole folder as one archive. For a folder on the way out, run `tar` in the sandbox and read the archive.

```
// Runloop
await runloop.devboxes.writeFileContents(devbox.id, { file_path: "notes.txt", contents: "hi\n" });
const text = await runloop.devboxes.readFileContents(devbox.id, { file_path: "notes.txt" });
await runloop.devboxes.uploadFile(devbox.id, { path: "data.csv", file: fs.createReadStream("data.csv") });
const response = await runloop.devboxes.downloadFile(devbox.id, { path: "out.tar" });
const tarball = new Uint8Array(await response.arrayBuffer());

// Groundbox: absolute paths; /home/runner is the home folder
await groundbox.write_file(sandbox.id, "/home/runner/notes.txt", "hi\n");
const notes = await groundbox.read_text_file(sandbox.id, "/home/runner/notes.txt");
await groundbox.write_file(sandbox.id, "/home/runner/data.csv", await readFile("data.csv"));
const bytes = await groundbox.read_file(sandbox.id, "/home/runner/out.tar");
await groundbox.upload_files(sandbox.id, "/home/runner/app", [
  { path: "package.json", content: await readFile("package.json") },
  { path: "src/index.ts", content: await readFile("src/index.ts") },
]);
```

```
# Runloop
runloop.devboxes.write_file_contents(devbox.id, file_path="notes.txt", contents="hi\n")
text = runloop.devboxes.read_file_contents(devbox.id, file_path="notes.txt")
runloop.devboxes.upload_file(devbox.id, path="data.csv", file=open("data.csv", "rb"))
runloop.devboxes.download_file(devbox.id, path="out.tar").write_to_file("out.tar")

# Groundbox: absolute paths; /home/runner is the home folder
gb.write_file(sandbox["id"], "/home/runner/notes.txt", "hi\n")
notes = gb.read_text_file(sandbox["id"], "/home/runner/notes.txt")
gb.write_file(sandbox["id"], "/home/runner/data.csv", open("data.csv", "rb").read())
open("out.tar", "wb").write(gb.read_file(sandbox["id"], "/home/runner/out.tar"))
```

## Suspend and resume

`pause_sandbox` keeps the sandbox's memory, disk and running processes, and `resume_sandbox` carries on where it stopped. `stop_sandbox` keeps only the disk, and `start_sandbox` boots a fresh VM from it. Either way only storage is billed while it waits, at $0.05 per GB-month. [Pause and resume](https://groundbox.dev/docs/sandboxes#pause) has the details.

```
// Runloop
await runloop.devboxes.suspend(devbox.id);
await runloop.devboxes.awaitSuspended(devbox.id);
await runloop.devboxes.resume(devbox.id);
await runloop.devboxes.awaitRunning(devbox.id);

// Groundbox: pause keeps memory, disk and running processes
await groundbox.pause_sandbox(sandbox.id);
await groundbox.resume_sandbox(sandbox.id);
// Or keep only the disk, and boot it again later
await groundbox.stop_sandbox(sandbox.id);
await groundbox.start_sandbox(sandbox.id);
```

```
# Runloop
runloop.devboxes.suspend(devbox.id)
runloop.devboxes.await_suspended(devbox.id)
runloop.devboxes.resume(devbox.id)
runloop.devboxes.await_running(devbox.id)

# Groundbox: pause keeps memory, disk and running processes
gb.pause_sandbox(sandbox["id"])
gb.resume_sandbox(sandbox["id"])
# Or keep only the disk, and boot it again later
gb.stop_sandbox(sandbox["id"])
gb.start_sandbox(sandbox["id"])
```

## Snapshots

Runloop's `snapshotDisk` becomes `keep_snapshot`, and both start a new box from `snapshot_id`. A Groundbox snapshot holds the sandbox's memory and running processes as well as its disk, and a sandbox started from it has the snapshot's size. Kept snapshots are on every plan. Runloop snapshots cannot be imported: rebuild the state from a template, or copy the files across. [Snapshots](https://groundbox.dev/docs/sandboxes#snapshots) and the [time machine](https://groundbox.dev/docs/sandboxes#time-machine) cover save points and rewind.

```
// Runloop
const disk = await runloop.devboxes.snapshotDisk(devbox.id, { name: "deps-installed" });
const fromDisk = await runloop.devboxes.createAndAwaitRunning({ snapshot_id: disk.id });

// Groundbox: waits until the snapshot is ready
const snapshot = await groundbox.keep_snapshot({ sandbox_id: sandbox.id, label: "deps-installed" });
const copy = await groundbox.create_sandbox({ snapshot_id: snapshot.id });
const { data: snapshots } = await groundbox.list_snapshots();
await groundbox.delete_snapshot(snapshot.id);
```

```
# Runloop
disk = runloop.devboxes.snapshot_disk(devbox.id, name="deps-installed")
from_disk = runloop.devboxes.create_and_await_running(snapshot_id=disk.id)

# Groundbox: waits until the snapshot is ready
snapshot = gb.keep_snapshot(sandbox["id"], label="deps-installed")
copy = gb.create_sandbox(snapshot_id=snapshot["id"])
snapshots = gb.list_snapshots()["data"]
gb.delete_snapshot(snapshot["id"])
```

## Blueprints become templates

A template is a disk built once, from a public image, a Dockerfile or Groundbox's own image, plus `apt`, `pip` and `npm` packages, `files` and `run` commands. A blueprint's `dockerfile` carries over as it is, and its `system_setup_commands` become `run`. Sandboxes of the template's own size start from a warm snapshot of it.

```
// Runloop
await runloop.blueprints.createAndAwaitBuildCompleted({
  name: "py-ml",
  dockerfile: "FROM python:3.12-slim",
  system_setup_commands: ["pip install numpy pandas"],
});
const fromBlueprint = await runloop.devboxes.createAndAwaitRunning({ blueprint_name: "py-ml" });

// Groundbox
await groundbox.create_template({
  name: "py-ml",
  dockerfile: "FROM python:3.12-slim",
  run: ["pip install numpy pandas"], // or pip: ["numpy", "pandas"]
});
for await (const line of groundbox.follow_template_logs("py-ml", 1)) console.log(line.text);
if ((await groundbox.get_template("py-ml")).status !== "ready") throw new Error("the build failed");
const fromTemplate = await groundbox.create_sandbox({ template: "py-ml" });
```

```
# Runloop
runloop.blueprints.create_and_await_build_complete(
    name="py-ml",
    dockerfile="FROM python:3.12-slim",
    system_setup_commands=["pip install numpy pandas"],
)
from_blueprint = runloop.devboxes.create_and_await_running(blueprint_name="py-ml")

# Groundbox
gb.create_template(
    name="py-ml",
    dockerfile="FROM python:3.12-slim",
    run=["pip install numpy pandas"],  # or pip=["numpy", "pandas"]
)
for line in gb.follow_template_logs("py-ml", 1):
    print(line["text"])
assert gb.get_template("py-ml")["status"] == "ready"
from_template = gb.create_sandbox(template="py-ml")
```

- **Build context:** a template's Dockerfile has no context folder, so `COPY` and `ADD` of local files fail. Put the files in `files`, or build the image yourself and push it to the [Groundbox registry](https://groundbox.dev/docs/registry), then start from it with `image`.
- **Base blueprints:** a template cannot build on another template. Repeat the base's steps in each template, or build the shared base as an image, push it to the registry and start each template from that image.
- **Build arguments:** there are none; write the values into the Dockerfile. Build-time secrets are the template's `secrets` field: the steps get them, and the template does not keep them.

[Templates and volumes](https://groundbox.dev/docs/templates) has the rest, and [From a Docker image](https://groundbox.dev/docs/sandboxes#image) starts a sandbox straight from an image with no template.

## Tunnels and ports

A Runloop tunnel becomes a preview: an HTTPS URL for one port in a running sandbox. `auth_mode: "open"` is `public: true`. Without it a preview is private: your team opens it signed in, and anyone else needs its `share_url`, which works for 24 hours. A sandbox can have 10 previews. Previews are on every plan.

```
// Runloop
const tunnel = await runloop.devboxes.enableTunnel(devbox.id, { auth_mode: "open" });
const runloopUrl = `https://3000-${tunnel.tunnel_key}.tunnel.runloop.ai`;

// Groundbox: the app listens on 0.0.0.0
const preview = await groundbox.expose_port(sandbox.id, 3000, { public: true });
console.log(preview.url);
const privateOne = await groundbox.expose_port(sandbox.id, 8080); // team only, plus privateOne.share_url
await groundbox.delete_preview(sandbox.id, 8080);
```

```
# Runloop
tunnel = runloop.devboxes.enable_tunnel(devbox.id, auth_mode="open")
runloop_url = f"https://3000-{tunnel.tunnel_key}.tunnel.runloop.ai"

# Groundbox: the app listens on 0.0.0.0
preview = gb.expose_port(sandbox["id"], 3000, public=True)
print(preview["url"])
private_one = gb.expose_port(sandbox["id"], 8080)  # team only, plus private_one["share_url"]
gb.delete_preview(sandbox["id"], 8080)
```

Runloop's `wake_on_http` is `wake_on_request`: a request to a preview wakes a sandbox that an idle timeout paused. Its `http_keep_alive` needs no setting: preview traffic counts as activity. For a port that is not HTTP, such as a database or SSH, [open a TCP tunnel](https://groundbox.dev/docs/previews#tcp) from the CLI or with `connect_tcp`.

## Environment variables and secrets

`environment_variables` is `env`. Runloop's secrets map one to one: `set_secret` stores a value with your team (it cannot be read back), and `env_from_secrets` takes the same variable-to-secret map as Runloop's `secrets`. `secrets: ["NAME"]` is the short form for a variable of the same name. The API key needs the `secrets:use` scope.

```
// Runloop
await runloop.secrets.create({ name: "GITHUB_TOKEN", value: process.env.GITHUB_TOKEN! });
await runloop.devboxes.create({
  environment_variables: { NODE_ENV: "test" },
  secrets: { GH_TOKEN: "GITHUB_TOKEN" }, // variable name: secret name
});

// Groundbox
await groundbox.set_secret("GITHUB_TOKEN", process.env.GITHUB_TOKEN!);
await groundbox.create_sandbox({
  env: { NODE_ENV: "test" },
  env_from_secrets: { GH_TOKEN: "GITHUB_TOKEN" }, // variable name: secret name
  // or secrets: ["GITHUB_TOKEN"], for a variable of the same name
});
```

```
# Runloop
runloop.secrets.create(name="GITHUB_TOKEN", value=os.environ["GITHUB_TOKEN"])
runloop.devboxes.create(
    environment_variables={"NODE_ENV": "test"},
    secrets={"GH_TOKEN": "GITHUB_TOKEN"},  # variable name: secret name
)

# Groundbox
gb.set_secret("GITHUB_TOKEN", os.environ["GITHUB_TOKEN"])
gb.create_sandbox(
    env={"NODE_ENV": "test"},
    env_from_secrets={"GH_TOKEN": "GITHUB_TOKEN"},  # variable name: secret name
    # or secrets=["GITHUB_TOKEN"], for a variable of the same name
)
```

**No equivalent:** Runloop's gateways keep a credential outside the devbox and add it to requests on the way out. On Groundbox the secret's value is a variable inside the sandbox. To limit what it can reach, give the sandbox an [egress allowlist](https://groundbox.dev/docs/sandboxes#egress) and a key scoped to what the agent needs.

## Code mounts and repositories

**No equivalent:** Groundbox does not clone a repository for you at start. Clone it with a command, with the token in a secret, and run the install step after it. To have the repository in every sandbox, clone it in a template's `run` step with the template's build `secrets`, then `git pull` at start.

```
// Runloop
await runloop.devboxes.createAndAwaitRunning({
  code_mounts: [{ repo_owner: "acme", repo_name: "app", token: process.env.GITHUB_TOKEN, install_command: "npm ci" }],
});

// Groundbox: clone it yourself, with the token from a team secret
const sandbox = await groundbox.create_sandbox({ env_from_secrets: { GH_TOKEN: "GITHUB_TOKEN" } });
await groundbox.run_command(
  sandbox.id,
  'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/acme/app.git" /home/runner/app && cd /home/runner/app && npm ci',
  { timeout_s: 900 },
);
```

```
# Runloop
runloop.devboxes.create_and_await_running(
    code_mounts=[{"repo_owner": "acme", "repo_name": "app", "token": os.environ["GITHUB_TOKEN"], "install_command": "npm ci"}],
)

# Groundbox: clone it yourself, with the token from a team secret
sandbox = gb.create_sandbox(env_from_secrets={"GH_TOKEN": "GITHUB_TOKEN"})
gb.run_command(
    sandbox["id"],
    'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/acme/app.git" /home/runner/app && cd /home/runner/app && npm ci',
    timeout_s=900,
)
```

Runloop's `file_mounts` become `write_file` calls after start, or a template's `files`. Its object mounts have no direct equivalent: keep the data in a [bucket](https://groundbox.dev/docs/storage) and [mount the bucket](https://groundbox.dev/docs/storage#mount) in the sandbox, or use a [volume](https://groundbox.dev/docs/templates#volumes).

## Sizes and resources

Runloop picks a size by name in `launch_parameters`. Groundbox takes the numbers: `cpus` (whole vCPUs, 1 to 16), `memory_gb` (up to 4 GB per vCPU) and `disk_gb` (up to 100; 20 by default, more than any named Runloop size). Every Runloop size has a Groundbox size with the same memory:

| Runloop | vCPU · memory | Groundbox | Per hour |
| --- | --- | --- | --- |
| `X_SMALL` | 0.5 · 1 GiB | `cpus: 1, memory_gb: 1` (Groundbox's smallest is 1 vCPU) | $0.04 |
| `SMALL` | 1 · 2 GiB | `cpus: 1, memory_gb: 2` | $0.04 |
| `MEDIUM` | 2 · 4 GiB | `cpus: 2, memory_gb: 4` | $0.08 |
| `LARGE` | 2 · 8 GiB | `cpus: 2, memory_gb: 8` | $0.08 |
| `X_LARGE` | 4 · 16 GiB | `cpus: 4, memory_gb: 16` | $0.16 |
| `XX_LARGE` | 8 · 32 GiB | `cpus: 8, memory_gb: 32` | $0.32 |

**No equivalent:** half a vCPU, memory above 4 GB per vCPU (Runloop's custom sizes go to 8), and `arm64`: Groundbox sandboxes are x86-64. For a memory-heavy shape, add vCPUs until the memory fits.

## Keep-alive, idle and timeouts

`keep_alive_time_seconds` becomes `timeout_minutes`: 60 minutes by default, up to 720 hours, renewed with `update_sandbox` (Runloop's `keepAlive`). `on_timeout` says what happens then: `delete`, `stop` (keep the disk) or `pause` (keep memory too).

`after_idle` with `on_idle: "suspend"` becomes `idle_timeout_seconds` (at least 30): the sandbox is paused when nothing has used it for that long, and the next call that needs it wakes it. Activity is API calls that reach the VM, commands still running and preview traffic; CPU use counts only with `idle_cpu_percent`.

```
// Runloop
const devbox = await runloop.devboxes.create({
  launch_parameters: {
    keep_alive_time_seconds: 7200,
    after_idle: { idle_time_seconds: 600, on_idle: "suspend" },
  },
});
await runloop.devboxes.keepAlive(devbox.id);

// Groundbox
const sandbox = await groundbox.create_sandbox({
  timeout_minutes: 120,
  on_timeout: "pause", // or "delete" (the default) or "stop"
  idle_timeout_seconds: 600, // paused when idle; the next call that needs it wakes it
});
await groundbox.update_sandbox(sandbox.id, { timeout_minutes: 120 }); // renew: 120 minutes from now
```

```
# Runloop
devbox = runloop.devboxes.create(
    launch_parameters={
        "keep_alive_time_seconds": 7200,
        "after_idle": {"idle_time_seconds": 600, "on_idle": "suspend"},
    },
)
runloop.devboxes.keep_alive(devbox.id)

# Groundbox
sandbox = gb.create_sandbox(
    timeout_minutes=120,
    on_timeout="pause",  # or "delete" (the default) or "stop"
    idle_timeout_seconds=600,  # paused when idle; the next call that needs it wakes it
)
gb.update_sandbox(sandbox["id"], timeout_minutes=120)  # renew: 120 minutes from now
```

**No equivalent:** shutting down on idle. The idle action is pause only. Pair it with `timeout_minutes` and `on_timeout: "delete"` to end a sandbox after a set time, or delete idle sandboxes from your own code. [Idle pause and wake](https://groundbox.dev/docs/sandboxes#idle) has the details.

## Network policies

A Runloop network policy is named and attached by id. On Groundbox the rules sit on the sandbox: `allow_hosts` (these and nothing else) and `deny_hosts` (everything but these), with host names, wildcards and networks. Set them at create, or change them while it runs with `set_egress`. See [Egress allowlist](https://groundbox.dev/docs/sandboxes#egress).

## MCP server

Runloop documents an MCP server for its API. Groundbox's MCP server gives an agent the same sandbox operations as the SDKs, at a hosted URL with OAuth or as a local process with your key:

.mcp.json (hosted)

```
{
  "mcpServers": {
    "groundbox": { "url": "https://mcp.groundbox.dev/mcp" }
  }
}
```

.mcp.json (local)

```
{
  "mcpServers": {
    "groundbox": {
      "command": "npx",
      "args": ["-y", "@groundbox/mcp"],
      "env": { "GROUNDBOX_API_KEY": "gbx_..." }
    }
  }
}
```

[MCP server](https://groundbox.dev/docs/mcp) lists the tools.

## Benchmarks and scenarios

**No equivalent.** Groundbox has no benchmark or scenario API, and no scoring. Runloop's docs say its benchmark product was discontinued. To run an evaluation on Groundbox, keep the harness in your own code: build the task's environment as a template, start one sandbox per task, run the agent and the scorer with `run_command`, and read the results. Flex sandboxes cost half ($0.02 per vCPU-hour) for runs that can wait for room; see [Flex sandboxes](https://groundbox.dev/docs/sandboxes#flex).

## Pricing

Sandboxes are $0.04 per vCPU-hour, billed by the second, with memory up to 4 GB per vCPU included. Disk is not part of a running sandbox's price. A paused or stopped sandbox, and a kept snapshot, is $0.05 per GB-month. The free plan includes $5 of usage; the $20 plan includes $20 a month. See [Pricing](https://groundbox.dev/pricing), and [Groundbox vs Runloop](https://groundbox.dev/compare/runloop) for a side-by-side.
