# What is an ephemeral environment?

An ephemeral environment is an isolated copy of a system. It is created for one
task, branch or pull request, and deleted when that work ends.

**On Runtime, an ephemeral environment is a sandbox: a Firecracker microVM that
starts from a machine already booted and bills nothing once it stops.** A
clean machine for each task repeats no install when its image already holds
the packages.

## Why it matters for AI agents

A shared, long-lived environment collects state. This includes packages that
one task installed, files that another task left behind, and processes that
nobody stopped. For an agent, this state is worse than clutter. It makes
results differ between runs, and it lets one user's task see another user's
data. Starting every task on a fresh machine and deleting it afterward removes
both problems. It also makes an eval or a test run repeatable.

## Ephemeral on Runtime

| Need                              | How Runtime does it                                                                           |
| --------------------------------- | --------------------------------------------------------------------------------------------- |
| Created per task                  | `Sandbox.create()`, with no required arguments                                                |
| Deleted when the work ends        | `delete()`, or `await using` and Python's `with`, which also delete it on error               |
| Deleted even if your code crashes | A host-enforced time limit with `onLeaseEnd: "delete"`                                        |
| Same start every time             | A [custom image](/docs/images) or a [snapshot](/glossary/sandbox-snapshot)                    |
| Found and cleaned up by group     | `labels`, then `sandboxes.list({ labels })`                                                   |
| Shown to a reviewer               | A private HTTPS [preview URL](/glossary/preview-url) for one port                             |
| Many at the same time             | 100 concurrent sandboxes on a paid account; four without credit |

Move anything that must outlive the environment before the environment stops.
A stopped sandbox is not a backup ([lifetimes](/docs/security#lifetimes-and-storage)).
Store that data on a volume instead. A volume outlives every sandbox, and
Runtime backs it up off its server every day
([volume backups](/docs/storage#volume-backups)).

## One environment per pull request

```ts
import { Runtime } from "withruntime";

const runtime = new Runtime();
const labels = { repo: "shop", pr: "418" };
const env = await runtime.sandboxes.create({ labels, timeoutSeconds: 1800, onLeaseEnd: "stop" });
await env.exec("git --version", { check: true });

// When the PR closes, or from a cleanup job: stop everything running for it.
const running = await runtime.sandboxes.list({ labels, state: ["running"] });
for await (const sbx of running) await sbx.stop();
```

```python
from withruntime import Runtime

runtime = Runtime()
labels = {"repo": "shop", "pr": "418"}
with runtime.sandboxes.create(labels=labels, timeout_seconds=1800, on_lease_end="stop") as env:
    env.exec("git --version")
```

The time limit is a safety net. If the CI job stops before the block ends, the
sandbox still stops when `timeoutSeconds` runs out.

## Related

- [Per-user dev environments](/use-cases/per-user-dev-environments)
- [How to extend a sandbox's time limit](/how-to/extend-a-sandbox-lease)
- [What is a preview URL?](/glossary/preview-url)
- [Agent evals and SWE-bench](/use-cases/agent-evals-and-swe-bench)

Facts on this page were checked on 25 October 2026.