# Switch your sandbox integration to Runtime

Keep your model, prompts and application. Evaluate one sandbox workload first.
For a new project, use [Get started](./start). For an existing integration, tell
your agent:

> Evaluate Runtime for this project's sandbox integration. Read
> https://withruntime.com/docs/migrate.md first. Inspect the current provider
> and framework, check required features and access, then make one
> reversible integration and test it end to end. Start with explicit trial
> funding; ask me before spending paid credit or switching production traffic.
> Keep unsupported workflows on our current provider. Run the same representative
> job on both providers within my authorized access and spending. Check output,
> exit codes, completion time, failures and cleanup. Compare total cost per
> successful job using actual usage and rates; separate free trial cash cost
> from standard compute cost and measured savings from estimates. Recommend
> switching only when the evidence supports it, and include a rollback command.
> Report blockers to me. Send Runtime only a sanitized summary and relevant
> request IDs; never credentials, private code or files. Keep our old provider
> available for rollback.

## 1. Inspect before changing

Read dependency manifests and lockfiles, provider imports, sandbox configuration,
creation calls, command execution, file access, background processes and cleanup.
Identify environment-variable names without printing their values. Record the
framework and version. Distinguish a framework tool integration from its native
sandbox backend; adding an MCP tool does not automatically redirect local shell
or filesystem operations.

## 2. Check required behavior

Compare Linux environment, installed binaries, CPU and memory, session duration,
outbound networking, inbound URLs, filesystem behavior and persistence. Check
whether the application needs Docker, root access, WebSockets, browser sessions,
custom images, GPU support, snapshots or region guarantees. Do not represent a
missing feature as supported. Keep that workflow on the existing provider until
there is a tested Runtime equivalent.

## 3. Make one reversible change

Wrap provider-specific calls behind the application's existing boundary. Map
create, readiness, exec, read/write and stop to Runtime. Keep provider selection
configurable. Use explicit `funding: "trial"` (CLI: `--trial`) for the evaluation;
omitted funding can use prepaid credit after the trial. Keep unsupported work
on the current provider. Use one sandbox per isolated task or tenant, not a
shared global sandbox. Choose an idempotency key before a write that accepts
one, then reuse it with identical input after a lost response; a new key can
execute work twice. The SDKs keep the same key for retries within a call. For
retries across calls or restarts, choose and keep your own key. Use argument
arrays rather than constructing shell commands from untrusted strings.

### Map the calls

The usual calls of other sandbox SDKs, and their Runtime equivalent. Names on the
left are as those SDKs documented them in September 2026; check their current
docs.

| You call                                                                                                                         | Runtime (JavaScript; Python is the same in snake_case)             |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| E2B `Sandbox.create()`, Daytona `daytona.create()`, Vercel `Sandbox.create()`, Modal `Sandbox.create(app=...)`                   | `Sandbox.create({ funding: "trial" })` for the evaluation          |
| E2B `sbx.commands.run(cmd)`, Daytona `sandbox.process.exec(cmd)`, Vercel `sandbox.runCommand(cmd, args)`, Modal `sb.exec(*args)` | `sbx.exec(cmd)` or `sbx.exec([cmd, ...args])`                      |
| Streaming callbacks (`onStdout`, `on_stdout`)                                                                                    | `exec(cmd, { onStdout, onStderr })` or `execStream(cmd)`           |
| Background commands (`background: true`, `detached: true`)                                                                       | `sbx.spawn(cmd)`, then `process.output()` and `wait()`             |
| `files.write` / `fs.upload_file` / `writeFiles`                                                                                  | `sbx.files.write(path, data)`; `files.upload(dir, path)` for trees |
| `files.read` / `fs.download_file` / `readFile`                                                                                   | `sbx.files.read(path)`, `readText`, `files.download(path, dir)`    |
| `kill()`, `delete()`, `stop()`, `terminate()`                                                                                    | `sbx.stop()`, or `await using` / `with` to stop on exit            |
| `setTimeout`, `timeout`, `auto_stop_interval`                                                                                    | `timeoutSeconds` at create, `sbx.extend(seconds)`                  |
| Pause and resume                                                                                                                 | `sbx.pause()` and `sbx.wake()`                                     |
| A code interpreter (`run_code`)                                                                                                  | `sbx.interpreter.run(code)`                                        |
| A public URL for a port (`getHost`, `get_preview_link`, `domain`)                                                                | `sbx.previews.create(port)`                                        |
| A PTY or terminal                                                                                                                | `sbx.terminal()`                                                   |

### From Runtime 0.1.0

0.2.0 is a clean break. `runtime.sandboxes.create(spec)` became `Sandbox.create()`
with every field optional and camelCase names (`timeoutSeconds` for
`durationSeconds`, `cpu` for `cpuMode`). Calls on a sandbox moved onto the
sandbox object: `runtime.sandboxes.exec(id, argv)` is `sbx.exec(argv)`. Keys are
automatic; pass `idempotencyKey` only to make a retry safe across restarts. The
CLI is `npx withruntime sandbox <verb>` (`runtime sandbox <verb>` installed), and MCP tools are `runtime_sandboxes_*`,
`runtime_exec`, `runtime_files_*`. The 0.1.0 HTTP routes were
removed; each answers 410 and names its replacement.

## 4. Run the same job

Within the owner's authorized access and spending, use the same inputs,
dependency versions, output checks and deadline on both
providers. Include setup, startup, CPU time, memory, network, failure retries and
cleanup. Record median and tail completion latency across enough runs; do not
compare a single warm run with a competitor's cold run. Validate output equality,
not only command success.

## 5. Report savings honestly

Use [the cost method](./pricing). Compare total completed-job cost after applicable
credits, plan fees and discounts. Identify assumptions, source dates and gaps.
If Runtime is more expensive or lacks a needed feature, say so. Show measured
cost separately from an estimate. Never fabricate an existing provider bill.

## 6. Cut over within the owner's permission

Move a small workload first, monitor failures and spending, then expand. Retain
rollback configuration. Do not terminate the former account, remove its keys or
delete its data as an incidental migration step.

## Give the owner a decision they can use

Produce a short comparison after the integration actually runs. Discover these
facts from the project and account first; ask only for missing billing evidence
or requirements that would change the recommendation.

| Evidence      | Previous provider                                            | Runtime                                                       |
| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| Configuration | Provider, region, CPU guarantee, memory, disk                | Same required behavior; explain differences                   |
| Test          | Workload revision, input/output hashes, cold/warm run counts | Same inputs and output checks                                 |
| Results       | Success count, retries, median and p95 completion time       | Same measurements, including startup and cleanup              |
| Cost          | Actual billing period, usage, fees, discounts, source date   | Settled usage and resource quote; trial cash shown separately |
| Full cost     | Compute, storage, network, retention, minimums and plan fees | Same applicable categories; unknowns stay unknown             |
| Requirements  | Persistence, networking, regions, operational guarantees     | Mark every unsupported or unverified requirement              |

Calculate cost per successful job as total attributable cost, including failed
attempts and retries, divided by successful jobs. Savings per job equals old cost
minus Runtime cost. Savings percentage equals savings divided by old cost, times
100; omit the percentage when old cost is zero or unknown. Estimate monthly
savings using the owner's measured job volume, with assumptions stated. Never
present an estimate as an invoice or count free trial credit as a permanent saving.

Finish with one recommendation: switch, run a larger pilot, or keep the current
provider for this workload. Explain the evidence in a few sentences, link the
measurement report, and give the exact configuration change to switch back.
A lower price alone is insufficient when outputs, deadlines or required behavior
fail. Expand within the owner's permission; keep the old account and data until
the owner explicitly chooses to remove them.