How to find a sandbox by name

Call Sandbox.getOrCreate("dev"); it returns the sandbox that holds the name, woken if paused, or creates one when none does.

On Runtime a name is a handle you can reach from any process, any day, with no id to store. It stays yours while the sandbox can still run, paused included, so getOrCreate gives an agent or a user the same machine, files and memory each time. A paused one wakes for the call, usually in about half a second, and between uses it costs $0.08 per decimal GB of saved state a month (pricing, checked 25 September 2026).

Get it, or make it

TypeScriptimport { Sandbox } from "withruntime";const dev = await Sandbox.getOrCreate("dev", { idlePauseSeconds: 900, diskMiB: 8192 });console.log(dev.id, dev.info.reused ? "found it" : "made a new one");await dev.exec("git -C /workspace/app pull || true");// The next process, or tomorrow, gets the same sandbox and its files.

Pythonfrom withruntime import Sandboxdev = Sandbox.get_or_create("dev", idle_pause_seconds=900, disk_mib=8192)print(dev.id, "found it" if dev.info.get("reused") else "made a new one")dev.exec("git -C /workspace/app pull || true")

Terminalid=$(runtime sandbox create --name dev --get-or-create --idle-pause 900)runtime sandbox exec dev -- git -C /workspace/app pull   # the name works as the id

The options you pass apply only when it creates one. A sandbox that already has the name comes back as it is: woken if paused, and restarted if it was stopped and persistent.

Look one up without creating

List with a name filter. It finds nothing, rather than making a sandbox, when no live sandbox holds the name:

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const page = await runtime.sandboxes.list({ name: "dev" });const [dev] = page.data;console.log(dev ? `${dev.id} is ${dev.state}` : "no sandbox is called dev");

Pythonfrom withruntime import Runtimeruntime = Runtime()found = runtime.sandboxes.list(name="dev").to_list()print(f"{found[0].id} is {found[0].state}" if found else "no sandbox is called dev")

In the CLI a name works wherever an id does, in every runtime sandbox command, and ssh dev.runtime reaches it once runtime sandbox ssh config --install has run (SSH and editors).

How names behave

Mistakes to avoid

• Catching name_taken and retrying with a new name. That leaves the first sandbox behind, still billed whether it runs or sleeps. Use getOrCreate, or read the holder from the error:

TypeScriptimport { ConflictError, Sandbox } from "withruntime";try {  await Sandbox.create({ name: "dev" });} catch (error) {  if (error instanceof ConflictError && error.code === "name_taken")    console.log("dev is", error.details?.sandboxId);  else throw error;}

• One name for many users. A name is unique in the account, so give each user or task its own, such as dev-${userId}, and use labels for grouping.
• Expecting new options on a found sandbox. getOrCreate does not resize or reconfigure the holder. Change what update() can change (name, labels, idle pause, automatic wake, persistence), or stop it and create afresh.
• Looking for a stopped sandbox by name. Once an ordinary sandbox stops, the name is free. Keep one around with persistent: true (keep a sandbox running).

Related

• Label and list sandboxes to find many at once.
• Pause when idle, which pairs with a named sandbox.
• Per-user dev environments, one name per user.
• Sandboxes by name in the SDK reference.

Facts on this page were checked on 25 September 2026.