# 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](/docs/pricing#paused-storage), checked 25 September 2026).

## Get it, or make it

```ts check
import { 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.
```

```python check
from withruntime import Sandbox

dev = 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")
```

```bash no-run
id=$(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:

```ts
import { 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");
```

```python
from withruntime import Runtime

runtime = 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](/docs/editors)).

## How names behave

| Rule                    | Detail                                                                                       |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| Unique while it can run | Starting, running, paused, or stopped and persistent                                         |
| A second create         | Fails with `409 name_taken`; `details.sandboxId` names the holder when your key can reach it |
| `getOrCreate`           | Answers the holder with `reused: true` instead of `name_taken`                               |
| Stopped for good        | The sandbox gives the name up and keeps it in its own record                                 |
| Rename                  | `sbx.update({ name: "dev-2" })`, or `runtime sandbox update <id> --name dev-2`               |
| Over HTTP               | `POST /v1/sandboxes` with `name` and `getOrCreate: true`; `GET /v1/sandboxes?name=`          |
| Over MCP                | `runtime_sandbox_create` with `name` and `getOrCreate: true`                                 |
| Cost                    | Nothing for the name; a paused holder is billed as paused storage                            |

## 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:

```ts check
import { 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](/how-to/label-and-list-sandboxes) 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](/how-to/keep-a-sandbox-running)).

## Related

- [Label and list sandboxes](/how-to/label-and-list-sandboxes) to find many at
  once.
- [Pause when idle](/how-to/pause-when-idle), which pairs with a named sandbox.
- [Per-user dev environments](/use-cases/per-user-dev-environments), one name per
  user.
- [Sandboxes by name](/docs/javascript#sandboxes-by-name) in the SDK reference.

Facts on this page were checked on 25 September 2026.