What is an ephemeral environment?
An ephemeral environment is an isolated copy of a system 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 in a fraction of a second and bills nothing once it stops. A new one ran its first Python command 351 ms after the create request at the median, measured on 24 September 2026 (speed), so a clean machine per task costs less time than most test suites spend installing packages.
Why it matters for AI agents
A shared, long-lived environment collects state: packages one task installed, files another left behind, a process nobody stopped. For an agent that state is worse than clutter. It makes results differ between runs, and it lets one user's task see another's data. Starting every task on a fresh machine and throwing it away removes both problems, and makes an eval or a test run repeatable.
Ephemeral on Runtime
| Need | How Runtime does it |
|---|---|
| Created per task | Sandbox.create(), no required arguments |
| Deleted when the work ends | stop(), or await using and Python's with, which stop it on error too |
| Deleted even if your code crashes | A host-enforced lease with onLeaseEnd: "stop" |
| Same start every time | A custom image or a snapshot |
| Found and cleaned up by group | labels, then sandboxes.list({ labels }) |
| Shown to a reviewer | A private HTTPS preview URL for one port |
| Many at once | 100 sandboxes at once on a paid account to start; eight on the trial |
Anything that must outlive the environment goes elsewhere before it stops: a stopped sandbox is not a backup (lifetimes). A volume is the place for it: it outlives every sandbox and is backed up off its server every day (volume backups).
One environment per pull request
TypeScriptimport { 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();Pythonfrom withruntime import Runtimeruntime = 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 lease is the safety net: if the CI job dies before the block ends, the
sandbox still stops when timeoutSeconds runs out.
Related
Facts on this page were checked on 25 September 2026.