<!-- https://withruntime.com/docs/api -->

# HTTPS API reference

One API for every Runtime Cloud product, at `https://api.withruntime.com`.

The SDKs, the CLI and MCP are thin layers over this API. This page is the contract. The machine-readable contract is the public OpenAPI document at `https://api.withruntime.com/v1/openapi.json`. It is generated from the same route definitions that the server validates with.

API version: **0.2.0**.

## Requests

Send the key as a bearer token. Store keys in server-side secret storage. Never put a key in a URL, a browser, or a command line that others can read. A browser uses a [session](#sessions) instead.

```bash no-run
curl https://api.withruntime.com/v1/sandboxes \
  -H "Authorization: Bearer ${RUNTIME_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{}'
```

In a shell, put a variable before a colon in braces: `"${ID}:exec"`. zsh, the macOS default, reads `$ID:e` as a modifier. It then sends `/xec`.

Never use `curl -v` or `--trace` with the key. They print the `Authorization` header.

A key sees and uses only what its own agent made. Another key's sandbox returns 404 `not_found`. An account-wide key sees and uses everything in the account. An owner or admin makes one at [API keys](https://withruntime.com/account/keys), or approves one with `runtime keys create --account-wide`. Such a key's `getOrCreate` can return a sandbox that another key named. A key in a [compartment](./security#compartments) sees only what its compartment's keys made. A full-access key of an owner or admin can make, list and revoke keys with `/v1/keys`. No other key can ([run a swarm](./teams#run-a-swarm)).

```bash no-run
curl -sS "https://api.withruntime.com/v1/sandboxes/${ID}:exec" \
  -H "Authorization: Bearer ${RUNTIME_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -c \"print(sum([125, 250, 375]))\""}'
```

- Resources live at `/v1/<plural>/{id}`. A change that is not a plain update uses `POST /v1/<plural>/{id}:<verb>`, such as `:stop`, `:pause`, `:wake` or `:exec`.
- Field names are camelCase. Times are ISO 8601 in UTC. Money is an integer count of microdollars: 1,000,000 is one US dollar.
- Unknown fields are refused. One response names every wrong field.
- `Prefer: wait=N` (seconds, at most 120) on a change returns once the resource has settled, not immediately. `GET /v1/sandboxes/{id}?waitFor=running&timeoutSeconds=60` waits for a state without polling.

## Responses and errors

Every response includes an `x-request-id` header and a `Server-Timing`
header, `app;dur=12.3`: the time in milliseconds from when the API received the
request until its response headers were ready. Subtract it from the time your
client measured to get the network's share. Every error has one shape:

```json
{
  "error": {
    "code": "no_credit_running_limit",
    "status": 429,
    "message": "An account without credit runs at most 4 sandboxes at once.",
    "hint": "... Stop or pause one you no longer need (runtime sandboxes stop <id>, or pause <id>), or wait for one to end, then retry. ... Adding credit lifts this. Only the account's owner adds credit, at https://withruntime.com/account/billing#add-credit, so tell them what was refused; an agent never adds or spends it on its own. Credit added within 30 days of signing up is matched, up to $1,000 in total. ...",
    "details": {
      "running": ["..."],
      "addCredit": {
        "url": "https://withruntime.com/account/billing#add-credit",
        "by": "owner",
        "givenCreditCounts": true,
        "welcomeMatch": { "withinDays": 30, "upToUsd": 1000 }
      }
    },
    "requestId": "req_0mud1dtgjogtn2z8t6y",
    "retryable": true
  }
}
```

Follow the `hint`. Quote the `requestId` when you report a problem. A 5xx response never includes internal detail. It contains only a fixed message and the request ID.

**`retryable` says whether to send it again.** Every error has it. `true` means the same request, sent again unchanged, may succeed. Such a response always has a `Retry-After` header with the seconds to wait first. The body also has `retryAfterMs` when the wait is exact. `false` means something must change first. The same request gets the same response, and that response never has `Retry-After`. Each code has one status and one `retryable` value. They are listed below and in the OpenAPI document's `x-error-codes`. A code is never renamed, so code that reads `code` keeps working.

**A refusal that adding credit lifts has one shape**, whatever the product. An agent can then tell its person plainly what to do. The code is one of
`no_credit_size_limit`, `no_credit_running_limit`, `no_credit_total_limit`,
`no_credit_kept_limit`, `no_credit_daily_limit`, `no_credit_key_limit`, `no_credit_domain_limit`, `no_credit_capacity_full`, `no_credit_build_limit`,
`included_usage_used_up`, `included_usage_unavailable`, `insufficient_funds`,
`payment_required`, `public_preview_not_allowed` or `connect_not_allowed`:

- `message`: what was refused, and the limit.
- `hint`: what you can do now without credit. Then it gives the one way past the limit. The account's owner adds credit at [Usage & billing](https://withruntime.com/account/billing#add-credit). Credit you add within 30 days of signing up is matched, up to $1,000 in total ([welcome match](./pricing#welcome-match)).
- `details.addCredit`: the same, for code. `givenCreditCounts` is `false` where only paid credit lifts the refusal. That covers public previews, ports beyond 80 and 443, custom domains, public TCP ports and private networks. `welcomeMatch` holds the match's days and dollars.

An agent never adds or spends credit on its own. It tells the owner which limit it met. One exception is an account that the agent opened itself with a wallet. No person pays for that account ([pay with stablecoins](./pricing)). For that account, the `hint` says to add credit yourself. Use `npx withruntime billing topup <usd>` or `POST /v1/billing/topups` with the account's own key. In that case, `details.addCredit` is `{"by": "agent", "command": ..., "api": ...,
"givenCreditCounts": ...}` and has no `url`. `GET /v1/limits` shows which kind of account a key is on (`credit.addedBy`).

A claim code is the way back into such an account if its key is lost. Use `npx withruntime billing claim <code> --new-key`, or `POST https://withruntime.com/api/wallet/rekey` with `{"claimCode": "..."}`. Either returns a new key, shown once. Every other key of the account stops working immediately. A claim code replaces the key at most three times in 24 hours. Each replacement is recorded in the account's audit log (`wallet.key_replaced`). This works only until a person takes the account over. After that, its people make keys on the website. Keep the claim code as secret as the key. `connect_not_allowed` returns no `addCredit` for an organization whose port access Runtime turned off. Credit does not change that refusal.

**A 5xx says whose fault it is.** A message that says the fault is ours, not your request's, was reported to us automatically, with its `requestId`. A 500 is a fault that a retry does not fix. A 502, 503 or 504 clears on its own, so retry it with the same key. Write to us only if it keeps failing. A 501 means a product is switched off on this deployment.

The status follows HTTP's meaning. A client or retry library that reads only the status does the right thing. 409 means a state you must change first, such as a sandbox to wake or a name already held. It can also mean a state that clears by itself. 429 means your own limit: a rate, what runs at the same time, a quota, or a daily cap. 503 means the service is briefly away or out of room.

<!-- error-codes:start (bun packages/cloud/src/api/error-codes-write.ts) -->

| Status | Retryable | Codes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Safe next step                                                                                                                                                                                                                                                                                                                                                  |
| ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | no        | `confirmation_required`, `copies_invalid`, `cursor_ahead`, `disk_shrink`, `env_invalid`, `env_name_reserved`, `env_too_large`, `image_no_command`, `invalid_alert`, `invalid_archive`, `invalid_authority`, `invalid_backup_night`, `invalid_drill`, `invalid_env`, `invalid_host`, `invalid_journal`, `invalid_lease`, `invalid_packages`, `invalid_path`, `invalid_region`, `invalid_request`, `invalid_service`, `port_ambiguous`, `resize_needs_restart`, `scale_invalid`, `size_exceeded`, `switch_keeps_workspace_only`, `terms_required`, `volume_invalid`, `working_dir_invalid`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Fix the request as the message and `details` say                                                                                                                                                                                                                                                                                                                |
| 401    | no        | `invalid_identity`, `unauthorized`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Check the key                                                                                                                                                                                                                                                                                                                                                   |
| 402    | no        | `account_blocked`, `budget_exceeded`, `budget_reached`, `included_usage_unavailable`, `included_usage_used_up`, `insufficient_credit`, `insufficient_funds`, `payment_failed`, `payment_required`, `pilot_ended`, `pilot_hours_used`, `retention_unavailable`, `spending_limit_reached`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | It needs credit or money; the message says which, and `details.addCredit` how                                                                                                                                                                                                                                                                                   |
| 403    | no        | `agent_key_required`, `connect_not_allowed`, `forbidden`, `host_mismatch`, `mode_not_applied`, `network_not_allowed`, `no_person`, `outside_compartment`, `permission_denied`, `plan_required`, `product_in_beta`, `public_preview_not_allowed`, `sandbox_halted`, `secret_not_shared`, `sign_in_unfinished`, `signed_requests_off`, `sso_refused`, `sso_required`, `wrong_source`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | This key or account may not; do not work around it                                                                                                                                                                                                                                                                                                              |
| 404    | no        | `file_not_found`, `image_not_found`, `not_available`, `not_found`, `path_not_found`, `process_not_found`, `route_not_found`, `sandbox_gone`, `snapshot_not_found`, `target_not_found`, `transfer_not_found`, `volume_not_found`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Check the id, name or path                                                                                                                                                                                                                                                                                                                                      |
| 405    | no        | `method_not_allowed`, `wrong_method`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Use a method the path accepts                                                                                                                                                                                                                                                                                                                                   |
| 408    | no        | `download_idle`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Send the request again, faster                                                                                                                                                                                                                                                                                                                                  |
| 408    | yes       | `request_timeout`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Send it again after `Retry-After`, with the same key                                                                                                                                                                                                                                                                                                            |
| 409    | no        | `already_exists`, `already_switched`, `already_topped_up`, `archive_unavailable`, `auto_wake_off`, `blobs_missing`, `browser_failed`, `browser_not_running`, `call_dismissed`, `call_started`, `cell_not_run`, `checksum_mismatch`, `chunk_conflict`, `compartment_not_empty`, `conflict`, `desktop_failed`, `desktop_not_running`, `directory_not_empty`, `file_trace_not_requested`, `file_trace_unavailable`, `fork_failed`, `guest_upgrade_required`, `image_in_use`, `image_unchanged`, `image_unnamed`, `in_use`, `insufficient_storage`, `invalid_state`, `is_a_directory`, `journal_full`, `legacy_email_requires_reconciliation`, `limit_reached`, `memory_full`, `name_conflict`, `name_taken`, `no_credit_kept_limit`, `no_credit_key_limit`, `no_memory_scope`, `no_space`, `not_a_directory`, `not_a_regular_file`, `not_a_terminal`, `not_installed`, `not_pausable`, `not_paused`, `not_resumable`, `not_running`, `notebook_not_running`, `offset_mismatch`, `operation_conflict`, `operation_outcome_unknown`, `payment_used`, `process_running`, `rebase_copy_failed`, `rebase_copy_timeout`, `repository_disconnected`, `repository_taken`, `resize_disk_cold`, `resize_needs_disk`, `resource_stopped`, `restart_unavailable`, `rollback_unavailable`, `root_unavailable`, `sandbox_in_use`, `sandbox_not_paused`, `sandbox_not_running`, `sandbox_paused`, `sandbox_stopped`, `second_step_already_on`, `second_step_not_started`, `second_step_off`, `second_step_required_by_account`, `secrets_mismatch`, `service_conflict`, `service_resume_unavailable`, `session_ended`, `session_open`, `session_stopping`, `size_unchanged`, `snapshot_metadata_changed`, `snapshot_unsupported`, `stdin_closed`, `switch_needs_disk`, `tailscale_joined`, `time_limit_too_short`, `trigger_paused`, `unmount_failed`, `unsupported_operation`, `upload_incomplete`, `version_conflict`, `volume_attached`, `volume_change_refused`, `webhook_disabled` | Change the state the message names (wake, stop, detach, rename), then send it again. A count you hold at its limit (`no_credit_kept_limit`, `no_credit_key_limit`, `limit_reached`, and `quota_exceeded` on what is kept: volumes, images, snapshots, secrets, kept sandboxes) is one too: delete one, or raise the limit; sending it again alone does not help |
| 409    | yes       | `backup_not_ready`, `browser_installing`, `desktop_installing`, `file_changed`, `image_building`, `image_not_ready`, `operation_pending`, `resize_during_snapshot`, `resize_not_halted`, `run_in_progress`, `sandbox_moving`, `sandbox_not_ready`, `snapshot_capturing`, `snapshot_in_progress`, `snapshot_not_ready`, `switch_not_paused`, `volume_not_ready`, `volume_releasing`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Clears by itself: send it again after `Retry-After`, with the same key                                                                                                                                                                                                                                                                                          |
| 410    | no        | `deleted`, `host_lost`, `link_expired`, `link_revoked`, `name_retired`, `secret_revoked`, `snapshot_expired`, `snapshot_lost`, `upgrade_required`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Gone for good: make a new one, or use the name the hint gives                                                                                                                                                                                                                                                                                                   |
| 413    | no        | `body_too_large`, `file_too_large`, `too_large`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Send less, or use the chunked upload                                                                                                                                                                                                                                                                                                                            |
| 415    | no        | `unsupported_media_type`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Send `Content-Type: application/json`                                                                                                                                                                                                                                                                                                                           |
| 416    | no        | `range_not_satisfiable`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Ask for a range inside the file; the message says its length                                                                                                                                                                                                                                                                                                    |
| 422    | no        | `archive_failed`, `cwd_not_found`, `disk_too_small`, `idempotency_conflict`, `idempotency_key_reused`, `image_build_failed`, `image_config_invalid`, `image_limit_too_small`, `image_on_another_host`, `image_platform_unsupported`, `image_port_invalid`, `image_registry_unsupported`, `interpreter_failed`, `invalid_volume_attachment`, `keep_env_refused`, `mcp_cleanup_failed`, `mcp_failed`, `no_credit_size_limit`, `passkey_limit`, `passkey_refused`, `program_not_found`, `recording_failed`, `ref_not_found`, `retention_too_long`, `scale_over_limit`, `second_step_wrong_code`, `subagent_depth`, `tailscale_failed`, `tunnel_overrun`, `tunnel_unavailable`, `unprocessable`, `upload_failed`, `volumes_apart`, `volumes_on_different_hosts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Well formed, but not possible as asked: change what the message names; a program in your sandbox that failed is named in `details`                                                                                                                                                                                                                              |
| 429    | yes       | `account_share_full`, `blob_store_full`, `blob_upload_limit`, `build_in_progress`, `context_limit`, `daily_limit`, `guest_busy`, `no_credit_build_limit`, `no_credit_daily_limit`, `no_credit_domain_limit`, `no_credit_running_limit`, `no_credit_total_limit`, `process_limit`, `quota_exceeded`, `rate_limited`, `resource_limit`, `sandbox_busy`, `second_step_locked`, `startup_application_limit`, `startup_cool_down`, `subagent_quota`, `transfer_limit`, `trial_signup_rate`, `watch_limit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `quota_exceeded` for a limit on what runs at once (`details.limit` `sandbox.count`, `sandbox.vcpu`, `sandbox.memory_mib`, `sandbox.disk_mib`, `tunnel.count` or `instance.count`); on what is kept it is a 409. Your own limit: its rate, what runs at once, a quota or a daily cap. Retry after `Retry-After` with the same key, or end something it counts    |
| 451    | no        | `taken_down`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Taken down after a report; write to support if it was a mistake                                                                                                                                                                                                                                                                                                 |
| 499    | no        | `cancelled`, `client_closed`, `request_cancelled`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | You closed the connection first; nobody read this                                                                                                                                                                                                                                                                                                               |
| 500    | no        | `env_unreadable`, `guest_quarantined`, `history_unreadable`, `internal_error`, `job_failed`, `operation_failed`, `price_unavailable`, `secrets_unconfirmed`, `snapshot_busy`, `snapshot_unusable`, `watch_failed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Our fault, reported to us. Safe to send again with the same key, but it may fail the same way until we fix it                                                                                                                                                                                                                                                   |
| 501    | no        | `delete_unavailable`, `env_unavailable`, `feature_unavailable`, `file_links_unavailable`, `fork_unavailable`, `identity_unavailable`, `network_rules_unavailable`, `network_unavailable`, `previews_unavailable`, `resize_unavailable`, `schema_migration_required`, `secrets_unavailable`, `storage_unavailable`, `switch_image_unavailable`, `switching_paused`, `unavailable`, `unsupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Switched off on this deployment; sending it again does not help                                                                                                                                                                                                                                                                                                 |
| 502    | yes       | `billing_unavailable`, `download_incomplete`, `github_unavailable`, `guest_failed`, `image_unavailable`, `keys_unavailable`, `support_unavailable`, `upstream_failed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | A service behind the API answered badly: retry after `Retry-After` with the same key                                                                                                                                                                                                                                                                            |
| 503    | yes       | `alert_in_flight`, `alert_unavailable`, `api_unavailable`, `base_image_unverified`, `body_stalled`, `builder_outdated`, `busy`, `capacity_unavailable`, `copies_unread`, `desktop_connection_unavailable`, `drill_unalerted`, `drill_unrecorded`, `email_unavailable`, `guest_not_ready`, `heartbeats_unreadable`, `history_unavailable`, `host_busy`, `host_capacity`, `host_memory_pressure`, `host_not_ready`, `host_start_failed`, `host_unavailable`, `host_unknown`, `monitor_unavailable`, `no_capacity`, `no_credit_capacity_full`, `planned_release`, `resize_not_started`, `sandbox_environment_unavailable`, `sandbox_starting`, `sandbox_unreachable`, `secret_withheld`, `signing_unavailable`, `snapshot_restoring`, `switch_undone`, `wake_refused`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Briefly away or out of room: retry after `Retry-After` with the same key (the SDKs do)                                                                                                                                                                                                                                                                          |
| 504    | no        | `cell_timed_out`, `page_timed_out`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | It ran past its time and was stopped, so it may have run in part: check what it did before you send it again                                                                                                                                                                                                                                                    |
| 504    | yes       | `host_timeout`, `upstream_timeout`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | A service behind the API did not answer in time: retry after `Retry-After` with the same key                                                                                                                                                                                                                                                                    |

<!-- error-codes:end -->

**Retryable answers are safe to send again.** `no_capacity`, `busy`, `host_unavailable`, `rate_limited`, `no_credit_running_limit`, and every other code marked retryable above clear on their own. Retry with the same key after `Retry-After`, using a growing delay and a bounded deadline.

- The SDKs retry every response that says `retryable: true` themselves. They wait for its `Retry-After`, up to `maxRetries` times. The exceptions are `no_capacity`, `quota_exceeded` and `no_credit_running_limit`. The SDKs wait those out only where they wait for room (below). Otherwise they return the error immediately. A wait over a minute, such as a daily cap, is not slept on. The error is returned immediately, with `retryAfterMs`, so you can schedule the retry.
- `guest_busy`, `busy`, `rate_limited` and `sandbox_starting` mean nothing ran. `sandbox_starting` (`503`) means the sandbox exists but is waiting for a server with room; a call sent right after a create can return it. The SDKs send such a call again, with the same key. The delay grows from `Retry-After` up to eight times that value. They keep going until the call's own deadline. If the call has none, they keep going for five minutes. This applies however many retries `maxRetries` allows. Then the refusal itself is returned. A sandbox under heavy load can return `guest_busy` for tens of seconds. The call is then slow, not failed.
- A `quota_exceeded` names the limit in its message and in `details`. `details` has `limit` (such as `volume.count`), `max`, and how to `raise` it. Every limit is listed in [limits](./limits).
- A create or wake refused with `no_capacity` keeps its place in its region's line. It keeps the place if it is sent again with the same `Idempotency-Key` (the SDKs do this). Its message gives the place, how many wait ahead, and the account's lane. For example: "in line at place 2: the region's room goes to higher lanes first: 1 waiting ahead (pro 1); this account's lane is free". Its `details.line` holds the same as `lane`, `place`, `ahead` (by lane) and `words`. Freed room goes to the highest lane waiting first. See [waiting in line for room](./limits#waiting-in-line-for-room).
- An SDK create also waits out `no_credit_running_limit`, `quota_exceeded` and `no_capacity`. It waits up to two minutes by default, then returns the refusal. For a loop of your own, the error's `retryable` is `true` for three cases. Those are `no_credit_running_limit`, `no_capacity`, and a `quota_exceeded` on what runs at the same time (`sandbox.count`, `sandbox.vcpu`, `sandbox.memory_mib`, `sandbox.disk_mib`, `tunnel.count`, `instance.count`). A `quota_exceeded` on what you keep (volumes, images, snapshots, secrets, kept sandboxes) is a 409. It says `retryable: false` and has no `Retry-After`. It clears only when you delete something or raise the limit. No SDK waits for it.
- `no_capacity` is a 503 with `Retry-After: 1`. `no_credit_running_limit` and a retryable `quota_exceeded` are 429s with `Retry-After: 5`. That value is the wait before a first retry, for a client that reads only HTTP. The SDKs keep their own growing delay. Until 17 October 2026, all three were 409s with the same body.
- `no_credit_running_limit` clears when one of the four running sandboxes without credit stops or pauses. A fork that asks for more copies than that never fits.

## Retries and idempotency

Send `Idempotency-Key: <any unique string>` on a change. The server remembers the key for 24 hours.

- The same key with the same body returns the first result again. The result is marked `"replayed": true`, and it has the header `Idempotency-Replayed: true`. Nothing happens twice.
- A secret or token shown once is left out of the replay. Examples are a rotated webhook secret, a preview or MCP token, and a WireGuard key that Runtime made. Read the resource for a fresh token. A first response over 32 KiB is not kept. Its replay returns 409 `operation_conflict`, and nothing runs again.
- The same key with a different body is refused with 422 `idempotency_key_reused`.
- A refusal is not kept. A request refused before anything ran (`no_capacity`, `busy`, or a limit) leaves its key unused. So the same key sent again runs the request afresh. Only a response that did the work is replayed. A create refused with `no_capacity` starts the sandbox when it is retried with its key once there is room. The next retry with that key replays it.
- `no_capacity` is a 503 with `Retry-After` wherever it is returned. That covers a create, a fork, a restart, a wake, a public port, and a dedicated address. So a client that retries 5xx retries it, with the same key.
- A wake of a paused sandbox that is moving to another server returns 409 `sandbox_moving` with `Retry-After` until its paused memory and disk are copied there, usually within a minute or two. Nothing changed, and the sandbox stays paused with its files and memory. Send the wake again with the same key. The SDKs wait for it as they wait for `no_capacity`, and a call that wakes a paused sandbox returns the same 409.
- A waited pause (`POST /v1/sandboxes/{id}:pause` with `Prefer: wait`) succeeds when its server's snapshot space is full. The server holds the sandbox's memory and saves it once there is room. Only a sandbox too near the end of its time to save later returns `no_capacity` (503, `Retry-After: 60`). The pause was not taken. The sandbox is still running, with its memory and files. Unlike a create, that request did run. So pause again with a new `Idempotency-Key`. The same key only returns the sandbox as it is now.
- A new key is new work.

The SDKs send a key on every change. They retry transport failures, and every response marked `retryable: true`, with that key. A connection refused before the request left is sent again immediately. Anything that may have reached a server waits first. Changing the body while reusing a key is not a retry.

## Limits

These limits protect the service. They are not quotas. A refusal costs nothing.

- **Per key:** about 50 requests a second, in bursts of up to 200. Up to 128 are served at the same time. Past that, a request waits its turn for up to five seconds before it is refused. A key may have as many served at the same time as its organization allows (below), when that is more. Its rate and burst grow by the same share. For example, an organization holding 40 sandboxes has 432 in flight. So each of its keys may send about 170 a second in bursts of 675. It may send at most 400 a second in bursts of 1,600.
- **Per address, for keys not yet seen to work:** until a request on a key is accepted once, requests on that key also count against the address they come from. So do requests with wrong or missing keys. The limit is about 50 a second, in bursts of 200 (`address_rate`). A key that has worked is never refused because of someone else's wrong keys.
- **Per organization:** 192 requests in flight across all its keys. Add six for each sandbox it holds that is not stopped, up to 1,024. When support has raised its sandbox quota past 138, add six for each running sandbox up to that quota (2,592 for 400 running). That lets every sandbox stream four commands and two watches at the same time. A new sandbox's six come within half a minute. The organization also has 16 watch streams, 16 SSH logins and port forwards, and 64 terminals open. Each adds two more for each such sandbox. That gives up to 292 watch streams, 292 logins and forwards, and 340 terminals, or more as the quota allows. A pilot's agreed count sets more too. A sandbox has at most 12 terminals. When the service as a whole holds as many as it can, a new request is refused for a moment with a retry delay. Requests beyond what an organization's sandboxes bring share one room. While that room is three-quarters taken, an organization holding its fair share waits for its own requests to finish (`organization_fair_share`). So a busy account never crowds out the rest.
- **Per sandbox:** up to 1,024 commands and background processes can run at the same time. The sandbox's memory is usually the closer limit. Past that, a new one is refused with `process_limit` (429), which names the number. A command's output stays readable through its own stream, however many others end meanwhile. Processes and threads together are limited to 16,384 in a sandbox. One command and all it starts are limited to 15,360. So a fork bomb in one leaves room for the command that ends it. Past that, Linux refuses a new one: `fork` or `pthread_create` fails with `EAGAIN`. A custom image keeps the limits of the day it was built. An image built while the command limit was 16 keeps 16 until it is built again.
- **Per address:** 64 connections open to the API at the same time, and 50 new ones a second in bursts of 100. Once a request from the address carries a valid key, the address may hold its organization's room instead, for the next 10 minutes. Each such request renews that period. The room is 256 connections and 200 new ones a second. It is larger for an organization with more requests in flight. Past a limit, a new connection gets no response. The client's own retry brings it in a second or so later, once a connection closes or the address has room. A streaming response (a command's output, a download, or a watch) holds its connection until it ends. The SDKs hold each client to 48 connections, for calls and streams together. They keep 8 of them for calls and queue the rest. So a client waits for a connection rather than fail. For example, a thousand streamed commands at the same time from one client are read 40 at a time.

Over a limit, you get 429 with `Retry-After`. Streaming responses count as requests in flight until their bodies finish or you cancel them. Receiving the headers does not release a request slot. A request you abandon counts until its work stops. So does a request that returns 503 because it ran past its deadline (110 seconds from the end of its request body). Such a request is stopped. It counts against its key and organization until its work has stopped. A read stops immediately. A change stops once it is recorded. That takes at most about four minutes more. A command it started keeps running in the sandbox.

## Sandboxes

| Method and path                        | What it does                                                                                                                                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /v1/sandboxes`                   | Create. Every field optional.                                                                                                                                                                          |
| `GET /v1/sandboxes`                    | List: `state`, `name`, `label=key:value` (repeat), `includeStopped`, `limit`, `cursor`                                                                                                                 |
| `GET /v1/sandboxes/{id}`               | Read; `waitFor` and `timeoutSeconds` wait for a state                                                                                                                                                  |
| `POST /v1/sandboxes/{id}:stop`         | Stop. Returns immediately, where compute billing ends; a kept disk is written out after                                                                                                                |
| `DELETE /v1/sandboxes/{id}`            | Delete for good, in any state (see "Deleting a sandbox" below)                                                                                                                                         |
| `POST /v1/sandboxes/{id}:pause`        | Returns once the processors stop, where compute billing ends; memory and files are then saved                                                                                                          |
| `POST /v1/sandboxes/{id}:wake`         | Restore a paused sandbox; for one with a time limit, `timeoutSeconds` sets the new one                                                                                                                 |
| `POST /v1/sandboxes/{id}:extend`       | `{"seconds": 600}` more before its time limit; a sandbox with none returns immediately, unchanged                                                                                                      |
| `POST /v1/sandboxes/{id}:retention`    | `{"days": 30}` keeps a paused or stopped sandbox 1 to 365 days; `null`, the default, while you have credit                                                                                             |
| `POST /v1/sandboxes/{id}:restart`      | Start a stopped sandbox from its kept disk, or reboot a running one from its disk                                                                                                                      |
| `POST /v1/sandboxes/{id}:update`       | Change `name`, `labels`, `env`, `autoWake`, `wakeOnTimers`, `user`, `leaseSeconds`, `idlePauseSeconds`, `persistent`, `maxTotalCostMicros`, `tailscale` (`null` leaves), `timeoutSeconds`, `onTimeout` |
| `POST /v1/sandboxes/{id}:switch-image` | Move it to another image, keeping `/workspace` (see "Switching its image" below)                                                                                                                       |

The create body:

| Field                     | Default                                               | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`, `labels`          | none                                                  | Your own handle and up to 32 `key: value` tags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `env`                     | none                                                  | Environment variables for every command, process, terminal, SSH session and image start command in it (see "Its environment" below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `funding`                 | ignored                                               | Accepted and ignored: the free usage is spent first, then prepaid credit, and an account that holds credit gets paid limits                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `region`                  | the default region                                    | Use a region listed for your account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `vcpu`                    | 2                                                     | At most 16 on a paid sandbox, 2 without credit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `memoryMiB`               | 4096                                                  | At least 128; at most 65,536 (64 GiB) on a paid sandbox, 4,096 without credit; a size outside that is refused with `invalid_request` naming the field. An odd size is rounded up to the next even number (4095 becomes 4096), which is the size it gets, is billed at and is returned; resize rounds the same way                                                                                                                                                                                                                                                                                                                                                                             |
| `diskMiB`                 | 4096                                                  | From an image of yours larger than that, 8,192 (8 GiB) when it holds the image; a larger image is refused with `disk_too_small`, naming the `diskMiB` to ask for. At least 3,072; at most 409,600 (400 GiB), and 10,240 without credit. A larger disk is refused with `invalid_request`, naming the maximum. A sandbox is placed only on a server with that much free disk                                                                                                                                                                                                                                                                                                               |
| `cpu`                     | `"shared"`                                            | `"reserved"` guarantees every vCPU: the same as `cpuFloorMillis` at `vcpu` x 1000, which it sets, ignoring any other `cpuFloorMillis`; not without credit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cpuFloorMillis`          | 50                                                    | Guaranteed CPU, in thousandths of a vCPU: at most `vcpu` x 1000 (16,000 at 16 vCPU), and 250 without credit. The highest, `vcpu` x 1000, is what `cpu: "reserved"` sets                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `timeoutSeconds`          | 0, none                                               | A time limit you choose, 60 to 86,400 seconds (24 hours): it pauses or stops when that runs out, busy or not. Left out (or 0), it has none: it runs while it works and pauses when idle, until you stop it or credit or free usage runs out. A large sandbox needs time to wake its memory: 190 s for 65,536 MiB; shorter is refused, naming the least                                                                                                                                                                                                                                                                                                                                        |
| `onTimeout`, `onLeaseEnd` | `"pause"`                                             | `"pause"` keeps memory and files when its time limit, credit or free usage runs out; wake it later. `"stop"` stops it and keeps its disk for `:restart`; `"delete"` stops it and deletes its disk. `onLeaseEnd` is its older name                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `idlePauseSeconds`        | 300                                | Pause after this many seconds with nothing happening: no request, no command or terminal running, no open connection, no traffic and no CPU use. 0 is never, otherwise 60 to 86,400. Not set on a `persistent` sandbox                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `autoWake`                | true                                                  | A request to a paused sandbox wakes it (see below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `wakeOnTimers`            | true                                                  | A process due on a timer wakes it when it paused for being idle ([timers](./sandbox-environment#timers-wake-an-idle-sandbox)). Needs `autoWake`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `user`                    | `"sandbox"`                                           | `"root"` runs its commands, background processes and terminals as root, through its passwordless `sudo`, unless one names `user: "sandbox"`; files written through the files API and SSH logins stay the sandbox user's. A sandbox made from a snapshot runs as its source did                                                                                                                                                                                                                                                                                                                                                                                                                |
| `leaseSeconds`            | its first lease, 1,800                                | With no time limit, how far ahead each renewal funds it: from its first lease (1,800 seconds unless the sandbox was made with a shorter one, at least 300) to 43,200 seconds (12 hours). It is renewed when half is left, so it keeps running for at least half of this if Runtime's control plane cannot renew it. Each renewal holds that much time's credit; what it does not use is released. A sandbox on the free usage renews by its first lease until the account has credit. Set only with an owner's, an admin's or an account-wide key, on a sandbox one of those made (403 otherwise); if it loses that right, a sandbox funded past its first lease is paused or stopped at once |
| `persistent`              | false                                                 | Paid only: it runs until you stop it, while credit lasts, with no idle pause unless you set one. Its disk is billed as any sandbox's                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `maxTotalCostMicros`      | none                                                  | The most the sandbox may cost over its whole life                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `maxCostMicros`           | none                                                  | Deprecated, still accepted from older clients: use `maxTotalCostMicros`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `pausable`                | ignored                                               | Deprecated, still accepted from older clients and ignored: every sandbox can pause, fork and be snapshotted. One created with `pausable: false` before 5 October 2026 can only be stopped; a pause, fork or snapshot of it returns `not_pausable`                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `getOrCreate`             | false                                                 | With `name`: return the sandbox that holds the name (see below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `network`                 | every public port (paid), 80 and 443 (without credit) | Same shape as `PUT /v1/sandboxes/{id}/network`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `image`, `volumes`        | none                                                  | A ready image (its id, `name`, `name:tag` or `name@version`) and up to four `{volumeId, path, mode}`: `mode` `"rw"` (default) or `"snapshot"`, a read-only copy of the volume for any number of sandboxes, unrelated to sandbox snapshots ([storage](./storage#attaching-a-volume)). An image with a start command returns once its ready check passes, in `start`                                                                                                                                                                                                                                                                                                                            |
| `snapshot`                | none                                                  | A ready snapshot id: start as a copy of it. Not with `image`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `spreadFrom`              | none                                                  | One to 16 ids of your own sandboxes: it starts on a server none of them is running on (see "Keeping copies on several servers" below). An id this key may not read returns `400 invalid_request`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `secrets`                 | every one that reaches it                             | The egress secrets it may use, by name, at most 64: only those of your secrets that would otherwise reach it, never one a secret's `only` keeps from it. `[]` is none; a name not stored yet takes effect once stored. Fixed for its life; a fork or a copy of a snapshot keeps its source's list and may only narrow it. A read returns it as `secrets` (`null` for none named). See [secrets sandboxes never see](./security#secrets-sandboxes-never-see)                                                                                                                                                                                                                                   |
| `tailscale`               | none                                                  | Paid only: `{authKeySecret, hostname?, tags?}` joins your Tailscale network once it runs (see "On your tailnet" below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

Sizes are limits you ask for. The server checks their combinations against
account limits and the host's measured capacity.

**Placement.** Every sandbox and snapshot response has `placement`. It is an opaque tag such as `pl_3f9a0c1b2d4e5f60`, or `null` before the sandbox is placed. Your sandboxes and snapshots with the same tag are on the same server. The tag is never the server's name. Another account's tags are unrelated to yours.

**Wake on request.** A paused sandbox with `autoWake` wakes by itself when a command, file, process, terminal, desktop or interpreter call reaches it. The call runs once the sandbox is running, usually within a second. A visit to one of its shared ports also wakes it. An API client's request waits up to 30 seconds. A browser is shown a page that reloads itself. The wake is an ordinary wake. The sandbox runs while it works again. A sandbox with a time limit gets a fresh one of its own `timeoutSeconds`. Or it keeps the time limit it paused with, if that ends later. Billing starts from the moment it runs. With `autoWake: false`, the call fails with `sandbox_paused` until you run `:wake`. A wake that cannot be paid for fails with the refusal, such as `insufficient_funds`. The sandbox stays paused.

**Names.** A name is unique in the account while its sandbox can still run. That covers starting, running, paused, or stopped and persistent. A [compartment](./security#compartments) is its own namespace. Its keys' names are unique among its own sandboxes. So two compartments, and the account's other keys, can each have a `main`. A create that names a name already held fails with `name_taken` (409). `details.sandboxId` names the holder when your key can reach it. With `getOrCreate: true`, the create returns the holder instead. It wakes the holder if paused, and restarts it if stopped and persistent. The response has `reused: true`. The other fields apply only when the create makes a sandbox. A sandbox that is deleted, or that stops without keeping its disk, gives up its name. The name stays in its own record. A delete gives up the name immediately, so a create of the name sent right after the delete succeeds. If a sandbox is deleted before its own create returns, that create returns 410 `deleted` with `details.sandboxId`. With `getOrCreate: true`, a holder that is deleted while the create waits for it is replaced by a new sandbox. For several callers that share one name, use `getOrCreate: true`. Do not delete the sandbox that a `name_taken` response names: another caller is starting it.

**How long it runs.** A sandbox runs while it works. It pauses itself when idle. There is no time limit unless you set one. Nothing needs extending. It runs on credit or, without credit, on the free usage. It pauses, or stops with `onTimeout: "stop"`, when it is idle for `idlePauseSeconds`. It also does so when you stop it, and when credit, free usage, a spending limit, or `maxTotalCostMicros` runs out. `endsAt` says when the sandbox will stop or pause by itself. It is `null` when it never will. That happens when it has no time limit and its funding continues. `endsAt` gives a time when the sandbox has a time limit. It also gives a time once credit or a limit stops its funding.

**During a Runtime outage.** If Runtime cannot keep a sandbox's funding going
(it renews the sandbox's lease while it runs), the sandbox pauses, keeping its
memory and disk, and is never stopped or deleted for it, whatever `onTimeout`
says. Once Runtime recovers, it wakes the sandbox, with what was left of its
time limit. Compute is not billed while it was paused, and its paused storage
only from when Runtime recovered. If the account can no
longer pay for it by then, it ends as `onTimeout` says. While Runtime cannot
pause or wake sandboxes, `:pause`, `:wake` and `:restart` return 503
`api_unavailable` and change nothing; a pause or wake Runtime accepted but did
not start within 5 minutes is withdrawn, and the sandbox returns to `running`
or `paused`.

**A time limit.** `timeoutSeconds` from 60 to 86,400 (24 hours) at create sets
one: the sandbox pauses or stops then, as `onTimeout` says, busy or not.
`:extend` moves it later, up to 24 hours ahead of now (the SDKs' `keepAlive`
does it for you), and `endsAt` answers the new end. `:update` with
`timeoutSeconds` sets a new limit counted from now, sooner or later than the
old one, or gives one to a sandbox made without; `0` takes the limit away, and
`onTimeout` changes what its end does. A paused sandbox counts the new limit
from its next wake. A change of `onTimeout` that falls in the last stretch the
sandbox has already paid for can end it up to about two minutes after the end
asked, never before. A wake starts the limit
again from the wake: the sandbox's own length, or the `timeoutSeconds` the wake
names. An extend of a sandbox with no time limit answers at once and changes
nothing, so older code that extends keeps working. A persistent sandbox has no
time limit, whatever `timeoutSeconds` says. Without credit, a limit longer than the free usage left is cut to it, and the answer's `timeoutSeconds` says so: the sandbox pauses when it ends either way.

**Keep it running until you stop it.** `persistent: true`, at create or with `:update`, keeps it running with no idle pause. An exception is `idlePauseSeconds`, if you set one. This holds while the account has credit, up to `maxTotalCostMicros`. Its disk is billed like any sandbox's disk. A stop keeps the disk, as any stop does. `:update` with `{"persistent": false}` makes it an ordinary sandbox again.

**A stop keeps the disk; only a delete removes it.** A stopped sandbox reads `diskKept: true`. It is listed with the live sandboxes. Its disk is billed as [paused storage](./pricing#paused-storage) until you delete it. `:restart` starts it again from that disk. Its memory is gone. It runs its image's start command again, which `start` reports as it does at create. A read-write volume stays attached until the sandbox is deleted. So delete the sandbox before you attach the volume elsewhere. A sandbox created with `onTimeout: "delete"` has its disk deleted when its time limit ends. A sandbox stopped before it ever started has no disk to keep. It reads `diskKept: false`, and a restart is refused. Create a new one instead. A raw HTTP client says it knows this with `x-runtime-client: http/2026-10-04`. A stop from a client that names an older version, or none, keeps the disk as any stop does in an account with credit. That means a card saved or a past purchase. The disk is kept at least 30 days from the stop, even if its credit runs out. In an account with none of these, the disk is kept free for three days and then deleted. To end a sandbox for good in any state, delete it.

**A restart of a running sandbox reboots it.** `:restart` stops it, keeping its disk, and starts it again from that disk, as a stop and then a restart would. Its files stay. Its processes and memory are gone, and its image's start command runs again. Use it when the sandbox's agent stops answering (`sandbox_unreachable`). A retry with the same `Idempotency-Key` returns the same restart and does not reboot it again.

**Its environment.** `env` at create sets variables. Every command, background process, terminal, SSH session, and the image's start command in the sandbox starts with them. They last for the sandbox's whole life, through pauses, wakes and restarts. A command's own `env` is put over them. `:update` with `env` changes them. A value sets a variable. `null` removes it. The rest stay. Commands started after the change get the new values. Running commands keep what they started with. A sandbox has at most 32 variables, with at most 32 KiB of names and values together. Past that, the response is `env_too_large` (400). A name that is not a letter or underscore followed by letters, digits and underscores is `invalid_env` (400). A command whose own `env` and the sandbox's together pass what one command can carry is refused with `env_too_large` (400) before it runs. Values are write-only. Responses carry only `envNames`. No list, log or audit entry holds a value. Values are stored encrypted. The request fingerprint that an `Idempotency-Key` is checked against holds a keyed hash of them, never the values. Copies made by `:fork` keep them, because they are on the same machine, and its processes already hold them. A sandbox created from a snapshot takes only its own `env`. An SSH session gets every variable whose value has no double quote, backslash or line break. A deployment that cannot store them returns `env_unavailable` (501) and creates nothing.

**Deleting a sandbox.** `DELETE /v1/sandboxes/{id}` works in any state. It stops the sandbox if it runs or is paused. It deletes the sandbox's disk and its paused memory. It revokes its previews and TCP ports, drops its environment, and releases its name immediately. It also removes the sandbox from every list. Compute billing ends as it does for a stop. A disk kept for `:restart` is billed until its host confirms the deletion, usually within seconds. Its snapshots are separate. They stay until you delete them. Its usage, charges, and audit entries stay too. A custom domain pointed at it stays yours. Point it at another sandbox, or remove it. The response is `{id, status: "deleted", state, deletedAt}`. Afterwards the sandbox reads nowhere, and `GET` returns `not_found`. Deleting it again returns the same response, with or without the same key. A read-only key cannot delete. A sandbox that a job or a managed service runs in is ended by that job or service instead.

**Switching its image.** `POST /v1/sandboxes/{id}:switch-image` with `{"image": "web:v2"}` moves a sandbox to another image. It keeps its id and name, `/workspace` (its home: dotfiles, `pip install` and `npm install -g`), volumes, environment, labels, previews and ports. Its processes restart, and the new image's start command runs as it does at create. Everything else on its old disk is lost, such as `sudo` and apt installs, and `/etc`. `keep: "workspace"`, which older clients send, is accepted and changes nothing. Any other `keep` value is refused with `switch_keeps_workspace_only` (400), and nothing changes. To keep everything, snapshot the sandbox first. A running sandbox is paused first. A paused sandbox, or a stopped persistent one, is switched as it is. A stopped ordinary sandbox kept no disk, so it cannot switch (`switch_needs_disk`, 409). The switch is charged as a wake. The response comes once the sandbox runs the new image. If anything fails, the switch is undone. The response is `switch_undone` (503). The sandbox is then paused or stopped on its old image, with its files and memory as they were. The image must be ready and on the sandbox's server (`image_on_another_host`, 422). It must differ from the image the sandbox runs (`image_unchanged`, 409). It must fit the sandbox's disk (`disk_too_small`, 422). Copying `/workspace` may take up to 60 seconds.

**On your tailnet.** A paid sandbox can join your own Tailscale network.
Store an auth key for jobs (`printf %s "$TS_AUTHKEY" | runtime secrets set TS_AUTHKEY --jobs`),
then `POST /v1/sandboxes/{id}/tailscale` with `{"authKeySecret": "TS_AUTHKEY"}`,
and optionally `hostname` and `tags`, or pass the same object as `tailscale` at
create. The response gives its tailnet `addresses`, `dnsName` and `mode`; `GET`
reads them again and `DELETE` logs the machine out. The key is never returned,
logged or written to the sandbox's disk. [Networking](./networking#your-tailscale-network) has the rest.

## Commands and processes

| Method and path                                        | What it does                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
| `POST /v1/sandboxes/{id}:exec`                         | Run and return `{exitCode, stdout, stderr, timedOut}`                          |
| `POST /v1/sandboxes/{id}/processes`                    | Start in the background; add `"pty": {"cols", "rows"}` for a terminal          |
| `GET /v1/sandboxes/{id}/processes`                     | Running and recent processes                                                   |
| `GET /v1/sandboxes/{id}/processes/{processId}`         | One process                                                                    |
| `GET /v1/sandboxes/{id}/processes/{processId}/output`  | Output from `cursor`; `waitMs` long-polls; `follow=true` streams               |
| `POST /v1/sandboxes/{id}/processes/{processId}:write`  | `{"data"}` or `{"base64"}`, with `offset` and `eof`; offsets make retries safe |
| `POST /v1/sandboxes/{id}/processes/{processId}:signal` | `{"signal": "SIGTERM"}`                                                        |
| `POST /v1/sandboxes/{id}/processes/{processId}:resize` | `{"cols", "rows"}` for a pty                                                   |
| `GET /v1/sandboxes/{id}/processes/{processId}/files`   | What a process started with `traceFiles` read and wrote, once it has ended     |

The exec body is `command` (run under `bash -c`) or `argv` (no shell). Optional fields are `cwd`, `env`, `stdin`, `user`, `timeoutMs` (default 60,000, or less when the sandbox's time limit, credit or free usage ends sooner; at most 24 hours), `stream`, and `traceFiles` (below). A timeout is a result with `timedOut: true`, not an error. In a sandbox that a [real-value secret](./security#a-secret-the-machine-needs-itself) reaches, a command or process start may return 503 `secret_withheld` when its server cannot give the value right now. Nothing ran. Send it again after a few seconds; the SDKs do. `env` is put over the sandbox's own environment. Its values are never echoed and are stored only as hashes. `user` is `"sandbox"` by default (the user `runtime`, uid 1000). It can also be `"root"`. That runs the command as root through the sandbox's passwordless `sudo`. The environment, `PATH` and working directory stay the same, and `HOME=/root` is set unless `env` sets `HOME`. So no command needs a `sudo` prefix. Starting a process takes `user` too. Every process reports which user it runs as in `user`.

**Files a command read.** With `"traceFiles": true`, the response (or the stream's `exit` event) adds `files`. It has `read`: every file and directory that the command, or anything it started, opened. Paths are sorted, absolute, and resolved through links. A directory ends in `/`. It has `written`: every file the command wrote. It has `truncated`, which is `true` when some paths are missing (past about 380 KB of paths). Key a cache by the contents of `read`. A test then reruns only when a file it really read has changed. A background process also takes `traceFiles`. It returns its files at `…/files` once it ends. Only the command's own opens are counted. Opens by other processes on the same sandbox are not. Opens through mounts that the command itself makes are not seen. Neither are lookups of files that do not exist. Each file costs 5 to 15 microseconds the first time it is opened. After that, the cost is almost nothing. A sandbox started before tracing existed returns `409 unsupported_operation`, and nothing runs. Stop it and start it again. A sandbox that cannot trace the command returns 409 `file_trace_unavailable`, and nothing runs. The `…/files` route returns 409 `process_running` while the process still runs. It returns 409 `file_trace_not_requested` for a process started without `traceFiles`.

**Streaming.** With `"stream": true`, the response is NDJSON, with one event per line: `start`, `stdout`, `stderr` and `exit`. When a stream passes the server's time limit, it sends `continue` with a cursor. `…/output?follow=true&cursor=` resumes from that cursor. A stream that fails ends with `error`. That event carries the `code` and `status` the response would have had, and the `cursor`. After a 429 or a 5xx, follow again from that cursor, because the command keeps running. The SDKs do this for up to five minutes of failures in a row. A streamed command has no output limit.

**Output size.** The JSON response returns up to 256 MiB of each stream, and a streamed exec (`"stream": true`) returns all of the output with no limit. `stdoutBytes` and `stderrBytes` give the number of bytes each stream wrote. A stream past 256 MiB is cut there and its truncation flag is `true`; it can also be cut sooner, and marked the same way, when the API host is short of disk space. To limit the response, set `maxOutputBytes`: the response then holds at most that many bytes of each stream, cut between UTF-8 characters, and `stdoutTruncated`, `stderrTruncated` and `truncated` are `true` for a stream that was cut. `stdoutBytes` and `stderrBytes` still count every byte. An older sandbox returns at most 64 KiB of each stream for a command with a `timeoutMs` of 60,000 or less; for a stream it cut, the truncation flag is `true` and its byte count is `null`. Stop and start the sandbox to remove the limit.

While a stream is being read, its command waits for the reader. That way no output is lost, from the first byte. The sandbox keeps the latest 1 MiB of each process's output. A reader that is away for more than 10 seconds, while more than that comes out, gets `{"type":"truncated","droppedBytes","resumeAt"}`. That event comes before the output that remains. For large output, stream it. Or write it to a file, and read the file with `GET …/files/content`.

## Terminals

`GET /v1/sandboxes/{id}/terminal` with `Upgrade: websocket` and the bearer header
opens a terminal: `cols`, `rows`, `command` (default `bash -l`), `cwd`,
`user=root` for a root shell, or
`processId` to attach to a process started with a pty. Binary frames are terminal
bytes both ways. Text frames are JSON: you send `{"type":"resize","cols":120,"rows":40}`;
the server sends `{"type":"ready","processId":...}` and `{"type":"exit","exitCode":...}`.
A terminal survives a restart of the API ([resuming terminals and tunnels](#resuming-terminals-and-tunnels-after-a-restart)).

A browser's WebSocket cannot send an `Authorization` header. So the terminal on a sandbox's page at withruntime.com uses a ticket instead: `Sec-WebSocket-Protocol: runtime.terminal.v1, runtime.ticket.<ticket>`. The server responds with `runtime.terminal.v1`. A ticket is accepted only from a page on withruntime.com. It opens one terminal in one sandbox, and it lasts 60 seconds. A refused ticket returns `unauthorized` (401) or `forbidden` (403), and says why. Your own code uses the bearer header. See [the browser terminal](./security#the-browser-terminal).

## Tunnels

This is a connection from your code into one sandbox. It is not the WireGuard tunnel that joins your own network to your sandboxes ([domains, TCP ports, addresses and the tunnel](#domains-tcp-ports-addresses-and-the-tunnel)). `GET /v1/sandboxes/{id}/tunnel` with `Upgrade: websocket` and the bearer header opens one into the sandbox. It carries TCP connections to any port on the sandbox's loopback, and SSH logins. Several can run at the same time over one socket. It needs the key's `exec` permission, like a command. The CLI (`runtime sandboxes ssh`, `runtime sandboxes port-forward`) and the SDKs (`sbx.tunnel()`, `sbx.forwardPort()`, `forward_port()`) use it for you.

Binary frames in both directions have one kind byte, then a 32-bit big-endian stream number, then a payload. You send `o` to open a stream with `tcp PORT` or `ssh KEYTYPE BASE64` (an OpenSSH public key). You send `d` for data, `e` for the end of your input, and `c` to close. The server sends `o` when a stream is opened, `d` for data, and `e` for the end of output. It sends `c` when a stream closes, with a reason (`closed` when nothing listens). It sends `l` for sshd's error output. It sends `a` on stream 0, with a 64-bit count of the data bytes the sandbox has taken. Keep at most 1 MiB of data sent beyond the last `a`. A client that sends more is disconnected. Text frames from the server are JSON. `{"type":"ready"}` comes first. `{"type":"error","error":{...}}` comes before the socket closes on an error. Empty and control frames also share a bounded pending queue. If that queue floods, the socket closes, even when data bytes remain below the credit limit.

## Resuming terminals and tunnels after a restart

When Runtime's API restarts, it moves each open terminal and tunnel to the API instance that serves next. The SDKs, the CLI and the console do this for you: a terminal's output and a tunnel's streams continue from the exact byte where they stopped, nothing typed is lost or sent twice, and your code sees no close. A client that speaks the WebSocket protocol itself follows these steps:

1. The server sends `{"type":"restart"}`. Stop sending, keep what you would have sent, and reply with `{"type":"restart"}`.
2. The server sends `{"type":"resume","token":"...","replay":"..."}` and closes the socket with code 1012 (Service Restart). `replay`, when present, is base64 input the server had received but not yet written to the sandbox.
3. Open the same path again with `?resume=<token>` and no other parameters. The server responds with `{"type":"ready","processId":...,"resumed":true}`. If there was a `replay`, send `{"type":"replay","data":"<replay>"}` first, then what you kept. On a terminal, send a `resize` if the size changed.

A client that does not reply to `{"type":"restart"}` within 2 seconds is closed with code 1012 and cannot resume; its terminal's shell ends as on any close. A token is signed, valid for 30 seconds, and only for the organization, sandbox and kind of socket it was issued for; the connection is authorized again like any new one. A token that was changed returns 400, and one that was already used returns 409. If the reconnect fails otherwise (for example, the server returns 503 while instances change over), retry with the same token for up to 25 seconds. Send `replay` back exactly as you received it. If no client resumes within the token's 30 seconds, the terminal's shell is ended as on a close (a shell you attached to with `processId` keeps running), and so is a tunnel's helper with the connections it carries.

## Files

| Method and path                                                 | What it does                                                                                                                                                                                            |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/sandboxes/{id}/files/content?path=`                    | The file's raw bytes, any size; `x-content-length` gives the length first (and `x-content-sha256` a small file's digest), so check it: a body that ends short failed                                    |
| `PUT /v1/sandboxes/{id}/files/content?path=`                    | Replace the file with the raw request body, up to 1 MiB (larger ones get 413: use `/uploads`); makes parents; `mode=755` sets its permissions (644 by default)                                          |
| `GET /v1/sandboxes/{id}/files/list?path=`                       | Entries; `depth`, `glob`, `hidden`, `limit`                                                                                                                                                             |
| `GET /v1/sandboxes/{id}/files/stat?path=`                       | Type, size, mode and times, or `{"exists": false}`                                                                                                                                                      |
| `POST /v1/sandboxes/{id}/files:mkdir`                           | `{"path", "parents"}`                                                                                                                                                                                   |
| `POST /v1/sandboxes/{id}/files:remove`                          | `{"path", "recursive"}`                                                                                                                                                                                 |
| `POST /v1/sandboxes/{id}/files:rename`                          | `{"from", "to", "overwrite"}`                                                                                                                                                                           |
| `POST /v1/sandboxes/{id}/files:chmod`                           | `{"path", "mode": "755"}`                                                                                                                                                                               |
| `POST`, `GET /v1/sandboxes/{id}/files/watches`                  | Watch a directory: `{"path", "recursive", "events", "include", "exclude", "batchMs", "timeoutMs"}`; list the watches                                                                                    |
| `GET /v1/sandboxes/{id}/files/watches/{watchId}/events?cursor=` | Its events after a cursor (`waitMs` up to 8000), or `follow=true` for a stream                                                                                                                          |
| `DELETE /v1/sandboxes/{id}/files/watches/{watchId}`             | Stop a watch                                                                                                                                                                                            |
| `POST /v1/sandboxes/{id}/uploads`                               | Begin a large upload: `{"path", "size", "sha256", "mode"}`; `path` must be under `/workspace` (move it with exec after the commit)                                                                      |
| `PUT /v1/sandboxes/{id}/uploads/{uploadId}?offset=`             | One chunk of raw bytes; chunks may go in parallel                                                                                                                                                       |
| `POST /v1/sandboxes/{id}/uploads/{uploadId}:commit`             | Check the digest and move the file into place atomically                                                                                                                                                |
| `POST /v1/sandboxes/{id}/uploads/{uploadId}:abort`              | Give up                                                                                                                                                                                                 |
| `GET /v1/sandboxes/{id}/files/archive?path=`                    | A folder as tar, streamed; `gzip=true`, `user=sandbox` or `root`, and repeated relative `exclude` paths. A failed folder stream ends as an archive no tar reader accepts                                |
| `PUT /v1/sandboxes/{id}/files/archive?path=`                    | Unpack a tar (gzipped or not) of up to 1 MiB from the raw body into the folder, making it; merges with what is there                                                                                    |
| `POST /v1/sandboxes/{id}/files/archive/uploads`                 | Begin a larger one: `{"path", "gzip", "user"}`; `gzip` and `user` are optional; returns `uploadId`                                                                                                      |
| `PUT …/files/archive/uploads/{uploadId}?offset=`                | The next part, up to 1 MiB, in order; a part sent twice is not written twice                                                                                                                            |
| `POST …/files/archive/uploads/{uploadId}:commit`                | Returns once tar has unpacked it all (`:abort` stops it; what was unpacked stays)                                                                                                                       |
| `POST /v1/sandboxes/{id}/files:link`                            | A link anyone can open with no key: `{"path", "method": "GET" or "PUT", "expiresInSeconds", "filename", "maxBytes", "wake", "archive"}`; returns `{"url", "expiresAt"}` (see [File links](#file-links)) |
| `POST /v1/sandboxes/{id}/files:revoke-links`                    | End every link made for the sandbox so far                                                                                                                                                              |

Paths are absolute. File errors name the path, such as `file_not_found`, `is_a_directory`, `not_a_directory` or `permission_denied`.

A watch's events are `create`, `write`, `remove`, `rename` and `chmod`. Repeated writes are folded together, with a `count`. `rename` includes `oldPath`. Events arrive in batches every `batchMs` (100 by default). Notices say when events were missed. `overflow` means more than 5,000 a second, or the kernel's own queue is full. `lost` means a reader more than 1 MiB behind. A stream ends with `continue` and the cursor after 110 seconds. It ends with `paused` when the sandbox pauses. Reading never wakes a sandbox. A read after it wakes carries on from the cursor with nothing lost. At most four watches run in a sandbox. Each runs for `timeoutMs`: one hour by default, at most a day, or `0` to run until stopped.

A watch started with `"webhook": true` also sends its changes to your account's webhooks as `sandbox.files.changed` events (see [webhooks](./observability#webhooks)). Nothing in the sandbox or on your side has to read it. Runtime reads it without waking the sandbox, at most once every 2 seconds. An account has at most 16 such watches. A sandbox session cannot start one.

A folder moves as one tar archive. By default, `tar` packs or unpacks it inside the sandbox, as the sandbox user. So a folder download needs only the key's `read_file` permission. An upload needs `write_file`. `user=root` explicitly uses passwordless `sudo` inside that sandbox, with the same file permissions. An image without `sudo` refuses with `root_unavailable` before any file bytes are sent. Downloads accept repeated `exclude` parameters for plain relative paths, not glob patterns. `..`, empty, or absolute paths are refused. A multipart upload sets `user` when it begins. Direct uploads detect gzip from the archive header. The sandbox needs `sh`, `tar` and `base64`, plus `gzip` for a compressed archive. Every image from Runtime's base has them. At most four folders move in each direction in a sandbox at the same time. Like every file call, a folder call wakes a paused sandbox. A download whose reader takes no bytes for 60 seconds ends with 408 `download_idle`. Ask for it again. An upload, a chunk, or any request whose body sends no bytes for 30 seconds returns 408 `request_timeout`. Send it again, with a chunk at its same offset. A body that keeps arriving, however slowly, may take up to about 280 seconds to arrive. The request still has its own 110 seconds to respond. A body still arriving after 280 seconds gets 408 `request_timeout` too. The response says how many bytes came. Chunks sent together share the link, so over a slow link, send fewer at the same time. The SDKs and the CLI get 503 `body_stalled` instead of either 408. They send it again by themselves, with the same key.

The SDKs' `files.upload` and `files.download` and the CLI's `runtime sandboxes cp` use these routes. The SDKs also expose `files.archive` and `files.unarchive` for callers that need the archive bytes themselves.

```bash no-run
curl -sS "https://api.withruntime.com/v1/sandboxes/${ID}/files/archive?path=/workspace/app&gzip=true" \
  -H "Authorization: Bearer ${RUNTIME_API_KEY}" -o app.tar.gz
curl -sS -X PUT "https://api.withruntime.com/v1/sandboxes/${ID}/files/archive?path=/workspace/site" \
  -H "Authorization: Bearer ${RUNTIME_API_KEY}" --data-binary @site.tar.gz
```

### File links

A file link is an address for one file in a sandbox. It works with no API key. A person's browser or another service can use it, for example for a report, a build, a video or a dataset. `POST /v1/sandboxes/{id}/files:link` makes one. It returns its `url`, `https://files.<preview domain>/<token>/<name>`, and the time it ends.

- `method: "GET"` (the default) downloads the file. Range requests work. A video plays, and a download resumes. `ETag` and `If-Range` keep a resume on the same version. A picture, video, sound or plain text shows in the browser. Anything else, such as a PDF, a page or a program, downloads. With `filename`, everything downloads under that name. Nothing a link serves runs as a page. Every response carries `X-Runtime-Report`, which says where to report a problem. `archive: true` links a folder. It downloads as `.tar.gz`. The file must exist when the link is made.
- `method: "PUT"` makes an upload link. `curl -T report.pdf "$URL"` writes the body to `path`. It creates the folder. The write is whole or not at all. A reader sees the old file or the new one. The response is 201 with `{"path", "size", "sha256"}`. The body can be up to `maxBytes` in one request. That is 5 GiB by default, and at most that. The body streams into the sandbox as it arrives, so there is nothing to split. It must arrive within 5 minutes.
- `expiresInSeconds` defaults to 3600. It can be 60 to 604800 (7 days).
- A link works from anywhere, including another sandbox. Give one to an agent in a sandbox, and it can download or upload with `curl`. No key is needed.
- A paused sandbox wakes for a link, as for any file call. `wake: false` never wakes it. The link returns 409 `sandbox_paused` instead. `wake: true` wakes it even when it was made with `autoWake: false`. That needs a key that may wake the sandbox itself, which means the `create` permission. Otherwise the response is 403.

A link needs the key's `read_file` permission to download, and `write_file` to upload. It acts as that key. Revoking the key ends its links. So does `POST /v1/sandboxes/{id}/files:revoke-links`, which ends every link of the sandbox, and deleting the sandbox. A link that has ended returns 410 (`link_expired` or `link_revoked`). A deleted sandbox returns 404 `sandbox_gone`. A request with the other method returns 405 `wrong_method`. A range past the end of the file returns 416 `range_not_satisfiable`. An upload the sandbox cannot write returns 422 `upload_failed`, and nothing is written. A sandbox that Runtime took down after a report returns 451 `taken_down`. Refusals are plain text, or JSON when the request accepts `application/json`. Each link made and each revocation is in the audit log. The bytes a link serves count as the sandbox's served traffic, as a preview's do. They have the same monthly allowance and price.

```bash no-run
URL=$(curl -sS -X POST "https://api.withruntime.com/v1/sandboxes/${ID}/files:link" \
  -H "Authorization: Bearer ${RUNTIME_API_KEY}" -H "Content-Type: application/json" \
  -d '{"path": "/workspace/report.pdf", "expiresInSeconds": 86400}' | jq -r .url)
curl -fLo report.pdf "$URL"  # no key
```

Links are for a sandbox's files. A link to a file on a volume is not available while no sandbox is running. Mount the volume in a sandbox, and link the file there.

## Sessions

A session is a short-lived token. A browser uses it to reach one sandbox without your key. A key that can run commands in the sandbox makes, lists and revokes sessions:

| Method and path                                       | What it does                                                                                        |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `POST /v1/sandboxes/{id}/sessions`                    | `{"ttlSeconds", "origins", "name"}`; returns the session with its `token`, shown once, and `apiUrl` |
| `GET /v1/sandboxes/{id}/sessions`                     | Its sessions still active, and those that ended in the last day                                     |
| `POST /v1/sandboxes/{id}/sessions/{sessionId}:revoke` | End one now                                                                                         |

`ttlSeconds` defaults to 3,600. It can be 86,400 at most. `origins` lists up to 10 exact origins, `https://host[:port]` or `http://localhost[:port]`.

Send the token as the bearer: `Authorization: Bearer rtsess_...`. The session can use the sandbox's routes under `:exec`, `/processes`, `/files`, `/uploads`, `/interpreter`, `GET /v1/sandboxes/{id}`, and `GET /v1/sandboxes/{id}/previews`. Those routes work for its own sandbox only. Everything else returns `forbidden` (403). An ended session returns `unauthorized` (401). A preview token that the session is handed ends when the session does.

The API sends CORS responses only for a session's own origins. That covers a preflight from a page that a session of that sandbox lists. It also covers the responses to that session's requests, errors included. A session request from any other page is refused. Requests with a key carry no CORS headers.

A replay of a create with the same `Idempotency-Key` returns the session with `token: null`. Revoke it and make another. The SDKs do that for you.

## Private preview tokens

`POST /v1/sandboxes/{id}/previews` accepts optional `ttlSeconds` and `expiresAt` fields. `GET /v1/sandboxes/{id}/previews/{port}` accepts them as query parameters. `runtime_sandboxes_previews_create` accepts the same fields. `expiresAt` is an ISO timestamp with a timezone. It must be at least a minute and at most a week ahead. Invalid deadlines return `invalid_request` (400) before the preview changes.

With `expiresAt` alone, the token ends by that deadline. With both fields, it ends by the earlier of the requested lifetime and the deadline. Existing relative lifetimes keep their rounding. An absolute deadline rounds down to whole seconds and is never exceeded. Read `tokenExpiresAt` from the response. Do not calculate it yourself. A connection the token opened, such as a WebSocket or a long download, ends when the token expires. Open it again with a fresh token. A preview token read through a sandbox session also ends when that session expires. With less than a minute left, the session receives no fresh token. Sessions still cannot create or rotate previews, or use MCP.

The token and its expiry are not stored on the preview. Every create and every read signs its own token for that response. A list, or a read without `ttlSeconds` or `expiresAt`, signs a token that lasts a day. So a create that asked for a week, and a list just after it, show the same preview id. They return different tokens and different `tokenExpiresAt` values. Both tokens work, each until its own `tokenExpiresAt`. A later read never shortens or extends a token you already hold. Only `:rotate`, or removal of a key, ends it early.

## Other products

| Method and path                                                                                                                                                                                                                        | Product                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `POST /v1/sandboxes/{id}/interpreter:run`, `…/interpreter/contexts` (`language`: python, javascript, typescript, r, java, bash, go), `…/contexts/{context}:restart`, `:interrupt`, `DELETE`, `GET …/contexts/{context}/results/{file}` | Code interpreter                                                                               |
| `POST`, `GET /v1/sandboxes/{id}/mounts`, `…/mounts:unmount`                                                                                                                                                                            | Bucket mounts                                                                                  |
| `POST`, `GET`, `DELETE /v1/sandboxes/{id}/tailscale`                                                                                                                                                                                   | Your Tailscale network                                                                         |
| `POST`, `GET /v1/sandboxes/{id}/previews`, `…/previews/{port}`, `…/previews/{port}:rotate`                                                                                                                                             | Previews                                                                                       |
| `POST /v1/sandboxes/{id}/browser:start`, `GET /v1/sandboxes/{id}/browser`, `POST /v1/sandboxes/{id}/browser:stop`                                                                                                                      | A Chromium browser and its private CDP address ([JavaScript](./javascript#a-browser-over-cdp)) |
| `POST /v1/sandboxes/{id}/desktop:start`, `:stop`, `:act`, `GET …/desktop/screenshot`                                                                                                                                                   | Desktop                                                                                        |
| `POST`, `GET /v1/sandboxes/{id}/desktop/recordings`, `GET …/recordings/{recordingId}`, `…/video`, `:stop`, `DELETE`                                                                                                                    | Desktop recordings                                                                             |
| `GET`, `PUT /v1/sandboxes/{id}/network`                                                                                                                                                                                                | Network rules                                                                                  |
| `GET /v1/egress-secrets`, `GET`, `PUT`, `DELETE /v1/egress-secrets/{name}`, `PUT /v1/egress-secrets/{name}/sandboxes` and `/rules`                                                                                                     | Secrets                                                                                        |
| `GET`, `PUT`, `DELETE /v1/networks/upstream-proxy`                                                                                                                                                                                     | Your own proxy                                                                                 |
| `GET`, `PUT /v1/networks/private`                                                                                                                                                                                                      | Your sandboxes reach each other by name                                                        |
| `GET`, `PUT /v1/networks/signed-requests`                                                                                                                                                                                              | Your sandboxes sign requests as Runtime's agents                                               |
| `POST`, `GET /v1/feedback`                                                                                                                                                                                                             | Feedback                                                                                       |
| `POST /v1/support/messages`, `GET /v1/support/conversations/{id}`                                                                                                                                                                      | Support                                                                                        |
| `GET /v1/me`, `GET /v1/usage`, `GET /v1/usage/requests?range=24h`, `GET /v1/limits`, `GET /v1/audit`, `GET /v1/account/emails`, `POST /v1/account/emails:update`                                                                       | Account                                                                                        |
| `GET /v1/sso`                                                                                                                                                                                                                          | Single sign-on                                                                                 |
| `GET`, `PUT`, `DELETE /v1/billing/auto-top-up`                                                                                                                                                                                         | [Auto top-up](./pricing#auto-top-up)                                                           |
| `GET`, `POST /v1/identity/token?audience=` (from inside a sandbox, with its request token)                                                                                                                                             | Identity tokens                                                                                |
| `GET /v1/usage/compare?provider=e2b&days=30`, `GET /v1/switching`, `POST /v1/switching`                                                                                                                                                | Switching                                                                                      |
| `POST`, `GET /v1/images`, `GET /v1/images/{id}`, `…/logs?follow=true`, `:tag`, `:untag`, `:delete`, `GET /v1/images/resolve?ref=`                                                                                                      | Custom images                                                                                  |
| `POST /v1/images/context/missing`, `PUT /v1/images/context/{digest}`                                                                                                                                                                   | Image build contexts                                                                           |
| `GET`, `POST /v1/images/registries`, `POST /v1/images/registries:delete`                                                                                                                                                               | Private registries                                                                             |
| `POST`, `GET /v1/volumes`, `GET /v1/volumes/{id}`, `:delete`, `:backup`, `:backup-policy`; `GET /v1/volume-backups`, `…/{id}`, `:delete`                                                                                               | Volumes and backups                                                                            |
| `POST /v1/sandboxes/{id}:fork`, `POST /v1/sandboxes/{id}:snapshot`, `GET /v1/snapshots`, `…/{id}`, `:update` (name, labels), `:extend`, `:delete`                                                                                      | Forks and snapshots                                                                            |
| `GET /v1/sandboxes/{id}/metrics?range=1h`, `GET /v1/events`                                                                                                                                                                            | Metrics and events                                                                             |
| `POST`, `GET /v1/webhooks`, `GET /v1/webhooks/{id}`, `:update`, `:rotate-secret`, `:test`, `:delete`, `…/deliveries`, `POST /v1/webhook-deliveries/{id}:retry`                                                                         | Webhooks                                                                                       |
| `POST`, `GET /v1/otel-exports`, `GET /v1/otel-exports/{id}`, `:update`, `:flush`, `:delete`                                                                                                                                            | OpenTelemetry export                                                                           |

**Secrets.** `PUT /v1/egress-secrets/{name}` takes `value` and one of two kinds. With `hosts`, the value is added on the way out: the machine sees a placeholder, and the proxy puts the value into HTTPS requests to those hosts. With `"exposed": true` and no `hosts`, the machines get the value itself, up to 64 KiB, several lines included. A real value takes no `header`, `format`, `rules`, `githubApp`, `git` or `api`. It needs `only` naming sandboxes (`only.sandboxes`) or Apps (`only.apps`) by id, with no labels: code in the machine can read it. A replacement may leave `only` out to keep its scope. `PUT /v1/egress-secrets/{name}/sandboxes` is refused for it, so its machines change only when it is stored again with its value. Writing a real value takes `exec` on each machine it reaches, the ones it keeps too: otherwise 403 `forbidden`, with the machine in `details.id`. `env` works with both, but a real value's variable (its `env`, or its name) is never one that makes programs load or run code, such as `BASH_ENV`, `NODE_OPTIONS`, `GIT_SSH_COMMAND`, `PYTHON*` or `LD_*`: that is 400 `invalid_request` with field `env`. `expectedVersion` writes only if the secret is at that version; `0` means it must not exist yet. Otherwise nothing is written, and the answer is 409 `version_conflict` with the current version in `details.version`. `GET /v1/egress-secrets/{name}` returns one secret as the list shows it, with `exposed` and `version`, never its value. A secret that does not exist is 404 `not_found`. See [a secret the machine needs itself](./security#a-secret-the-machine-needs-itself).

Snapshots accept `mode: "memory"` (the default) or `mode: "disk"` in `POST /v1/sandboxes/{id}:snapshot`. Memory snapshots keep files and running processes. Disk snapshots keep only the root filesystem. A sandbox created from one boots fresh, with no saved processes. It uses the `vcpu`, `memoryMiB` and `diskMiB` that the create asks for. Each one left out is taken from the snapshot. Its disk is at least the saved size. A copy of a memory snapshot continues the saved machine, so it has the snapshot's size. Naming a different size returns `400 invalid_request`. Neither mode takes a source with attached volumes. Both keep the same ownership, retention, and storage pricing. A running source is paused for the capture, and woken after it. A disk snapshot's pause first waits for the sandbox to write to its disk what it still holds in memory. That takes milliseconds when the sandbox is quiet, and up to a few seconds while it writes. The returned snapshot includes its `mode`. Keep the source paused until the snapshot's state is `ready` or `failed`. `Prefer: wait` can return while capture is still in progress.

Where deferred compression has been qualified and enabled, a memory snapshot may be `ready` with `compressionPending: true`. It can start on the same server from its captured raw state. `meteredBytes` is zero until Runtime publishes the verified compressed allocation. Temporary raw files are not charged. While compression is pending, `backedUp` is false and `durability.state` is `none`. Its off-server copy is queued after compression. See [snapshot storage](./storage#snapshots-survive-their-server).

### Evictable sandboxes

Set `evictable: true` on a create, or with `:update`, for work you can recreate, such as build caches, CI machines and test fixtures. An evictable sandbox that has been paused or stopped for at least 15 minutes may be deleted when its server needs the disk. The sandbox idle longest is deleted first. The deletion is the same as `DELETE`: its disk and paused memory are deleted, and it no longer appears in lists. A running sandbox is never deleted for it, and `evictable: false` turns it off. Setting it to `true`, on a create or an update, needs a key that may delete the sandbox; otherwise the request returns `403`. The sandbox's `evictable` field reads the setting back.

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

const runtime = new Runtime();
const cache = await runtime.sandboxes.create({ evictable: true, labels: { role: "build-cache" } });
```

### Keeping copies on several servers

A copy of a snapshot starts on a server that holds the snapshot. That is the server it was taken on, or one that Runtime keeps a checked copy on. When none of those has room, Runtime copies the snapshot to another server in the region. The sandbox starts there once the copy is checked, usually within half a minute. This works as soon as the snapshot is `ready`, even while its compression is pending. A server starts at most 4 copies a minute of one account's snapshot while that account's sandboxes there are busy on CPU. Past that, the start moves to another server that holds the snapshot and has room. It is refused with `account_busy_here` only when no such server exists. To be sure copies start on several servers, keep several warm sources on different servers.

`spreadFrom` lists 1 to 16 ids of your own sandboxes. The new sandbox starts on a server that none of them is running on. It stays apart from them each time it is placed again. With no other server that has room, the create returns `503 capacity_unavailable` immediately. Its message names `spreadFrom`. Nothing is made or charged. An id that is not a sandbox this key may read returns `400 invalid_request`. Snapshot ids are not accepted in `spreadFrom`, and a copy of a snapshot cannot take `spreadFrom` yet: that create returns `501 feature_unavailable`. Compare `placement` tags to see which of yours share a server.

Three warm sources on different servers. Then copies, made round-robin:

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

const runtime = new Runtime();
const a = await runtime.sandboxes.create();
const b = await runtime.sandboxes.create({ spreadFrom: [a.id] });
const c = await runtime.sandboxes.create({ spreadFrom: [a.id, b.id] });

const snapshots = [];
for (const source of [a, b, c]) snapshots.push(await source.snapshot());

for (let i = 0; i < 12; i++) {
  await runtime.sandboxes.create({ snapshot: snapshots[i % 3]!.id });
}
```

```python check
from withruntime import Runtime

runtime = Runtime()
a = runtime.sandboxes.create()
b = runtime.sandboxes.create(spread_from=[a.id])
c = runtime.sandboxes.create(spread_from=[a.id, b.id])

snapshots = [source.snapshot() for source in (a, b, c)]

for i in range(12):
    runtime.sandboxes.create(snapshot=snapshots[i % 3]["id"])
```

A wake runs on its sandbox's server. A copy starts on a server that holds its snapshot while one has room. When none has room, it starts on another server once the snapshot is copied there. That adds seconds to its start. A fork's copies do the same.

A copy of a snapshot that saved memory, and a wake, load all of that memory within seconds. So a server counts each one at its full memory size from the start. Many copies or wakes at the same time on one server use up what memory it has. The ones past that wait while it makes room. If none gets room in time, they return `503 host_memory_pressure` with `Retry-After`. Send each one again after that wait, with the same `Idempotency-Key`. Back off if it is refused again, as the SDKs do.

Forks:

- A fork's copies keep the source's size and CPU (`cpu` and `cpuFloorMillis`). They are quoted as a create with those values would be.
- Copies keep the source's `labels` unless the fork names others. They get no name unless the fork gives one (`name`, then `name-1`, `name-2` for several). Names are unique in the account, or in a compartment. A snapshot taken without labels keeps its sandbox's labels. A sandbox created from a snapshot keeps the snapshot's labels unless the create names others. The one exception is `share: made-keys`. Copies, sandboxes and snapshots never inherit it. Set it on each snapshot you mean to share (see [Run a swarm](./teams#run-a-swarm)). A `share` label with any other value is yours, and is copied as before.
- The snapshot a fork takes is deleted when the fork ends, whether every copy started or not. It is never billed, unless the request says `keepSnapshot: true`.
- A fork that fails after its snapshot returns the failing step's error. `details.startedSandboxIds` names the copies that did start. They are deleted. When the error is a 5xx, a failure on Runtime's side, none of their time is billed, and `details.copiesBilled` is `false`. When it is a 4xx, caused by the request or the account (a limit, a quota, or a copy or the source deleted or changed during the fork), the time they ran is billed. A copy the fork could not delete at once is named outside `details.deletedSandboxIds`, `details.copiesDeleted` is `false`, and it is deleted within 15 minutes. If the server handling a fork stops before it answers, the fork is marked failed with a 500 once it has run longer than any fork can (15 minutes, plus about 20 seconds for each GiB of the source's memory), and its copies are deleted unbilled within 15 minutes after that. A fork that does not answer within the request deadline is a failure on Runtime's side, unbilled; if your client closes the connection before the fork answers, the copies are deleted and billed for the time they ran. A retry with the same `Idempotency-Key` returns that same error.
- If a fork stops partway and left its source paused, the source stays paused. `GET /v1/notices` holds a `fork-left-paused` notice. It names the sandbox, the fork's key, and how to wake it.

Metrics, events, webhooks and OpenTelemetry export are in [metrics and webhooks](./observability). That page covers what each field means, how deliveries are signed and retried, and what an export sends.

The OpenAPI document lists every field of every route.

## Account

`GET /v1/me` says who a key is. It returns `orgId`, `principalId`, `credentialId`, the account's `orgName`, the `role` of the member who made the key (`owner`, `admin`, `developer` or `billing`), and the key's `reach`: `agent` when it acts only on what its own agent made, `compartment` when it acts on what every key of its compartment made, or `account` when it acts on everything in the account. That role limits what the key may do. `GET /v1/usage` shows what the account has and has used. Money is an integer count of microdollars, given as strings (1,000,000 is one dollar). The values are exact, however large:

| Field           | What it is                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------------- |
| `credited`      | Every credit ever added: purchases and grants                                                       |
| `spent`         | Settled usage, including what refunds and disputes took back                                        |
| `expired`       | Credit that expired, or grant credit taken back                                                     |
| `available`     | What can still be spent, after what running sandboxes are about to use                              |
| `takenBack`     | The part of `spent` that refunds and disputes took                                                  |
| `trial`         | Machine time without credit: `{totalMs, usedMs, reservedMs, availableMs, offer, renewsAt}`, or null |
| `freeUsageHold` | Why the account has no free machine time, `{reason, message}`, or null                              |
| `allowances`    | This month's free usage, one row per pool, below                                                    |
| `outbound`      | This month's outbound traffic, below                                                                |
| `kinds`         | Every resource, however many, a row a kind: `{kind, resources, chargedMicros, heldMicros}`          |
| `resources`     | The newest hundred resources, with what each used and was charged                                   |

Each resource has `resourceId`, `name`, `kind`, `state`, `createdAt`, `vcpu` and `memoryMiB` (null for a kind with no size), `runningSeconds` (the billed running time), `activeCpuSeconds`, `memoryGiBSeconds`, `rates` and `chargedMicros`. `chargedMicros` covers every meter, including outbound traffic. Divide it by `runningSeconds` to get the cost of one second of a run.

`outbound` is the account's outbound traffic for this calendar month, in UTC. It has `month` (`2026-09`), `sentBytes`, `freeBytes` (what the allowance covered), `billableBytes`, and `allowanceBytes` (100 GiB). It also has `chargedMicros` and `writtenOffMicros`, as strings. `writtenOffMicros` is traffic that your balance or a spending limit could not cover. It is never charged later ([pricing](./pricing#network-products)).

### Export settled usage

`GET /v1/usage/export?since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z` reads settled usage for every product the key can see. `since` is inclusive and `until` is exclusive. Both are UTC ISO timestamps ending in `Z`. The filter uses when an interval settled, not when its resource was created.

The response is `{since, until, data, nextCursor, finalThrough, csv}`. Each row names the interval and resource, the kind, the meter, the funding, the interval start and end, the settlement time, the billed milliseconds, `chargedMicros`, the quoted component rates, and the measurement evidence. Money and quantities are exact decimal strings. `billedMilliseconds`, measurements and evidence can be null when unavailable.

Each interval is one row, written once when it settles. A later read never changes or repeats it. Before the first page, a read settles your running sandboxes through about a minute ago. So their use appears in the export, not only what ran up to their last hourly window. A read settles up to 100 sandboxes, the longest unsettled first. Only sandboxes paid from credit are settled. A trial's sandboxes are not. Storage is paid an hour at a time. That covers a paused sandbox's memory and disk, a stopped sandbox's disk, images, snapshots, volumes, and volume backups. Each hour appears in the export within a minute of its end, usually within seconds. Pending holds are not in the export. These are the credit set aside for work still running (`heldMicros` in `GET /v1/usage`). A hold becomes a row when it settles.

`finalThrough` is a UTC timestamp before which nothing can still change. No row with a `settledAt` earlier than it can still appear, and rows never change once written. A range whose `until` is at or before `finalThrough` is complete for good. Usage that settles later is stamped at or after it. It is null only when the marker could not be taken in time. In that case, read again. Each row's `final` (and the CSV's last column) is true once its resource is deleted. At that point nothing of it is still running or open, and every charge it will ever have is settled before `finalThrough`. A volume's backups are resources of their own. They bill until their retention ends. So they are not final when the volume is.

Follow `nextCursor` with the same range until it is null. Each page rechecks the key's `usage` permission and resource visibility. These are live reads. Usage that settles after an earlier page can appear on a later page. The server's `csv` includes a header on its first page only. So concatenate the pages unchanged, in order. This range export covers more than the newest hundred resources in `GET /v1/usage`.

`GET /v1/limits` shows what this key may do, and what its agent may still spend:

```json
{
  "access": "full",
  "daily": {
    "limitMicros": "25000000",
    "usedMicros": "3100000",
    "remainingMicros": "21900000",
    "window": "24h"
  },
  "trial": null,
  "credit": {
    "availableMicros": "42500000",
    "dailyPaceMicros": "6100000",
    "runwayDays": 6,
    "lowBelowDays": 5,
    "state": "ok",
    "addedBy": "owner"
  }
}
```

- `access` is `full` (every action in every product), `read` (a read-only key:
  every read, no change and no spending) or `selected` (the actions the key
  names).
- `daily.limitMicros` is the most the key's agent may commit in any 24 hours,
  or null when the owner set no limit. `usedMicros` counts what is charged and
  what its running sandboxes are about to use.
- Past the limit, a create, wake, extension or renewal fails with 402
  `spending_limit_reached` and charges nothing.
- `trial` is the machine time the account can run without credit, in milliseconds. It has the same figures as `GET /v1/usage`. It is null when the account has none, as here. `availableMs` is what a new sandbox without credit can still use. `offer` is `monthly` for the free usage. It is `hours` for an account given free hours before 5 October 2026, which keeps what is left of them. `renewsAt` is when the next month starts. An account that has never paid has its free machine time once, until `freeUntil` on its `allowances` rows. The field keeps its older name, so code that reads it keeps working.

- `credit` is the account's credit. `availableMicros` is what is left now, as `available` in `GET /v1/usage`. `dailyPaceMicros` is a day's spend at this month's pace. Last month's pace is used while this month is under three days old. It is null when nothing is spent. `runwayDays` is the whole days the credit lasts at that pace, as the console's Home shows it. `state` is `low` when credit falls under `lowBelowDays` days. It is `empty` at none. Running paid sandboxes then pause, and new ones are refused. The `credit.low` and `credit.empty` [webhooks](./observability) are sent at the same moments. `addedBy` is `owner` when a person adds credit on the website. It is `agent` when the account was opened with a wallet and no person pays for it. Then its own agent adds credit with `npx withruntime billing topup <usd>` before `runwayDays` reaches 0.

A limit is set, changed or removed only on the website, at [API keys](https://withruntime.com/account/keys). That is done by the member who made the key, or by an owner or admin. A key can make only keys with a daily limit that fits within its own. It cannot change its own limit.

`GET /v1/audit` is the account's audit log, newest first. It records member and role changes, keys, connections, limits, credit, network rules, secrets and deletions. Each entry has `actor`, `at`, `ip`, `requestId`, `via` and `sandbox`. `sandbox` is the sandbox the call came from, when code in it called `http://runtime.internal`. Otherwise it is null. Filter with `action` (`key.created`, or a group such as `member.`). Page with `before=<next>`, and set `limit` (1 to 200). It needs a key with full access, or a read-only key, made by an owner or admin. See [teams](./teams).

`GET /v1/sso` shows the account's single sign-on. It lists each identity provider, its domain, and whether DNS has proven it. It shows the role people join with, whether single sign-on is required, and SCIM directory sync. It is read only, with the same keys as the audit log. An owner changes it on the website. See [single sign-on](./single-sign-on).

`GET /v1/identity/token?audience=sts.amazonaws.com` is for code inside a sandbox. It takes the sandbox's `RUNTIME_ID_TOKEN_REQUEST_TOKEN` as the bearer, not an API key. It returns `{"token", "expiresAt", "issuer", "subject", "audience"}`. That is an OIDC token that names the sandbox. It lasts 10 minutes by default (`lifetimeSeconds` 60 to 3600). See [identity tokens](./identity-tokens).

## Domains, TCP ports, addresses and the tunnel

These are for paid accounts only. See [networking](./networking). Each one is its own product, not a sandbox's:

| Route                                           | What it does                                                             |
| ----------------------------------------------- | ------------------------------------------------------------------------ |
| `POST /v1/domains`                              | `{hostname, sandboxId, port}`: claim a hostname; returns its DNS records |
| `POST /v1/domains/{hostname}:verify`            | Check the TXT record; `active` when it matches                           |
| `GET`, `DELETE /v1/domains/{hostname}`          | One domain; stop serving it                                              |
| `POST /v1/ports`                                | `{sandboxId, port}`: a public TCP port; returns `connect`                |
| `GET /v1/ports`, `DELETE /v1/ports/{id}`        | List (`?sandboxId=`); close                                              |
| `POST /v1/ips`                                  | `{family}`: reserve a dedicated outbound address (4 or 6)                |
| `GET /v1/ips`, `DELETE /v1/ips/{id}`            | List; release                                                            |
| `POST`, `GET`, `DELETE /v1/networks/wireguard`  | Create (`{subnet}`), read or delete the WireGuard tunnel                 |
| `POST /v1/networks/wireguard/peers`             | `{name, publicKey?, routes?}`: add a peer; returns its wg-quick `config` |
| `POST /v1/networks/wireguard/peers/{id}:rotate` | `{publicKey?}`: a new key for the peer                                   |
| `DELETE /v1/networks/wireguard/peers/{id}`      | Remove a peer                                                            |

A dedicated address needs credit on the account. The rest need a kept top-up. Without one, a request gets `payment_required` (402).

## Pages

A list that can grow returns `{"data": [...], "nextCursor": "..."}`. Pass `nextCursor` back as `cursor`. A `null` value ends the list. `limit` is 1 to 100, and up to 500 for `GET /v1/feedback`.

Short lists return `{"data": [...]}` in full, with no cursor. Examples are a sandbox's file watches, mounts, interpreter contexts, desktop recordings and registry credentials. A few lists have their own shape:

- **The audit log,** `GET /v1/audit`, returns `{"events": [...], "next": "..."}`, newest first. Pass `next` back as `before`. A `null` value ends the log. `limit` is 1 to 200.
- **Secrets,** `GET /v1/egress-secrets`, returns `{"secrets": [...], "next": "..."}`, sorted by name. Pass `next` back as `after`. A `null` value ends the list. `limit` is 1 to 100, and 50 by default.
- **Single sign-on,** `GET /v1/sso`, returns `connections`, `scim` and `manage`.
- **Process output and file-watch events** carry their own `nextCursor` beside the chunks or events. **Build logs** return `lines` with `nextAfter`.

## Versions

This is 0.2.0. The OpenAPI document's `info.version` is the version you are talking to.

The 0.1.0 routes under `/v1/resources` were removed on 22 September 2026. Each one returns 410 `upgrade_required`. `details.replacement` names the route that replaced it. [The migration guide](./migrate) maps each old call to its new one.

Each product has one plural name in every path, SDK call, command and MCP tool: `/v1/sandboxes`, `runtime.sandboxes`, `runtime sandboxes`, `runtime_sandboxes`. When a name changes, the old one keeps working for 30 days. Each response to it carries a `Warning` header with the new name, and a `Link` to the new path. The SDKs and the CLI print the warning once. An MCP response carries it as `warning`. Once the day it stops is set, responses also carry `Deprecation` and `Sunset` (that day), and the warning names it. From that day, the old name returns 410 `name_retired`. Its `hint` names the new one.


---

<!-- https://withruntime.com/docs/aws-lambda-microvms-alternative -->

# Runtime vs AWS Lambda MicroVMs

Runtime runs agent code in Firecracker microVMs, like Lambda MicroVMs. For an agent that mostly waits on a model, it costs **85% less**.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $4.20 on Lambda MicroVMs**. At 100,000 runs a month, that is $63.89
against $420.33, **$356 a month saved**. Runtime needs no AWS account, IAM role or VPC set up first.

Comparing more than two providers? [AWS Lambda MicroVMs alternatives](/compare/aws-lambda-microvms-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Lambda MicroVMs bill the baseline vCPUs and
  memory for every second a MicroVM runs, busy or not. Runtime measures the CPU
  your code actually uses. Time spent waiting on a model costs only a small
  floor, a twentieth of a vCPU.
- **Idle time bills only storage.** A Runtime sandbox pauses itself after 300 seconds
  with nothing happening in it. It keeps its memory and processes. While paused, it pays
  $0.08 per GB (10⁹ bytes) of saved state a month.
- **An uptime promise that pays itself.** Paid accounts get
  99% API uptime each month. A month below that returns 10% of that
  month's charges as credit. No claim is needed ([Uptime Promise](/legal/sla)).
- **Lower rates on both meters.** $0.025 per vCPU-hour, against about $0.0997,
  and $0.0075 per GiB-hour of memory, against about $0.0132 per GB-hour. With
  both CPUs busy the whole time, the example job still costs $1.33 on Runtime
  and $4.20 on Lambda MicroVMs.
- **Bigger sandboxes.** A paid Runtime sandbox takes up to 16 vCPUs and 64 GiB.
  Memory is chosen apart from CPU. A MicroVM's baseline tops out at 4 vCPUs
  and 8 GB, always 2 GB per vCPU.
- **Sessions that last.** A MicroVM keeps its state for up to 8 hours. A Runtime
  sandbox has no time limit. It runs while it works, or stays up idle with
  `persistent: true`. A paused one keeps its memory while you have credit.
- **Fork a running machine.** A Runtime fork copies a sandbox as it is now,
  memory and processes included, into up to 100 running copies.
- **Keys the sandbox never sees.** Store an API key once. The sandbox holds a
  placeholder. Runtime's proxy adds the value only to HTTPS requests to the
  hosts you name, so a prompt injection has nothing to leak ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No access key
  goes into a prompt or a config file. The [MCP server](./mcp) reuses the
  same connection.
- **Guardrails for agents.** Read-only keys, a daily spending limit per key and
  `maxTotalCostMicros` on each sandbox keep an agent inside its budget. Every
  write takes an idempotency key.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, private previews, a Linux desktop, metrics,
webhooks, OpenTelemetry export, S3, R2 and GCS bucket mounts, identity tokens for AWS and Google Cloud, and free single sign-on. Paid
accounts add custom domains, TCP ports, dedicated outbound addresses and
WireGuard private networks. See [products](./products).

## At a glance

Lambda MicroVMs' figures come from AWS's public pricing and product pages.
Last checked 25 October 2026. Rates are for Arm (Graviton) in US East (N. Virginia).

|                | Runtime                                                        | AWS Lambda MicroVMs                                                                  |
| -------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Isolation      | Firecracker microVM, own kernel                                | Firecracker microVM                                                                  |
| CPU billing    | $0.025 per vCPU-hour of measured CPU, with a small floor | $0.0000276944 per baseline vCPU-second while running      |
| Memory billing | $0.0075 per reserved GiB-hour                          | $0.0000036667 per baseline GB-second while running     |
| Sizes          | Up to 16 vCPUs and 64 GiB paid, chosen apart | Baseline up to 4 vCPUs and 8 GB, 2 GB per vCPU                                       |
| Session length | No time limit: runs while it works, or `persistent`            | State kept up to 8 hours                                                             |
| Suspend        | Files, memory and processes, kept while you have credit        | Memory and disk in a snapshot, at $0.08 per GB (10⁹ bytes) a month |
| Free start     | 100 free hours of a 1 GB machine in the first 30 days, no card             | No free tier for MicroVMs                                                            |
| Plan fee       | None; prepaid credit from $10                        | None; an AWS account                                                                 |
| Agent sign-in  | Browser approval; no key in the agent's config                 | AWS credentials and IAM                                                              |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox (a 2 vCPU, 4 GB baseline on Lambda
MicroVMs). Each run lasts 60 seconds and keeps the CPU busy for 20 CPU-seconds.
This is an agent that spends most of its time waiting for a model.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025                 = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075            = $0.50
         Total                                                   $0.64

Lambda   CPU    1,000 × 60 s × 2 × $0.0000276944              = $3.32
         Memory 1,000 × 60 s × 4 × $0.0000036667              = $0.88
         Total                                                   $4.20
```

- **Saving:** 85%, or $3.56 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $420.33 on Lambda
  MicroVMs.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $4.20 on Lambda. At this size, Runtime is cheaper however busy the
  sandbox is.

Snapshot storage and its reads and writes, data transfer, taxes and credits are
excluded from both. On Runtime, inbound traffic is free. Each account's first
100 GiB out a month is free, then $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for
Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the MicroVM calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

A MicroVM image built from a container image maps to a
[custom image](./images) built from the same Dockerfile. A MicroVM's HTTPS
endpoint maps to a [preview](./javascript#share-a-port):

```ts check
import { Sandbox } from "withruntime";

const box = await Sandbox.create();
try {
  await box.spawn("python3 -m http.server 8080");
  const preview = await box.previews.create(8080);
  console.log(preview.urlWithToken);
} finally {
  await box.stop();
}
```

## When Lambda MicroVMs may fit better

- **Everything else is on AWS.** A MicroVM reaches your VPC through the Lambda
  Network Connector. It is governed by the IAM policies you already run.
- **Many regions.** AWS runs Lambda in regions worldwide. Runtime runs in one US
  region.
- **Arm code.** MicroVMs run on Graviton. Runtime sandboxes are x86-64.

## Sources

Checked 26 October 2026.

- [AWS Lambda pricing](https://aws.amazon.com/lambda/pricing/)
- [Lambda MicroVMs](https://aws.amazon.com/lambda/lambda-microvms/)
- [Announcing Lambda MicroVMs](https://aws.amazon.com/blogs/compute/announcing-lambda-microvms-serverless-compute-environments-with-vm-level-isolation-and-near-instant-startup/)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/blaxel-alternative -->

# Runtime vs Blaxel

Runtime bills the CPU your agent uses. It costs **81% less than Blaxel** while running an agent that mostly waits on a model.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $3.45 on Blaxel**. At 100,000 runs a month that is $63.89 against
$345.00, **$281 a month saved**. Your Blaxel sandbox code keeps working. Change
one import.

Comparing more than two? [Blaxel alternatives](/compare/blaxel-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **Lower cost while running.** Blaxel bills $0.0000115 per GB of memory per
  second of active time, $0.0414 per GB-hour. CPU comes with the memory.
  Runtime charges $0.0075 per GiB-hour of memory and measured CPU at $0.025 per
  vCPU-hour.
- **A written uptime promise.** 99% API uptime a month for paid accounts,
  measured from outside. 10% of a short month's charges comes back as credit
  automatically ([Uptime Promise](/legal/sla)).
- **Cheaper even when busy.** With both CPUs working the whole time, the example
  job costs $1.33 on Runtime and $3.45 on Blaxel.
- **CPU and memory chosen apart.** Blaxel sets a sandbox's CPU from its memory:
  8 GB gets 4 cores. On Runtime you choose vCPUs and memory separately. A
  CPU-heavy job does not pay for memory it does not need.
- **Idle time costs no compute here either.** A Runtime sandbox pauses itself
  after 300 seconds with nothing happening in it, or after as few as 10 if you
  set it. A paused sandbox pays only paused storage. A command still
  running, an open connection, network traffic or CPU use keeps it awake.
- **Cheaper to keep paused work.** A paused Runtime sandbox keeps its files,
  memory and processes for $0.08 per GB (10⁹ bytes) a month, while you have credit. Blaxel's
  standby snapshots cost $0.20 per GB a month.
- **A one-line switch.** `withruntime/blaxel` runs code written for Blaxel's
  sandbox SDK, in JavaScript and Python: processes, files, previews, snapshots,
  forks and the code interpreter, with no Blaxel key. Credit you add within 30 days of signing up is matched, up to $1,000 in total.
- **Single sign-on at no extra charge.** SAML or OIDC sign-in, SCIM, roles
  and an audit log come with every Runtime account
  ([single sign-on](./single-sign-on)). Blaxel lists SAML among the enterprise
  features of its Dedicated Support add-on.
- **Private networks without a custom plan.** A paid Runtime account joins its
  own network to its sandboxes over WireGuard, for $5 a month
  ([private networks](./networking#private-networks)). Blaxel lists private
  network connectivity on its Custom plan.
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Give an agent a read-only key or a daily spending
  limit per key. Cap any sandbox's whole cost with `maxTotalCostMicros`. Every write takes an
  idempotency key, so a lost response never creates a second sandbox.

**Also included:** a code interpreter, network allow and deny lists, secrets the
sandbox never sees, custom images, volumes backed up daily, snapshots and forks
with memory, private previews, a Linux desktop, metrics, webhooks, OpenTelemetry
export, S3, R2 and GCS bucket mounts and identity
tokens for AWS and Google Cloud. Paid accounts add custom domains, TCP ports and
dedicated outbound addresses. See [products](./products).

## At a glance

Blaxel's figures come from its public pricing and documentation, checked
25 October 2026.

|                | Runtime                                                                              | Blaxel                                                              |
| -------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| Isolation      | Firecracker microVM, own kernel                                                      | Lightweight virtual machines                                        |
| CPU billing    | $0.025 per vCPU-hour of measured CPU, with a small floor                       | Included with memory; 8 GB gets 4 cores                             |
| Memory billing | $0.0075 per reserved GiB-hour                                                | $0.0000115 per GB-second of active time      |
| Paused storage | $0.08 per GB (10⁹ bytes) a month; files, memory and processes      | $0.20 per GB-month snapshot; files and processes |
| Plan fee       | None; prepaid credit from $10                                              | None; tiers grow with credit added                                  |
| Free start     | 100 free hours of a 1 GB machine in the first 30 days, no card                                   | Up to $200 of credit                              |
| Internet out   | First 100 GiB a month free, then $0.02 per GB (10⁹ bytes) | Included                                                            |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox (4 GB on Blaxel). Each run lasts
60 seconds and keeps the CPU busy for 20 CPU-seconds. This is an agent that
spends most of its time waiting for a model.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
         Total                                        $0.64

Blaxel   Memory 1,000 × 75 s × 4 × $0.0000115      = $3.45
```

- **Saving:** 81%, or $2.81 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $345.00 on Blaxel.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $3.45 on Blaxel.

The Blaxel figure includes the 15 seconds or so each sandbox stays billed after
its run, before Blaxel puts it on standby. Storage, network, taxes and free credit are left out of both. On
Runtime, inbound traffic is free. Each account's first 100 GiB out a month
is free. After that, outbound traffic costs $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Blaxel calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### Change one import

Runtime's SDK runs code written for Blaxel's sandbox SDK. Change the import and
set `RUNTIME_API_KEY`, or run `npx withruntime login` once:

```ts no-run
import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"
```

```python no-run
from withruntime.blaxel import SandboxInstance  # was: from blaxel.core import SandboxInstance
```

Sandboxes get Blaxel's default of 4096 MB, with one vCPU for every 2048 MB. A
sandbox pauses after 300 seconds with nothing happening in it. It keeps its
memory, files and processes. It wakes by itself on the next command, file call or preview visit.
Envs, processes by name, files, previews, snapshots, forks, volumes and the code
interpreter carry over. Sandboxes use the free usage first, then prepaid credit. There is nothing to choose.

Four things to know before the first run:

- **Share sandboxes with an account-wide key.** A Blaxel workspace key sees
  every sandbox. A Runtime key sees the sandboxes it made unless an owner or
  admin makes it account-wide, on the [API keys](https://withruntime.com/account/keys)
  page or with `runtime keys create --account-wide`. Give a web service and a
  worker that share sandboxes account-wide keys, or one key
  ([keys in a team](./teams#keys-in-a-team)).
- **Without credit, a sandbox is at most 2 vCPU and 4096 MB.** Blaxel's default fits.
  `memory: 8192` or more needs paid credit.
- **Custom images are Runtime images.** Blaxel's own templates, such as
  `blaxel/base-image`, start Runtime's stock image. Any other image must be a
  ready Runtime image of the same name. Build it once with
  `npx withruntime images build --dockerfile Dockerfile --name <name>`.
- **Private preview tokens work as they did.** Blaxel's
  `X-Blaxel-Preview-Token` header and `?bl_preview_token=` parameter are
  accepted, as are Runtime's own. The token never reaches your server.

**Sessions work as they did.** `sandbox.sessions.create()` makes a Runtime
[sandbox session](./javascript#a-sandbox-from-a-browser). It is a token your
frontend uses to run commands, use files and reach previews of that one
sandbox, and nothing else. Blaxel's default of a day is Runtime's longest.
`responseHeaders["Access-Control-Allow-Origin"]` names the page that may use
it. `SandboxInstance.fromSession(session)` drives the sandbox with the
token alone.

A call Runtime handles differently, such as drives, schedules or Blaxel's
agent and MCP hosting, throws `NotSupportedError` before anything happens. It
names what to use instead. `BLAXEL.md` in the package lists every
mapping. For MCP, run your own server as a process in the sandbox and reach it
through a preview ([MCP servers in a sandbox](./javascript#mcp-servers-in-a-sandbox)). A bucket mounted in several sandboxes shares files between them
([mount your own bucket](./storage#mount-your-own-bucket)). A Blaxel schedule runs a command inside one sandbox. On Runtime, a
[scheduled job](./jobs) runs it on a cron schedule or at a time, in a fresh
sandbox each run.

### Or port the calls

Blaxel:

```js
import { SandboxInstance } from "@blaxel/core";
const sandbox = await SandboxInstance.create({ name: "my-sandbox", memory: 4096 });
const result = await sandbox.process.exec({
  command: "python3 -c 'print(sum([125, 250, 375]))'",
  waitForCompletion: true,
});
await sandbox.delete();
```

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

Moving from Blaxel? Credit you add within 30 days of signing up is matched, up to $1,000 in total ([welcome match](./pricing#welcome-match)).

## When Blaxel may fit better

- **Very large fleets.** Blaxel's top tier runs over 100,000 sandboxes at the same time.
  A tier is the credit topped up over the last 30 days, which is then spent on
  usage: $20 unlocks 50 sandboxes and $50 unlocks 200.
- **Heavy outbound traffic.** Blaxel includes internet egress in its rates.
  Runtime's first 100 GiB out a month are free. After that, the rate is $0.02 per GB (10⁹ bytes).

## Sources

Checked 27 September 2026.

- [Blaxel pricing](https://blaxel.ai/pricing)
- [Blaxel sandboxes](https://docs.blaxel.ai/Sandboxes/Overview)
- [Blaxel usage and quotas](https://docs.blaxel.ai/Security/Quotas)
- [Blaxel proxy and network](https://docs.blaxel.ai/Sandboxes/Proxy)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/changelog -->

# Changelog

What shipped in Runtime Cloud, newest first.

Runtime ships every day. Each entry is something you can use or see; the
guides hold the current terms, and [pricing](./pricing) holds the current rates.
Each day, and each entry, also has a page of its own at
[withruntime.com/changelog](https://withruntime.com/changelog), and every entry
arrives in the [RSS feed](https://withruntime.com/changelog/feed.xml).

## 14 November 2026

- **Catalog MCP servers in a sandbox are withdrawn.** `GET /v1/mcp/catalog` and `/v1/sandboxes/{id}/mcp` return 404 `route_not_found`, with a message that says what to use instead. The SDKs' `mcp` clients, `runtime sandboxes mcp` and the `runtime_sandboxes_mcp` tool are removed. To run an MCP server in a sandbox, start it as a process and share its port with a preview ([MCP servers in a sandbox](/docs/javascript#mcp-servers-in-a-sandbox)). Runtime's own MCP server is unchanged.
- **A paused sandbox wakes for its own timers.** A sandbox paused after its idle seconds wakes by itself shortly before the soonest timer of one of its processes is due: a `sleep`, a poll or wait with a timeout, a timerfd, `alarm()` or `timer_create()` that was pending the whole time it sat idle. A loop that polls every ten minutes, or `sleep 600 && ./next.sh`, now runs on time instead of waiting for the next call. Each such wake is billed as any wake. A timer armed and fired again and again while the sandbox was idle wakes nothing, and a sandbox you paused yourself never wakes on its own.
- **Environment variables on create.** `POST /v2/sandboxes` and `POST /v1/sandboxes` take `env`: up to 32 variables and 32,768 bytes of names and values, set for every command and process in the sandbox and for its start command. Values are stored encrypted and are never returned. A fork or a copy of a snapshot keeps its source's variables. Before, `/v1` ignored `env` and `/v2` refused it.
- **Resize a running sandbox.** `POST /v2/sandboxes/{id}:update` takes `vcpu`, `memoryGB` and `diskGB` (and `POST /v1/sandboxes/{id}:resize` takes `vcpu`, `memoryMiB` and `diskMiB`). The sandbox grows while it runs: its disk and file system, its memory and its vCPUs, with its commands running on. The new size counts against your limits; a size past them returns `403`. A smaller size, or a sandbox that is not running, returns `409` with the reason, and nothing changes.
- **Run a sandbox as root with one setting.** `POST /v2/sandboxes` and `POST /v2/sandboxes/{id}:update` take `user`: `runtime` (the default: uid 1000, with passwordless sudo) or `root`. Every exec and process in the sandbox runs as that user when the call names no `user`; a call's own `user` still overrides it for that call. An image kept from a sandbox keeps its user as the default for sandboxes created from it, and a fork or a copy of a snapshot keeps its source's. Every SDK takes it: `create({ user: "root" })`. The per-call value `sandbox` is now `runtime`; `/v1` and the MCP tools still take `sandbox`.
- **Job secrets can be deleted, and their names reused.** `POST /v1/secrets/{id}:delete` deletes a job secret (with an optional `expectedVersion`), and `GET /v1/secrets/{id}` returns one. After a delete, `POST /v1/secrets` with the same name creates a new secret. Job secrets are now the same secrets as `/v2/secrets` (visible ones): they appear in its list, and machines get them in their environment as before.
- **A fork makes all its copies or none.** `POST /v2/sandboxes/{id}:fork` with `count` is admitted as one start: when the copies together would pass one of your limits (running vCPU or memory) or find no room, the request returns the error and makes no copy. Before, it made copies until the limit and refused the rest. A fork counts as one start against your starts-per-second limit, whatever its `count`.
- **Network rules on create.** `POST /v2/sandboxes` takes `network` (the same `{default, rules}` that `PUT /v2/sandboxes/{id}/network` takes), and `POST /v1/sandboxes` and the `runtime_sandboxes_create` MCP tool take `network` in their own shape (`internet`, `allow`, `deny`, `connect`). The rules hold from the sandbox's first start. Before, v1 and MCP dropped `network` and the sandbox started with the default rules. A create from a snapshot refuses `network` with `400`: set the rules with `PUT /v2/sandboxes/{id}/network` after it starts.
- **A command runs to its end.** `POST /v2/sandboxes/{id}:exec` (and `/v1/sandboxes/{id}:exec`, and the `runtime_sandboxes_exec` MCP tool) with no `timeoutMs` no longer stops the command after 60 seconds: it runs until it exits and returns its exit code and output. `timeoutMs` still sets a limit when you name one. Every SDK waits for the command to end when you name no limit, with no client timeout, and if the answer is cut while the command runs (for example by a release of the API), the SDK sends the request again with the same idempotency key and returns the same run's result, without running it twice.

## 9 November 2026

- **A sandbox says what you can do with it now.** Every sandbox read from `/v1/sandboxes` and `/v2/sandboxes` returns `actions`: the actions that change it from its current state (`pause`, `wake`, `stop`, `restart` and `delete`). A lifecycle action that cannot apply, such as a pause of a starting sandbox, still returns `409`, and its `details` now carry `state` and the same `actions` list; its hint is written for that state. A wait for a state (`?waitFor=running`) now returns immediately once the sandbox cannot get there without a new action, such as a sandbox you stopped, instead of after its whole timeout. Every SDK reads the list: `sandbox.can("pause")` in TypeScript and Python, `Can("pause")` in Go, `can("pause")` in Java and `can?("pause")` in Ruby. The states and every move between them are on [Sandbox states and actions](/docs/sandbox-lifecycle).

## 8 November 2026

- **A `503 busy` says whether the cell could not confirm the request or could not complete it.** Before, every `503 busy` from `/v1/sandboxes` read "The cell could not confirm this in time; it may or may not have been applied.", whatever the cause. That message now comes only when the cell's log or a timeout is the reason. Any other cause, such as a sandbox's disk or its guest not answering, returns "The cell could not complete this right now; it may or may not have been applied." The status, the `busy` code and `details.reason` are unchanged. Retry with the same `Idempotency-Key`.

## 7 November 2026

- **Desktops: capture the screen with `POST /v2/desktops/{id}:screenshot` and drive it with `POST /v2/desktops/{id}:act`.** A screenshot returns the whole screen as base64, as `png` or `jpeg` (set `quality`, 1 to 100), with its width and height. An action moves, clicks, drags or scrolls the mouse by pixel, types text, presses xdotool key names such as `ctrl+l` or `Return`, reads the cursor position, lists the windows and focuses one, opens a URL in the desktop's Chromium, or launches a program. Both run inside the desktop's own sandbox. Returns `400` (`invalid_request`) when a field is outside its limits, `409` (`desktop_not_running`) when the desktop is not running, and `409` (`desktop_failed`) with the command's own error when it fails. Available in every SDK as `desktops.screenshot` and `desktops.act`.
- **Apps, Functions and Containers: volumes are mounted.** A version whose `spec.volumes` names a volume now mounts it in each copy before its process starts. Before, the version failed with `deploy_build_failed: volumes cannot be read here yet`. A volume that is still being created is waited for; one that does not exist, or was deleted after the request was accepted, fails the version with `not_found`. A `POST`, `PUT` or `PATCH` that sets `spec.volumes` needs `volumes:attach`; without it, the request returns 403.
- **Sandboxes: mount a volume through v2.** `POST /v2/sandboxes` accepts `spec.volumes`, a list of at most one `{volume, path}` entry naming a volume of the same project by its ID (`vol_...`). The volume is mounted read-write at its `path` before the sandbox's phase is `running`; a volume that is still being created is waited for. The sandbox writes the volume alone: while it holds it, no other sandbox mounts it, and it cannot be forked. The API key needs `volumes:attach`, and must be able to read the volume: without `volumes:attach` the request returns 403, and a volume the key cannot read, or that does not exist, returns 400. `volumes` is set when the sandbox is created and cannot be changed. Each `path` must be absolute, outside `/proc`, `/sys` and `/dev`, and neither at nor inside a file share's path; otherwise the request returns 400.

## 5 November 2026

- **Status incidents in the API.** `GET /v2/status/incidents` returns the incident notes shown on withruntime.com/status, `status.md` and `status.json`, newest start first, as `{"data": [...]}`. It requires no API key. Each incident has `id`, `title`, `start`, `end` (`null` while ongoing), `saw` and `fixed`; a published note is never rewritten, and later updates are appended to `fixed`. The status page now reads these notes live, so a new or updated incident appears on the page's next load.
- **Per-address limit on creating organizations.** `POST /v2/orgs`, which creates a signed-in person's own organization, is limited to 10 an hour per client IP address (an IPv6 address counts by its /64). A request over the limit returns `429 rate_limited` with a `Retry-After` header giving the seconds until one more request is accepted; the refused request does not count toward the limit.
- **Closing an account deletes its resources.** `POST /v1/account:close` now succeeds for every account; for some accounts it previously returned `500 internal_error`. From the response on, requests with the account's API keys to sandboxes, volumes and the other resource APIs return `401`, and the account's resources are deleted within seconds. Data-bearing resources, such as volumes and snapshots, are held for 7 days before they are purged. The response's `released` field is `false` while that deletion is in progress.
- **Cloud Run: Google's client libraries' `$alt` parameter is accepted.** The Google Cloud Run Admin API at `/compat/google-cloud-run` now accepts the `$alt` query parameter (`json`, or `json;enum-encoding=int`), which Google's Node.js client (`@google-cloud/run`) sends with every REST request. Previously each such request returned 400. Responses are JSON, with enum values as names, which the clients read. Any other `$alt` value returns 400.
- **Seven more launch checks through competitors' APIs on /status.json.** `launch_checks` on `GET https://withruntime.com/status.json` now also returns `dev_environments_codespaces` (Octokit, GitHub's SDK, against the Codespaces API), `containers_fly` (Fly's Machines API), `containers_cloud_run` (Google's Cloud Run client for Node.js), `firewall_security_groups` (the AWS SDK for JavaScript's EC2 client), `uptime_checks_betterstack` (Better Stack's monitors API), `uptime_checks_checkly` (Checkly's checks API) and `sites_vercel` (Vercel's SDK, promoting a release). Each entry creates, uses, reads back and deletes one resource through Runtime's compatible API, with the same fields as the other launch checks. For a product billed per resource (`dev_environments_codespaces`), the entry also confirms that the resource's usage was billed, and its `steps_ms` includes `usage`. The other six products are not billed per resource, so their entries have no `usage` step.
- **`GET /v1/me` returns the key's reach.** The response now includes `reach`: `agent` when the key acts only on what its own agent made, `compartment` when it acts on what every key of its compartment made, or `account` when it acts on everything in the account. The value reflects the key as the API treats it at the time of the request, so an account-wide key whose maker is no longer an owner or admin returns `agent`. Every SDK returns it from `me()`.
- **A build whose identical image is larger than its `maxImageMiB` fails with the size to set.** When your account already had an identical image larger than a new build's `build.maxImageMiB` (8192 by default), the build failed with "The image could not be saved because of a fault on our side". It now fails immediately with `An identical image of this organization is N MiB, larger than this build's build.maxImageMiB of M. Set build.maxImageMiB to at least N.` Set `build.maxImageMiB` to at least that size and the build copies the identical image immediately.
- **Per-address limits on sign-in and API key creation.** Requests that sign in or create an account are limited per client IP address (an IPv6 address counts by its /64): 30 an hour for `POST /v2/sign-in/email`, and 30 an hour for `POST /v2/sign-in/email/verify` and Google or SSO sign-in returns together. Creating or rotating API keys (`POST /v2/keys`, `POST /v1/keys`) is limited to 60 an hour. Each API server applies these limits on its own. A request over a limit returns `429 rate_limited` with a `Retry-After` header giving the seconds until one more request is accepted; nothing is created, and the refused request does not count toward the limit. Accounts that already exist count the same as new ones.
- **Clearer error when a sandbox from an image cannot start.** When the server could not prepare a sandbox's image, `POST /v1/sandboxes` returned `503 busy` with "The cell could not confirm this in time; it may or may not have been applied." It now returns `503 busy` with "This sandbox could not be started on its server, so nothing was made." Retry the create with the same `Idempotency-Key`.
- **Render environment variable endpoints for Apps.** `/compat/render/v1` now serves Render's environment variable endpoints over an App's `spec.env`: list (`GET /services/{serviceId}/env-vars`, paginated by `cursor` and `limit`), replace all (`PUT /services/{serviceId}/env-vars`), get, set and delete one (`GET`, `PUT` and `DELETE /services/{serviceId}/env-vars/{envVarKey}`). Setting or deleting one variable leaves the others unchanged. Getting or deleting a variable the service doesn't have returns 404. `generateValue` returns 400.
- **Sandboxes, Apps and Functions can call App and Function addresses.** A request from a sandbox, an App or a Function to an App's or a Function's address (`https://<name>.runtimehost.com`) used to return `403` with "Destination resolves to a forbidden address". These addresses are now reachable over HTTPS on port 443, as they are from the internet. Private address ranges, Runtime's own servers, and other ports on these names are still refused.
- **Render list pagination reads only the requested page.** On `/compat/render/v1`, `GET /services` and `GET /services/{serviceId}/deploys` now start reading from the position the `cursor` names and stop as soon as the page is full. Previously each request read the whole list first. Without a `name` or `status` filter, a request reads only as many items as the page returns. If the item a cursor names is deleted before the next request, that request returns the next page instead of 400. The page may repeat items, but no item is skipped. Cursors are opaque strings, and cursors returned before this change continue to work. A `cursor` value that the list did not return returns 400.
- **Paused sandboxes started from a custom image survive the loss of their host.** A paused sandbox started from your own image is no longer stopped when its host is lost, as long as its saved copy is complete and another host holds the image. Its next wake restores it from that copy on a host that holds the image. While no such host can take it, a wake returns `503 no_capacity` with the detail that it starts from its saved copy as soon as one has room. If the image is deleted or rebuilt, or no other host holds it, the sandbox is stopped as before, and its parked charge ends when its host was lost.
- **A wake whose host does not answer fails within about a minute.** A paused sandbox whose host did not answer its wake used to stay in `resuming` for as long as the host stayed silent, and every request on it waited. The wake now gives up after two unanswered attempts (about a minute): requests on the sandbox return `500 operation_failed` immediately, its memory and files are kept, and nothing is charged. A minute later the host is asked again; once it answers, the sandbox is `paused` and the next request wakes it.
- **App versions and Render deploys.** `GET /v2/apps/{id}/versions` lists an app's versions, newest first and paginated by `limit` and `cursor`. `GET /v2/app-versions/{id}` returns one version. A version is numbered by the app generation that created it, so the response to the `PATCH` that creates a version identifies it. A new `spec.rollout` value creates a new version with the same settings. Render's deploy endpoints are now served under `/compat/render/v1`: list deploys (filterable by `status`), get a deploy, create a deploy (`imageUrl`, or a redeploy of the current image), and roll back to an earlier deploy (`POST /services/{serviceId}/rollback`). A deploy's ID is its version number. Creating a deploy, or changing the image with `PATCH /services/{serviceId}`, clears an earlier rollback, so the new version goes live. `commitId` and `buildId` return 400, and cancelling a deploy is not supported.

## 4 November 2026

- **Render API for Apps.** The web service endpoints of Render's REST API are served under `/compat/render/v1`, so Render API clients and the `render` CLI manage Apps by changing only their host (`RENDER_HOST`) and API key (`Authorization: Bearer <key>`). Supported: create an image-backed web service (`POST /services`, `type` `web_service`, `runtime` `image`), list, get, update its name, image, plan and health check path, scale (`POST /services/{serviceId}/scale`) and delete. Lists return `[{"cursor", "service"}]` and are paginated with `cursor` and `limit` (20 by default, at most 100), and can be filtered by `name`. The plans `starter` (the default), `standard`, `pro`, `pro_plus`, `pro_max` and `pro_ultra` create an App with 1, 1, 2, 4, 4 or 8 vCPUs and 0.5, 2, 4, 8, 16 or 32 GiB of memory, billed by measured use; each copy serves on port 10000, Render's default `PORT`. Errors return Render's status codes and `{"id", "message"}` body. A field or operation Apps does not support yet, such as `repo` or deploys, returns 400 or 404.
- **Desktops: E2B Desktop API.** Desktops now accept E2B's sandbox REST API with its `desktop` template at `/compat/e2b-desktop`: set `E2B_API_URL` to `https://<your API host>/compat/e2b-desktop` and `E2B_API_KEY` to a Runtime API key, and E2B Desktop's SDKs (`@e2b/desktop`, `e2b_desktop`) can get, list (paginated by `nextToken`), connect to, extend the timeout of, pause and kill Runtime desktops. Creating a desktop from the `desktop` template with `timeout` and `metadata` is supported over the REST API; a timeout under 60 seconds returns 400. The SDKs' screen, mouse, keyboard, screenshot and stream methods, and their `Sandbox.create()`, which starts the screen through commands inside the sandbox, are not yet available. Desktops also gain `spec.endsAt` (a later time extends the timeout), and Browsers and Desktops gain `status.endsAt`.
- **Launch checks on /status.json.** `GET https://withruntime.com/status.json` now returns `launch_checks`, one entry per product that launches with the next platform release (Browsers, Desktops, Notebooks, Dev environments, Actions runners, Cron, Apps, Functions, Containers, Load balancers, Firewall, Uptime checks, KV, Queues and Sites). Each hour, a test account creates, uses, reads back and deletes one resource of each product through the public API and confirms that its usage was billed. Three more entries run the same steps through a competitor's own SDK against Runtime's compatible API: `browsers_browserbase` (Browserbase's Node.js SDK), `kv_cloudflare` (Cloudflare's SDK) and `functions_lambda` (the AWS SDK for JavaScript's Lambda client). Each entry returns `state` (`passed`, `failed` or `not_served`), `checked_at`, `total_ms`, and `steps_ms` with the time of each step; a failed entry also returns `failed_step` and `error`.
- **Upstash QStash schedules API for Cron.** QStash's schedules endpoints are served under `/compat/qstash`, so the `@upstash/qstash` client manages Cron jobs by changing only its base URL and token. Supported: create (`POST /v2/schedules/{destination}` with `Upstash-Cron`, `Upstash-Method` and the request body), get, list, pause, resume and delete. Each schedule is a job that sends the request to the destination on the cron schedule in UTC, with up to 3 retries, and is billed by measured use. A header not supported yet, such as `Upstash-Retries` or `Upstash-Forward-*`, returns 400 with its name. Errors return QStash's status and `{"error"}` body.
- **Balancer targets receive requests only after their first health check passes.** When a balancer has `spec.health`, each target starts out of rotation: a new target, or every target on a host whose router has just restarted, receives no requests until its first health check passes, which happens within about 100 ms. One passing check is enough, whatever `healthyThreshold` is. While no target has passed yet, a request waits for the first check result instead of going to every target. If no target passes, requests go to all targets, as before. A target whose first check fails is reported unhealthy immediately.
- **Start action for Dev environments.** `POST /v2/dev-environments/{id}:start` starts an environment immediately: a paused environment is woken, and a stopped one starts again from its disk, even when `spec.state` is already `running`. If `spec.state` holds another state, it is set to `running`. The response is the environment. Returns 409 (`environment_stopping`) while a stop is in progress, and 409 (`environment_not_resumable`) when the environment's disk was not kept. Every SDK has a `start` method. GitHub Codespaces' start (`POST /user/codespaces/{codespace_name}/start` under `/compat/github`) uses it, so it also starts a codespace that was shut down for being idle.
- **Cloud Run: `gcloud run revisions list --service`.** In the Google Cloud Run Admin API at `/compat/google-cloud-run`, v1's `namespaces.revisions.list` now returns a service's revisions when `labelSelector` is `serving.knative.dev/service=<name>`, as `gcloud run revisions list --service <name>` sends it. Each revision is a version of the Container, as a Knative Revision, and only revisions of the service in the request's project and location are returned. A request without that selector, such as `gcloud run revisions list` with no `--service`, or with any other selector, returns 400. The v1 `namespaces.revisions.list` and `namespaces.services.list` methods also accept `limit` and `continue`: with either, the response is one page, and the next page's token is in `metadata.continue`. Without them, the response holds every item. A repeated `labelSelector`, `limit` or `continue` returns 400.
- **Containers: versions, and Cloud Run revisions.** `GET /v2/containers/{id}/versions` returns a container's versions, newest first and paginated with `limit` (1 to 100, default 20) and `cursor`. `GET /v2/container-versions/{id}` returns one version by its ID, which is the container's ID, a dot, and the version's number (`ctr_....3`). Both accept the container's slug in place of its ID and require the key's `containers:get` permission. Each version returns its `number`, `state` (`building`, `warming`, `ready`, `live`, `failed` or `superseded`), `image`, `imageDigest`, `failure`, the container `generation` that made it, and the container's `labels`. The SDKs read them with `containers.versions(id)` and `containers.version(id)`. In the Google Cloud Run Admin API at `/compat/google-cloud-run`, `services.revisions.list` (paginated with `pageSize` and `pageToken`) and `services.revisions.get` now return these versions as revisions named `<service>-<version>`, and v1's `namespaces.revisions.get` (`gcloud run revisions describe`) returns one as a Knative Revision. A revision of another service, location or project returns 404. Deleting a revision is not yet available, and v1's revisions list returns 404.
- **Sandboxes: a fork waits for room, as a create does.** When no server has room for a copy, `fork` now retries with the same idempotency key for up to two minutes, as `create`, `wake` and `restart` do, in every SDK and in `withruntime sandboxes fork`. A fork refused for room pauses nothing and charges nothing. Set the wait as for a create (`waitForCapacityMs` in JavaScript, `wait_for_capacity` in Python and Ruby, `WaitForCapacity` in Go, `waitForCapacity` in Java); 0 fails immediately, and the CLI's `--no-wait` fails immediately. A fork of one copy now needs only the room a create of the same size needs; before, it needed four times its memory free on one server. A fork of many copies is still held to a quarter of each server's free memory past its first copy there, and is refused with `details.fits` when fewer copies fit. A fork that has already failed returns `retryable: false`, because its idempotency key returns the same error.

- **Containers: Cloud Run revisions are named, and traffic can be pinned to one.** In the Google Cloud Run Admin API at `/compat/google-cloud-run`, each version of a Container is a revision named `<service>-<version>`, such as `hello-3`. In v2, a service now returns `latestCreatedRevision` (the newest version), `latestReadyRevision` (the version serving requests) and `trafficStatuses`. In v1, it returns `status.latestCreatedRevisionName`, `status.latestReadyRevisionName` and `status.traffic[].revisionName`. Sending 100% of traffic to one revision sets the Container's `spec.version`, which rolls it back to that version: in v2, `traffic` with `type: TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION` and `revision`; in v1, `spec.traffic` with `revisionName`, as `gcloud run services update-traffic --to-revisions hello-2=100` sends. Traffic to the latest revision (`TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST`, or `latestRevision: true`) removes the pin. A revision of another service, a revision without a version number, or a revision named in a create returns 400. A traffic split between revisions returns 400, and `revisions.list`, `revisions.get` and `revisions.delete` are not yet available.

- **Better Stack TCP monitors keep their type.** In the Better Stack compatibility API, a `PATCH` that changes a TCP monitor's `monitor_type` to `status`, `keyword` or `expected_status_code` now returns 400; previously it changed only the reported type while the check kept probing TCP. Delete the monitor and create a new one to change its type.
- **Better Stack TCP monitors.** The Better Stack compatibility API at `/compat/betterstack` now accepts `monitor_type: "tcp"` with `url` (the host) and `port`, and creates an Uptime check on `tcp://<host>:<port>`; the monitor returns its host and port as Better Stack does. A TCP monitor without `port` returns 400. A TCP monitor's host and port, and a change to or from `tcp`, can't be updated, because an Uptime check's URL is fixed: such a request returns 400 (a `port` must be sent with its `url`); delete the monitor and create a new one.
- **Better Stack expected-status-code monitors.** The Better Stack compatibility API at `/compat/betterstack` now accepts `monitor_type: "expected_status_code"` with `expected_status_codes` (a list of HTTP status codes); the Uptime check passes only those codes, and the monitor returns them as numbers. A request with that type and no codes returns 400. On other monitor types the codes are ignored, as on Better Stack, and changing a monitor to another type restores the default passing statuses (200 to 399).
- **Browserbase sessions accept `keepAlive`.** `POST /compat/browserbase/v1/sessions` accepts `keepAlive: true` (previously 400). On Browsers, every session runs until its `timeout` (default 3600 seconds) or until you release it with `REQUEST_RELEASE`, whether or not a client is connected. A session created without `keepAlive` also keeps running after its client disconnects. To stop billing for it, release it or set `timeout`.
- **Containers: a `slug` addresses a container, and Cloud Run services keep the name requested.** Containers accept an optional `spec.slug`: 1 to 63 lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen, unique within the project and set at create only. A create that repeats a slug in use returns 409 `conflict`, and the slug is released when the container is deleted. `GET`, `PATCH` and `DELETE /v2/containers/{id}` accept the slug in place of the ID; other kinds whose `name` is unique within the project, such as queues, accept that name the same way. A request by name requires the key's `get` permission on the kind. In the Google Cloud Run Admin API v2 at `/compat/google-cloud-run`, `services.create` now stores `serviceId` as the container's slug: the service's `name` is `projects/{project}/locations/{location}/services/{serviceId}`, and `services.get`, `services.patch` and `services.delete` accept that name. A second create with the same `serviceId` in the project returns 409 instead of returning the first service; a service created without `serviceId` is named by its container ID, as before. A slug is unique within a project, not within each location. A service's `description` now returns 400 instead of being stored as the container's `name`.
- **Browserbase session list rejects an unknown status.** `GET /compat/browserbase/v1/sessions` returns 400 when `status` is not one of `RUNNING`, `ERROR`, `TIMED_OUT`, `COMPLETED` or `PENDING` (the values are case-sensitive), as Browserbase does. Previously it returned an empty list.
- **Console: the Sandboxes, Browsers and Desktops lists show every sandbox, wherever it runs.**
  For many accounts the lists showed only sandboxes made before the account
  moved to Runtime's new servers, and none made since. The lists now include
  them for every account. A sandbox that moved while paused shows its current
  state; before, it showed paused, and a woken one was missing from the
  Running tab. "Stop all long-running" reads the same list.

## 3 November 2026

- **Better Stack's monitors API over Uptime checks.** Better Stack Uptime API calls for monitors (`GET` and `POST /api/v2/monitors`; `GET`, `PATCH` and `DELETE /api/v2/monitors/{id}`) run against Runtime Uptime checks at `/compat/betterstack` with a Runtime API key as the bearer token. Status and keyword monitors are mapped: URL, name, HTTP method, check frequency, request timeout, regions and required keyword. Any other field set in a request, including `paused: true` and `follow_redirects: true`, returns 400 with a message that names the field. Only a `keyword` monitor checks `required_keyword`, as on Better Stack; a keyword monitor requires it, and a monitor changed to `status` stops checking for it. A monitor's `url` can't be changed; delete the monitor and create a new one.
- **GitHub Codespaces API for Dev environments.** The Codespaces endpoints of GitHub's REST API are served under `/compat/github`, so Octokit and other GitHub clients manage Dev environments by changing only their base URL and token (`Authorization: token <key>` or `Bearer <key>`). Supported: create in a repository (`POST /repos/{owner}/{repo}/codespaces`), list, list in a repository, get, update the display name, start, stop, delete, and machine types for a repository or a codespace. Lists are paginated with `page` and `per_page` (30 by default, at most 100), return the full count in `total_count`, and return a `Link` header to the next and last pages. The machine types `basicLinux32gb`, `standardLinux32gb` (the default), `premiumLinux` and `largePremiumLinux` create an environment with 2, 4, 8 or 16 vCPUs and 8, 16, 32 or 64 GiB of memory, billed by measured use. Stop pauses the environment with its memory kept. A field Dev environments does not support yet, such as `devcontainer_path`, returns 400 with its name.
- **Containers: Google Cloud Run Admin API v2.** Containers now accept the Cloud Run Admin API v2 services methods at `/compat/google-cloud-run`: set the client's endpoint to `https://<your API host>/compat/google-cloud-run` and use a Runtime API key as the bearer token. `services.create`, `services.get`, `services.list` (paginated with `pageSize` and `pageToken`), `services.patch` and `services.delete` are supported; each service is a Container labeled with its project and location, and a service under another project or location returns 404. One container's `image`, `command`, `args`, `env` (name and value pairs), `workingDir`, one port, `resources.limits.cpu` (1, 2, 4 or 8) and `resources.limits.memory` (512Mi to 32Gi), `scaling.minInstanceCount`, `scaling.maxInstanceCount` and `maxInstanceRequestConcurrency` map to the Container's spec, with Cloud Run's defaults: a service scales to zero unless `minInstanceCount` is set. Any other field returns 400 with a message naming it. Create, patch and delete return their operation with `done: true`, so clients do not poll. `services.patch` replaces the whole template, so its body must include `template.containers[0].image`; `updateMask` and `etag` return 400. A service's name holds its Container ID, not the `serviceId` requested; `serviceId` follows Cloud Run's rule (1 to 49 lowercase letters, digits and hyphens, starting with a letter) and is the create's idempotency key for 24 hours, so a retried create returns the same service instead of creating a second one; once that service is deleted, a create with the same `serviceId` creates a new one. Revisions, traffic other than 100% to the latest revision, `validateOnly`, `allowMissing` and the IAM methods are not yet available.
- **Containers: flyctl and fly-go.** flyctl and Fly's Go client (fly-go) now run against Runtime's Fly Machines API unchanged. These clients discard the path of `FLY_FLAPS_BASE_URL` and send `/v1/apps/...`, so the `/compat/fly` base URL from the earlier entry did not reach them. Requests whose `User-Agent` starts with `flyctl/` or `fly-go/`, or that include flyctl's `Fly-Client-Parent` header, are now served Fly's API at the root of the API host. Set `FLY_FLAPS_BASE_URL`, `FLY_API_BASE_URL` and `FLY_UIEX_BASE_URL` to `https://api.withruntime.com` and `FLY_API_TOKEN` to a Runtime API key, so that no flyctl request is sent to Fly. `fly machine run`, `list`, `stop`, `start` and `destroy` are supported. `GET /v1/apps/{app_name}`, the organization lookup and the image lookup that `fly machine run` performs are supported. `GET /v1/apps/{app_name}/machines/{machine_id}/wait` returns 200 when the machine is in a requested `state`, at the requested `version` or `instance_id` if one is given, and 408 immediately when it is not, because a Container's state changes only through a request. `from_event_id` is accepted and ignored. `GET /v1/apps/{app_name}` returns 200 for any app name. A stop request now accepts `id`, `timeout` and `signal: "SIGTERM"`; any other signal returns 400. A machine's `instance_id` is a string, as Fly's clients expect. Other HTTP clients continue to use `https://api.withruntime.com/compat/fly` as their base URL.
- **Queues: SQS-compatible status codes for authentication and size errors.** The SQS-compatible endpoint now returns 403 for `AccessDenied` and for every `InvalidClientTokenId`, and 413 for `RequestEntityTooLarge`; these errors previously returned 400 (and `InvalidClientTokenId` returned 400 or 403 depending on where the request was refused). `AddPermission` and `RemovePermission` are not supported and return 400 `UnsupportedOperation`: access to a queue comes from the access key's grant.
- **Functions: AWS Lambda `Invoke`.** The AWS Lambda API on Runtime Functions now supports `Invoke`, so `invoke` in AWS's SDKs runs a function after you change only the endpoint and the keys. The payload is sent as a `POST` to the function's address (`status.url`). With `InvocationType` `RequestResponse` (the default), the call returns 200 with the function's response body. When the function returns a 4xx or 5xx status, the response also includes `X-Amz-Function-Error: Unhandled`. A function whose response is larger than 6 MB, whose connection closes before it responds, or that runs longer than 15 minutes also returns 200 with `X-Amz-Function-Error: Unhandled`, and an `errorType` of `Function.ResponseSizeTooLarge`, `Runtime.ExitError` or `Sandbox.Timedout`, so SDKs do not retry an invocation that may have run. When the function cannot accept the request, `Invoke` returns 429 `TooManyRequestsException` or 500 `ServiceException`. `DryRun` returns 204 without running the function, including for a function that has no address yet. `Event` is not yet supported and returns 400 `InvalidParameterValueException`. A function that has no address yet returns 409 `ResourceConflictException`. A payload larger than 6 MB returns 413 `RequestTooLargeException`. Concurrent invocations are limited per organization; past the limit, `Invoke` returns 429 `TooManyRequestsException`. `Qualifier`, `LogType: Tail` and `ClientContext` are not supported.
- **Browserbase session list filters on Browsers.** `GET /compat/browserbase/v1/sessions` (`sessions.list` in Browserbase's SDK) accepts `status` (`PENDING`, `RUNNING`, `COMPLETED` or `ERROR`) and `q` in Browserbase's metadata query form, `user_metadata['key']:'value'`, and returns only the sessions that match both. A session whose browser is still starting now reports `PENDING` instead of `RUNNING`. A `q` in any other form, including a nested path such as `user_metadata['a']['b']:'value'`, returns 400: session metadata on Browsers holds only string values at the top level.
- **Browserbase's session debug URLs on Browsers.** `GET /compat/browserbase/v1/sessions/{id}/debug` (`sessions.debug` in Browserbase's SDK) returns the session's `wsUrl` (its Chrome DevTools Protocol WebSocket URL) and, when the browser draws its screen, its live view as `debuggerUrl` and `debuggerFullscreenUrl`; otherwise those are empty. `pages` is always empty; the browser's pages are listed at its `httpUrl` (`/json/list`).
- **Queues: SQS-compatible error status codes.** The SQS-compatible endpoint now returns the HTTP status Amazon SQS returns for each error. For example, `DeleteMessage` with an invalid receipt handle and `CancelMessageMoveTask` for a task that does not exist now return 404 instead of 400. Every operation and error is checked against AWS's published SQS API model.
- **Checkly's checks API over Uptime checks.** Checkly API calls for API and URL checks (`POST /v1/checks/api`, `POST /v1/checks/url`, `PUT` on each, `GET /v1/checks`, `GET` and `DELETE /v1/checks/{id}`) run against Runtime Uptime checks at `/compat/checkly` with a Runtime API key as the bearer token. Frequency, locations, maximum response time, the URL, the method and one status-code assertion are mapped; any other field set in a request returns 400 with a message that names the field.
- **Balancers and Ports: target weights and failover.** Each entry in `spec.targets` accepts `weight` (1 to 1,000, default 1) and `backup` (default `false`). When targets have different weights, each request (or, for a port, each connection) goes to a target with a probability of its weight over the sum of the weights; when weights are equal, it goes to the target with fewer requests in flight of two chosen at random. On a balancer, a backup target receives requests only while no other target is healthy and has capacity; on a port, it receives connections only while every other target's sandbox is stopped or deleted. Available in every SDK.
- **Apps, Functions and Containers: health checks while serving.** `healthPath` is now also checked while a copy serves: every 5 seconds, each copy is sent a GET of the path, and a copy that fails 2 consecutive checks (no status under 500 within 2 seconds) receives no requests until it passes 2 consecutive checks. Previously the path was checked only before a copy took its first request. During a staged release that changes `healthPath`, the service's address checks only that each copy's port accepts a connection until the release completes. A `healthPath` that does not start with `/` is checked as `/`, as the check before the first request already does. A path with characters a URI path cannot contain, such as a space or `#`, is not sent: the check only confirms that the copy's port accepts a connection.
- **Containers: Fly Machines restart.** `POST /compat/fly/v1/apps/{app_name}/machines/{machine_id}/restart` is now supported. It creates a new version of the machine's Container with the same settings, and that version's copy replaces the running one. The `timeout` query parameter is accepted. `signal` returns 400, because the restart replaces the copy instead of signaling its process. As with the other machine routes, a machine is found only under its own app.
- **Speed page: daily history charts and provider comparison.** The
  [speed](./speed) page now charts each listed operation's median own time
  for each of the last 90 days, against its physical floor. Hover over a day
  to see its p95, p99 and sample count. When another provider has been
  measured the same way and Runtime is faster, the page also lists it beside
  the matching Runtime operation, comparing total times.
- **CI/CD: a job that fails because its machine ran out of disk says so in its reason.**
  When a job's machine runs out of disk, the error is often never written to
  the job's log, because the log is on the same full disk. Such a job's
  reason was the log's last error, for example
  `error: build failed, waiting for other jobs to finish...`. The job's log
  now ends with a line that says the machine ran out of disk
  (`error: No space left on device: ...`), and its reason names that line.
- **Speed: browser create time and rival providers, measured the same way.**
  `browsers.create` is now measured every five minutes. The time runs from
  `POST /v1/browsers` until the browser's CDP WebSocket answers
  `Browser.getVersion`, which is the point where Playwright or Puppeteer can
  connect. The CDP exchange carries no `Server-Timing`, so all of its time is
  counted as Runtime's own. `speed.json` also includes a `rivals` array. Each
  rival is timed from the same location as Runtime, through the provider's
  own public API, to the same outcome as the Runtime operation it is compared
  with (`compares`). Browserbase, Steel, Hyperbrowser and Browser Use are
  timed until CDP answers. E2B, Daytona and Vercel Sandbox are timed until
  the sandbox is running. Rivals return no `Server-Timing`, so each line
  reports total time only. A rival is listed only after it has been measured
  with its own API key; nothing is estimated. Each rival's history is
  available from `speed/history.json?op=rivals.<name>.<operation>`
  ([speed](./speed)).
- **Sites (beta): static websites served with no machine.** A site is files and a route table (redirects, rewrites, headers, Markdown for agents, 404 pages) served by every front. `POST /v2/sites` creates one; `:missing` returns the files, by SHA-256, the site does not hold yet, `:upload` stores each, `:release` stages a release and `:publish` makes it live in one commit. `:rollback` publishes the previous release, also in one commit, and keeps the release it replaced so it can be published again. Both `:publish` and `:rollback` accept `ifVersion` and return 409 if another change came first. `:releases` returns the live release, the earlier ones and the ones rolled back from. A deleted site stops serving and keeps its releases; restoring it serves its live release again. `npx withruntime sites deploy ./dist` runs all of these for a folder and uploads only the files that changed. Every SDK, the CLI and the MCP tools include Sites. Usage is billed on the existing storage, operations and egress meters at their current rates.
- **Speed history by the hour and by the day.** Each listed operation's
  hourly and daily p50, p95 and p99 (Runtime's own time, the network's part
  and the total), sample count and failure count are now kept indefinitely
  and returned by
  `https://status.withruntime.com/speed/history.json?op=<id>&step=hour|day&from=&to=`.
  `from` and `to` take a date (`2026-11-03`) or an ISO 8601 time and are
  rounded down to the step; by default a request returns the last 48 hours,
  or the last 365 days with `step=day`. A request returns at most 744 hourly
  or 3,660 daily points, and returns 400 for an unknown operation or an
  invalid range. Percentiles are computed from each hour's or day's own
  samples. Responses are cached for one minute ([speed](./speed)).
- **Containers: Fly Machines API.** Containers now accept Fly's Machines REST API at `/compat/fly/v1`, so clients written for `api.machines.dev` run against Runtime after you change only the base URL and the token: use `https://<your API host>/compat/fly` as the base URL and a Runtime API key as the bearer token. For flyctl's Machines calls, set `FLY_FLAPS_BASE_URL` to the same base URL. Each machine is a Container with one copy, labeled with its app. Creating, showing, updating and deleting a machine, listing an app's or an organization's machines, starting, stopping and suspending a machine, and reading and writing its metadata in all six forms are supported. A machine's `image`, `env`, `guest.cpus`, `guest.memory_mb`, `init.cmd`, `init.entrypoint`, `metadata`, one service's `internal_port`, one mount and `restart.policy` (`no` or `always`) map to the Container's spec; any other config field returns 400 with a message naming it. As on Fly, an update replaces the machine's whole config, so a field it omits is removed; listing machines returns every machine, not one page; and a machine ID is found only under its own app, so a request under another app returns 404. `auto_destroy: true` returns 400. Restart, wait, events, versions, exec, signal, processes, leases, cordon and the memory routes are not yet available and return 404.
- **Sandboxes: E2B API.** Sandboxes now accept E2B's REST API at `/compat/e2b`, so code that uses E2B's SDKs (`e2b`, `@e2b/code-interpreter`) can create and manage Runtime sandboxes after you change only the API URL and the API key: set `E2B_API_URL` to `https://<your API host>/compat/e2b` and `E2B_API_KEY` to a Runtime API key. Creating a sandbox from the `base` template with `timeout`, `metadata` and `autoPause`, getting and listing sandboxes (paginated by `nextToken`), setting the timeout, pausing, connecting (which resumes a paused sandbox) and killing are supported. Running commands and reading or writing files inside the sandbox through E2B's SDK are not yet available. A request that sets an unsupported field, such as `envVars` or another template, returns 400 with a message naming the field.
- **Browserbase's sessions API on Browsers.** Browserbase's Node.js SDK (`@browserbasehq/sdk`) works with Runtime Browsers when `BROWSERBASE_BASE_URL` is set to `https://<your API host>/compat/browserbase` and `BROWSERBASE_API_KEY` to a Runtime API key. `POST /v1/sessions` returns a running session with its `connectUrl` (the browser's Chrome DevTools Protocol WebSocket URL), `GET /v1/sessions/{id}` and `GET /v1/sessions` read and list sessions (a list of more than 100,000 sessions returns 400), and `POST /v1/sessions/{id}` with `status: "REQUEST_RELEASE"` ends one. Fields and operations not yet supported (`region`, `keepAlive`, proxies, contexts, debug URLs, recordings) return 400 or 404 instead of being ignored.
- **Functions: AWS Lambda API.** Functions now accept the AWS Lambda API, signed with AWS Signature Version 4, so code that uses AWS's SDKs (such as boto3) runs against Runtime Functions after you change only the endpoint and the keys. Create an access key pair with `POST /v2/aws-access-keys`, authenticated with a Runtime API key; it returns `accessKeyId` and `secretAccessKey`, reaches what that API key reaches, and stops working when that API key is revoked or expires. Set `AWS_ENDPOINT_URL_LAMBDA` to `https://<your API host>`, set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to the pair, and use a function's ID as `FunctionName`. `GetFunction` (`FunctionName`, `MemorySize`, `Environment` and `LastModified`), `ListFunctions` with `Marker` and `MaxItems`, and `DeleteFunction` are supported. Errors return Lambda's exception names, such as `ResourceNotFoundException`. A qualified function name or an ARN returns 400 `InvalidParameterValueException`. `Invoke`, `CreateFunction`, `UpdateFunctionCode`, `UpdateFunctionConfiguration`, versions and aliases are not yet available and return 404.
- **Notebooks: connect JupyterLab, VS Code or any Jupyter client.** The URL that `POST /v2/notebooks/{id}:open` returns now also accepts its secret as a Jupyter token, sent as `Authorization: token <secret>` or `?token=<secret>`. Jupyter clients use Jupyter Server's REST API (`/api/kernels`, `/api/sessions`, `/api/contents`) and the kernel WebSocket without changes, and share the kernel with cells run through `:execute`.
- **Firewalls.** `POST /v2/firewalls` creates a named rule set that ports and balancers attach to with `firewallId`. Each rule blocks, allows or rate-limits HTTP requests by IP address or CIDR block, path, method or header; a rule that matches ports applies to raw TCP connections only. Rules are checked at write by the same parser and compiler every host enforces them with. A change to a firewall applies to every route attached to it one commit later, without a write to the routes. A rate limit counts each client across every route attached to the firewall. A route with `firewallId` takes no inline `firewall`; the request returns 400. A route attached to a deleted firewall refuses every visitor. Available in the API, the SDKs, the CLI and the MCP tools.
- **KV: Cloudflare Workers KV API.** KV stores now accept Cloudflare's Workers KV REST API at `/compat/cloudflare/client/v4`, so code that uses Cloudflare's SDKs runs against Runtime KV after you change only the base URL and the API token: set `baseURL` to `https://<your API host>/compat/cloudflare/client/v4`, `apiToken` to a Runtime API key, and use a KV store's ID as the namespace ID. Reading, writing and deleting a value, and listing keys with `prefix`, `limit` and `cursor`, are supported. A request that sets expiration or metadata returns 400 with a message naming the unsupported parameter; bulk operations and namespace management are not yet available and return 404.
- **Browsers: capture a page with `POST /v2/browsers/{id}:screenshot`.** Opens `url` in a new tab, waits for its load event, and returns the image as base64 with the page's final URL, title and HTTP status; without `url`, it captures the page the browser shows now. Set `fullPage` to capture the whole page, `format` to `png` or `jpeg`, and `waitMs` (up to 10000) to wait for late scripts. The capture runs inside the browser's own sandbox. Returns `409` (`browser_not_running`) when the browser is not running and `504` (`page_timed_out`) when the page does not load within 30 seconds. Available in every SDK as `browsers.screenshot`.
- **Balancers: health checks.** A balancer's `spec.health` sets how each target is checked, with the fields of an AWS ALB target group: `path`, `intervalSeconds`, `timeoutSeconds`, `healthyThreshold` and `unhealthyThreshold`. A target that fails `unhealthyThreshold` consecutive checks receives no requests until it passes `healthyThreshold` consecutive checks. Available in every SDK.
- **Sandboxes: upload links replace files in root-owned folders.** A `PUT` link from `POST /v1/sandboxes/{id}/files:link` to a path under `/workspace` whose folder is owned by root (for example, a tarball extracted with `sudo`) returned `404` with `This upload is not open in the sandbox.` The upload now replaces the file atomically, as `files_write` does, and the new file is owned by the sandbox user. When the sandbox user cannot write the folder (outside `/workspace`), the link returns `403 permission_denied` with the folder named, instead of `404`.
- **GitHub Actions runners in every SDK.** `/v2/runners` is now in the API reference and the OpenAPI document, and every SDK makes its calls as `runners.settings`, `runners.enable`, `runners.disable`, `runners.jobs` and `runners.job`. `GET /v2/runners/jobs` returns `{"jobs": [...]}`; `GET /v1/actions/jobs` still returns the array.
- **Sandboxes: lists and lookups include every sandbox of an organization being moved to Runtime 2.0.** While an organization has sandboxes on both Runtime 1.0 and Runtime 2.0, `GET /v1/sandboxes` returns them all in one paginated list, in the same order and with the same fields as before. `GET`, exec, files and `DELETE` on a sandbox return from wherever it runs, and the console's Sandboxes page shows both. Before, a sandbox created on Runtime 2.0 might be missing from the list, and requests for it returned 404.
- **Plans: `includedMicros`, `yearlyOnly` and `trialUsageMicros`.** `GET /v1/plans` returns three new fields on each plan: `includedMicros`, the usage included each month (null when the fee and `bonusMicros` are the plan's usage); `yearlyOnly`, whether the plan is billed yearly only (choosing such a plan monthly returns `409`); and `trialUsageMicros`, the usage a trial includes (`"0"` for none). Every current plan returns `null`, `false` and `"0"`. The TypeScript, Python, Go, Ruby and Java SDKs include the fields.

## 2 November 2026

- **Sandboxes: exec on a newly created sandbox returns as soon as the command exits.** In some regions, `POST /v1/sandboxes/{id}/exec` on a sandbox created at the default size could hang until the client's timeout. The first exec after a create now returns in about 35 ms, and later ones in about 6 ms.
- **API keys limited to a compartment reach only that compartment's sandboxes.** On Runtime 2.0, a key limited to one compartment (project) now lists only that compartment's sandboxes, and `GET`, `DELETE`, `:exec`, files, processes and every other sandbox route return 404 for a sandbox in another compartment, the same response as for a sandbox that does not exist. A sandbox created on Runtime 2.0 before this change has no recorded compartment: a compartment's key reaches it only if that key created it. Account-wide keys still reach every sandbox in the account. A create with a `name` that a sandbox the key cannot reach holds returns 409 `name_taken` without naming that sandbox, and `getOrCreate` never returns it.
- **CI/CD: a failed job's reason names its first error.** The reason shown for a failed job, in the console and on its GitHub check run, was the last line of its log, which for a build is often a line such as `error: build failed, waiting for other jobs to finish...`. It is now the first error line that names a cause (for example `error[E0308]: mismatched types`), or a `No space left on device` line when the machine ran out of disk. When a long log is shortened, every error line is kept, including `error:` lines without a code, and a compiler's quoted source lines are no longer taken for an error.
- **API v2: filter sandboxes and other machines by `phase`.** The lists of sandboxes, browsers, desktops, dev environments, databases, Kubernetes clusters and notebooks (`GET /v2/{resources}`) accept `phase` (`pending`, `running`, `paused`, `stopped` or `failed`) and return only the resources in that phase. For example, `GET /v2/sandboxes?phase=running` returns the running sandboxes. The filter reads an index that is updated in the same write as the status, so a resource appears under its new phase as soon as its status shows it. The TypeScript, Python, Go, Ruby and Java SDKs take `phase` in each of these lists' filtered queries.
- **API v2: lists return the API v1 ID of each moved resource with `include=movedFrom`.** Every v2 list (`GET /v2/{resources}`) accepts `include=movedFrom`, which adds `movedFrom` to the page: the ID of each item that moved in from API v1 mapped to the ID it had there. Items created in v2 are not in it. On a metered resource, `include=usage,movedFrom` returns both. Any other `include` value returns `400`. The TypeScript, Python, Go, Ruby and Java SDKs return the page's `movedFrom`, and the CLI takes `--include movedFrom`.
- **API v2: lists return each resource's usage to date with `include=usage`.** A list of a metered resource (`GET /v2/{resources}`, for every resource that has `:usage`) accepts `include=usage`, which adds `usage` to the page: each item's ID mapped to what it has used from the month it was created (`since`) to now, with the same figures as `:usage` (`windows`, `heldMs`, `cpuBilledUsec`, `memoryMibMs` and `chargedMicros`), summed over those months. The page is still one request, so a list that shows each resource's cost no longer needs one `:usage` call per item. Any other `include` value returns `400`, as does `include` on a resource that is not metered. The TypeScript, Python, Go, Ruby and Java SDKs take `include` on `list` and return the page's `usage`, and the CLI takes `--include usage`.
- **API v2: lists return resources newest first with `order=newest`.** Every v2 list (`GET /v2/{resources}`) accepts `order=newest`, which returns resources by `createdAt`, newest first, and pages with `cursor` as before. `order=oldest`, the default, keeps today's ID order. Labels and filters apply on top of either order. A key limited to the resources it created returns `400` for `order=newest`. The TypeScript, Python, Go, Ruby and Java SDKs take `order` on every `list`, and the CLI takes `--order oldest|newest`.
- **Sandboxes: commands run as the sandbox user, and the HTTP proxy works at every size.** On some sandboxes, commands, processes, terminals and file writes ran as root even though the sandbox reported `user: "sandbox"`. They now run as the sandbox user (uid 1000) with its `HOME`, and files written through the files API are owned by that user, as on every other sandbox; `user: "root"` still runs a command through `sudo`. On those sandboxes, every request sent through the built-in proxy (`HTTPS_PROXY`, `http://127.0.0.1:10800`) at a size other than the default returned `502` with `Connection reset by peer`; the proxy now carries them. `/workspace` is owned by the sandbox user, the host name `runtime-guest` resolves (so `sudo` no longer prints `unable to resolve host`), and `PATH`, `NO_PROXY` and `NODE_USE_ENV_PROXY` are set as on every other sandbox.
- **Sandboxes: bucket mounts succeed and stay mounted.** `POST /v1/sandboxes/{id}/mounts` checked whether the mount's client was still running by the size of its cgroup's process list, which the kernel always reports as 0. Every mount was therefore taken for a client that had exited: the request returned `422 mount_failed` with "the bucket did not mount", and the client was stopped even when the bucket had mounted. The check now reads the process list itself. A mount returns `200` once the bucket is mounted, `GET /v1/sandboxes/{id}/mounts` reports `mounted: true` for it, and `POST /v1/sandboxes/{id}/mounts:unmount` waits for the client to exit before it returns.
- **Sandboxes: sessions work for every sandbox.** `POST /v1/sandboxes/{id}/sessions`, `GET /v1/sandboxes/{id}/sessions` and `POST /v1/sandboxes/{id}/sessions/{sessionId}:revoke` now work for every sandbox, and the `rtsess_` token a session returns can be used with every sandbox. Previously, these requests returned `409 served_elsewhere` for some newly created sandboxes. Sessions behave as before: a token reaches only its own sandbox's commands, files and previews, from the origins it lists, and is rejected with `401` on its next request once it is revoked or expires, or once the API key that created it is revoked.

## 1 November 2026

- **Sandboxes: browser, desktop and MCP on every new sandbox.** `/v1/sandboxes/{id}/browser` (`:start`, `GET`, `:stop`), `/desktop:start`, `/desktop:act`, `/desktop/screenshot`, `/desktop:stop` and `/mcp` (`POST`, `GET`, `DELETE`) previously returned 409 `served_elsewhere` for sandboxes created on the new platform. They now return the same request and response shapes as for any other sandbox.
- **Sandboxes: network rules work for every sandbox.** `GET /v1/sandboxes/{id}/network` and `PUT /v1/sandboxes/{id}/network` now work for every sandbox. Previously, these requests returned `409 served_elsewhere` for some newly created sandboxes. The rules have not changed: a change applies to open connections too, so a connection the new rules refuse is closed, and the response reports `enforced: true` once the sandbox's server applies the new version. A sandbox created with `network` rules can now also be created from a snapshot; previously that request returned `501 feature_unavailable` for some newly created sandboxes.
- **Sandboxes: a verb the API key does not allow returns 403, and older keys can wake, extend, update, set retention and restart.** A request for a sandbox operation that the API key's grant does not include now returns `403 forbidden`; previously some of these requests returned `409 served_elsewhere`, and retrying them at the address in the error returned the same error again. API keys created before November 1, 2026 that can create sandboxes can now also call `:wake`, `:extend`, `:update`, `:retention`, `:restart`, `:fork`, `:resize` and `:switch-image` on them, as newer keys can. No change to existing keys or code is needed.
- **Sandboxes: a fork returns 409 `fork_unsafe` when a copy would repeat the source's random numbers.** A fork (`forkOf`, or `POST /v1/sandboxes/{id}:fork`) copies every process's memory, including the state of each language runtime's own random number generator. The kernel's generator is reseeded in every copy, but Node's UUID cache and OpenSSL generator, Python's `random` and `ssl` generators and Java's `SecureRandom` are reseeded only when the process loads Runtime's reseed shim. A fork whose source runs a Node, Python or Java process that the shim does not reach now returns `409 fork_unsafe`, names each such process, and makes no copy; previously the copies started and could return the same UUIDs, tokens and keys as the source and as each other. While a copy is made, the source's Node, Python and Java processes are paused for a few milliseconds, so no copy runs one of them before it is reseeded.
- **Sandboxes: a fork with `count` above 1 makes its copies in parallel.** `POST /v1/sandboxes/{id}:fork` with `{"count": 4}` previously made each copy after the one before it; it now makes them at the same time and records them in one commit, so a fork of 4 copies of a running sandbox returns in 216 ms at the median instead of 340 ms.
- **Tailscale: new sandboxes can join a tailnet again.** `POST /v1/sandboxes/{id}/tailscale`, `GET /v1/sandboxes/{id}/tailscale`, `DELETE /v1/sandboxes/{id}/tailscale`, and the `tailscale` field on `POST /v1/sandboxes` and `POST /v1/sandboxes/{id}:update` now work for every sandbox. Previously, these requests returned `501 feature_unavailable` for some newly created sandboxes. The rules have not changed: the auth key is read from your job secret with your key's own permission to reveal it and is never returned or logged. While a sandbox is on a tailnet, forking it or taking a memory snapshot of it returns `409 tailscale_joined`. If a create with `tailscale` cannot join, the sandbox is stopped and the request returns `422 tailscale_failed`.
- **API: keep-alive connections stay open across Runtime releases.** When a server's API process was replaced during a release, a request in progress on a keep-alive connection could be answered with `connection: close`, and the client had to open a new connection. The connection now moves to the new process between two requests, after the last response is sent in full, and stays open. Connections whose last request had a body, HTTP/1.0 connections, and connections whose response included `connection: close` are closed after their response instead, as before.
- **Jobs: a vouch is no longer cleared by secrets scoped to other sandboxes by ID.** Any change to an egress secret's scope, including a list of other sandboxes' IDs, cleared every vouch in the organization, and the job's runs carried no `job_vouched_by` claim in their identity tokens. Scopes by sandbox ID no longer affect a vouch, except for a run whose own sandbox ID is added to one, which carries no `job_vouched_by` claim. A change to a secret with no scope, a label or App scope, a secret's policy, or the upstream proxy still clears the vouch until an owner or admin vouches again. Vouches that were in effect when this change was released remain in effect.
- **Keys: `POST /v1/keys` no longer slows down or returns 502 `keys_unavailable` in accounts with many keys.** In an account holding tens of thousands of keys, creating a key could take 15 seconds or more and return `502 keys_unavailable`, and other requests in the account waited while it ran. Creating a key now reads only the chain of keys that made the calling key and the keys under a maker with a daily limit, and completes in under 100 ms in an account with 50,000 keys.
- **Sandboxes use included free usage before credit in every region.** A sandbox's running time is charged to the month's included free usage first, then to credit, in every region where the account runs sandboxes. A sandbox pauses only when both are used up; a wake then returns `402 insufficient_credit` until credit is added. At the start of each month, the new month's included usage applies immediately for accounts whose included usage renews monthly.
- **API keys: keys Runtime creates for your builds, CI/CD checks, app versions, agent sessions and Actions runners no longer count toward the limit of 1,000 live keys per member.** Previously, a busy CI/CD repository could fill the limit with its checks' short-lived keys, and `POST /v1/keys` returned `409 limit_reached` to the member who connected it. Those keys are still bounded by the work that uses them and expire with it.
- **`spreadFrom` keeps a new sandbox off its peers' servers.** `POST /v1/sandboxes` accepts `spreadFrom` again: 1 to 16 IDs of your own sandboxes. The new sandbox starts on a server that none of them is running on, and stays apart from them each time it is placed again. When no other server has room, the create returns `503 capacity_unavailable` immediately and nothing is made or charged. An ID this key cannot read returns `400 invalid_request`. Snapshot IDs are not accepted in `spreadFrom`, and a create that copies a snapshot returns `501 feature_unavailable` when it sets `spreadFrom`.
- **Sandbox creates in a full region fail immediately and name the size.** When no server in the region has room for a new sandbox, `POST /v1/sandboxes` now returns `503 capacity_unavailable` immediately, before any state is written, and the error message states the vCPUs and memory that could not be placed. Retry after the `Retry-After` delay with the same `Idempotency-Key`, or request a smaller sandbox.
- **Sandboxes: creates from an existing image no longer return 404 `image_not_found` for some accounts.** `POST /v1/sandboxes` could return `404 image_not_found` (or `snapshot_not_found`, `volume_not_found`) for an image, snapshot or volume that exists in the account. The create now succeeds in the same request, and a retry with the same `Idempotency-Key` returns the same sandbox.
- **Sandboxes: creates no longer return 501 or an immediate 503 for some accounts.** `POST /v1/sandboxes` could return `501` (for example `env_unavailable` or `feature_unavailable`) or an immediate `503` for request bodies the API supports. A create rejected before anything was applied now succeeds in the same request, and a retry with the same `Idempotency-Key` returns the same sandbox. A `503 busy` whose create may have been applied is still returned, so a retry never creates a second sandbox.

- **Correct clock after a restore.** A sandbox created from a template, forked, or woken from a pause now reads the correct wall-clock time from its first instruction. Previously, such a sandbox could read the time at which its memory snapshot was saved.
- **Creates from an image that cannot boot return 404.** `POST /v1/sandboxes` now returns 404 `image_not_found`, naming the image and the reason, when the image is not the organization's or was deleted. Previously it returned 503 `busy`, so retries failed the same way. Nothing is created.
- **Requests that carry a secret's placeholder are never sent unreplaced.** If the server running a sandbox has not received secret updates in the last 15 seconds, a request that carries a secret's placeholder, or that a secret's header rules apply to, returns `503` with `Retry-After: 1` and `X-Runtime-Egress: secret-not-current` instead of being sent with the placeholder. Retry the request.
- **Files: watches work in sandboxes created from the default image.** `POST /v1/sandboxes/{id}/files/watches` (and `files.watch()` in the SDKs) returned `500 watch_failed` ("The watch exited while starting") in sandboxes created from the default image. A watch now runs in every image, and when one fails to start, the error message includes the exit code and the reason the sandbox reported.
- **Sandbox creates move off a failed host immediately.** When the host chosen for a new sandbox has failed and refuses connections, `POST /v1/sandboxes` now places the sandbox on another host immediately, instead of returning `503` until the failed host's lease expires (about 2 seconds). If that host had already started creating the sandbox, the request still waits for it, so each `Idempotency-Key` creates at most one sandbox.
- **A Function with no running copy starts one for its next request.** A request to a Function that has scaled to zero waits at the router while a copy is started from the version's saved copy, then is answered; it no longer returns `503 machine_no_capacity` after 10 seconds. `sleepAfterMs` now applies: a copy that requests no longer need keeps running for `sleepAfterMs` after its last request before it stops, so requests a moment apart reach a running copy.
- **A crashed process restarts immediately.** When the process of an App, a Function or a container exits, its first restart now happens immediately instead of after 1 second; an App's process killed with `SIGKILL` answers requests again about 60 ms later. A process that exits again still waits 1 second, then 2, 4 and so on up to 60 seconds, and ten exits within 10 minutes still mark it `failed`.
- **CI/CD: always run a pull request's own tests.** A split step with `own: true` (`split: { files: "**/*.test.{ts,tsx}", own: true }`) runs the test files a change adds or changes that no other step's `split` names. With such a step in `runtime.yml`, a pull request that adds or changes a test file no step runs (any language: TypeScript and JavaScript, Python, Go, or a Rust crate's files) fails with a `tests not run` job that lists each file and the reason. Configs without an `own` step are unchanged.
- **Parallel forks no longer return `503 busy` while a snapshot copy arrives.** When a snapshot's own server was full, creating many sandboxes from that snapshot at once could return `503 busy` ("Cloud is busy; retry"). It happened when a create joined a copy of the snapshot that was arriving on another server. These creates now succeed, and the copy finishes arriving alongside them.
- **CI/CD checks every push of the branches you list.** Add `pushes: [{ branch: next, steps: [...] }]` to the production branch's `.runtime/checks.yml` to check each push of a branch that has no pull request of its own, such as a staging branch. Each such check runs only the named steps, appears on GitHub as `runtime @ <branch>` rather than `runtime`, and once started it runs to its own verdict instead of being replaced by a newer push.
- **Slack triggers in the v2 Agents API.** `POST /v2/agents/slack/installs` returns a link that adds Runtime's Slack app to a workspace, valid for 15 minutes; `POST /v2/agents/slack/installs:finish` completes it with Slack's `code` and the link's `state`, and accepts only a key of the project that created the link. `GET /v2/agents/slack/teams` lists the project's workspaces and `DELETE /v2/agents/slack/teams/{team}` removes one. `POST /v2/agents/{id}/triggers` with `kind: "slack"` and `config: {team, channel}` adds a trigger: each new message in the channel starts a session, each reply in its thread is sent to the same session, and the session's replies, status, questions and result are posted in that thread. Triggers are read with `GET /v2/agents/{id}/triggers` and `GET /v2/triggers/{id}`, changed with `PATCH /v2/triggers/{id}`, paused and resumed with `POST /v2/triggers/{id}:pause` and `:resume`, and deleted with `DELETE /v2/triggers/{id}`.

## 31 October 2026

- **Sandbox creates no longer wait on an unresponsive host.** When the host chosen for a new sandbox stops responding before it starts creating the sandbox, `POST /v1/sandboxes` places the sandbox on another host, usually within 2 seconds, instead of waiting for that host for up to several minutes. If that host had already started creating the sandbox, the request waits for it, so that each `Idempotency-Key` still creates at most one sandbox. If the cell cannot confirm where the sandbox may be created, the request returns `503`; retry with the same `Idempotency-Key`.
- **Stopping a sandbox always completes.** A stop that could not be recorded used to leave the sandbox in `stopping` permanently, and every request on it returned `500 operation_failed`. The stop is now retried automatically every 5 minutes until the sandbox is `stopped`; meanwhile requests on it still return `500 operation_failed` immediately, its files are kept, and nothing is charged. Sandboxes already stuck in `stopping` are stopped by the same retry.
- **Previews wait for a server that is still starting.** Within 60 seconds after a sandbox is created or wakes, a preview or TCP port request to a port that is not listening yet now waits up to 10 seconds for the port to open, and is forwarded as soon as it does. Previously it returned `502` with `x-runtime-preview-error: port_closed` immediately, so a health check sent right after create failed until the server started. After 10 seconds the request still returns `502 port_closed`. Requests to a port that is already listening are not delayed.
- **Forks of a sandbox in use no longer fail with `sandbox_not_paused`.** If a command or other request woke the source between the fork's pause and the start of its copy, `POST /v1/sandboxes/{id}:fork` returned `409 sandbox_not_paused`. Requests that wake a sandbox automatically now wait until the copy has started, up to one minute, and then proceed as before.
- **Postgres read replicas follow the standby.** On a Postgres database with `spec.standby` set to `true`, each read replica now streams its changes from the standby instead of the primary, so no replica is ever ahead of the standby. When the standby is promoted after a host loss, the replicas keep running at the same host names and continue to receive changes from the new primary without being recreated. A database whose host is lost while its `state` is `paused` or `stopped` now also fails over to its standby, then pauses or stops, and its read replicas are removed; previously its standby and read replicas kept running, and were billed, until the database was deleted.
- **Exec returns all of its output.** `POST /v1/sandboxes/{id}:exec` now returns every byte a command writes to stdout and stderr, up to 256 MiB of each stream in a JSON response and with no limit in a streamed one. Previously the JSON response kept at most 64 KiB of each stream for a command of 60 seconds or less, and 1 MiB for a longer one. The response adds `stdoutBytes` and `stderrBytes`, the bytes each stream wrote, and `truncated`. The new `maxOutputBytes` parameter limits the response to that many bytes of each stream; a stream it cuts has its truncation flag set to `true`. The TypeScript, Python, Go, Ruby and Java SDKs return the same output and take the same limit (`maxOutputBytes`, `max_output_bytes`, `MaxOutputBytes`). `withruntime sandboxes exec` takes `--max-output-bytes`. `runtime_sandboxes_exec` over MCP returns `stdoutBytes`, `stderrBytes` and `truncated`. Sandboxes started before this change keep the 64 KiB limit until they are stopped and started.
- **Forks succeed when the source is woken during the fork.** `POST /v1/sandboxes/{id}:fork` pauses the source while it copies it. If another request woke the source during that time (for example, a command run on it), the fork returned `409 not_paused`, said the source stayed paused, and left its copies running. The fork now returns its copies, and the source keeps running.
- **Apps and Functions accept a start command.** `spec.command` on `/v2/apps` and `/v2/functions` sets the process each copy runs, as an argument list, with `PORT` set to `spec.port`. When the process exits, it is restarted automatically, and its last 8 KiB of output is kept in the copy at `~/.runtime/process-<version>.status`. A version that fails its health check includes that output in `status.failure`. When `command` is omitted, the image's start command runs, as before.
- **A failed fork deletes the copies it started.** When `POST /v1/sandboxes/{id}:fork` fails after some copies have started, the copies that started are now deleted and no longer appear in `GET /v1/sandboxes`. The error's `details.startedSandboxIds` still names them, and `details.copiesDeleted` is `true`. When the error is a 5xx, a failure on Runtime's side (for example, no capacity for a later copy, a copy that does not reach `running` in time, or the source cannot be woken), none of their running time is billed and `details.copiesBilled` is `false`. When it is a 4xx, caused by the request or the account (a limit or quota, or a copy or the source deleted or changed during the fork), the time they ran is billed. A copy whose create completed after the fork had already failed is deleted too. A copy that could not be deleted at once is named outside `details.deletedSandboxIds`, `details.copiesDeleted` is `false`, and it is deleted within 15 minutes. If the server handling the fork stops before it returns, the fork is marked failed with a 500 once it has run longer than any fork can (15 minutes, plus about 20 seconds for each GiB of the source's memory), and its copies are deleted unbilled within 15 minutes after that. A fork that does not answer within the request deadline is a failure on Runtime's side, and its copies are not billed; if your client closes the connection before the fork answers, the copies are deleted and billed for the time they ran. Previously these copies kept running, and were billed, until you stopped them.
- **Reads are served while a cell's storage is full.** When a cell's drives are short of space, `GET` requests now succeed instead of returning `503 api_unavailable`, including a project's first request after a front restarts. Requests that change state return `503 capacity_unavailable` with a `Retry-After` header; retry them with the same `Idempotency-Key`.
- **Fixed: file shares and streams for sandboxes created with `POST /v2/sandboxes`.** In regions served by the new API, a sandbox created with `spec.fileShares` could fail with "mounts file shares, which this cell's machines do not", and `GET /v2/sandboxes/{id}/streams` returned 404 for any sandbox created through `/v2`. Volumes and file shares are now mounted as they are for `POST /v1/sandboxes`, and exec and pty streams reach the sandbox. One file share can be mounted read-write in several sandboxes on different hosts at once.
- **Postgres synchronous standby with automatic failover.** Set `spec.standby` to `true` on a Postgres database to keep a synchronous standby on another rack. A commit is acknowledged only once it is on the standby too. If the database's host is lost, the standby is promoted in its place without a request: the database keeps its ID, host name, port and password, holds every acknowledged commit, and accepts writes again within seconds; a new standby is then made on another rack, and until it runs, commits are acknowledged without a copy on another rack. `status.standby.phase` is `running` once every commit waits for the standby. The standby is billed as a database of the same size that never pauses.
- **Password sign-in is faster.** `POST /v2/auth/sessions` with an email and password now checks the password while the sign-in attempt is recorded, instead of after it, and reads the clock alongside the account lookup. On cell 1 the median sign-in dropped from about 47 ms to about 35 ms. Responses, throttling, and the attempt count are unchanged: an attempt is always recorded before the response is sent, and a throttled email is refused before its password is checked.
- **`getOrCreate` always returns the one sandbox that holds a name.** Concurrent `POST /v1/sandboxes` requests with `getOrCreate: true` and the same `name` now return the same sandbox, including when that sandbox is paused, stopped with its disk kept, or being moved between regions. Previously, under load, a second sandbox could be created under the same name, and later calls by that name could return either one. A create with a `name` that cannot be placed at that moment, for example while capacity is short, returns 503 `busy` with `Retry-After` and creates nothing; retry it. In the Vercel-compatible TypeScript SDK, `Sandbox.getOrCreate` now creates a missing sandbox with `getOrCreate`, and so does `get_or_create_sandbox` in the Vercel-compatible Python SDK. Concurrent calls for the same name return the same sandbox instead of failing with 409 `name_taken`. `resume: false` still leaves a found sandbox paused.
- **Sandbox list pagination returns every page.** `GET /v1/sandboxes` no longer returns `400 invalid_request` (`cursor`) on the second or later page for organizations whose sandboxes run in more than one cell. Each sandbox is returned exactly once, oldest first, and `nextCursor` stays an opaque string to pass back unchanged. `withruntime sandboxes ls` and every SDK's list iterator page through the full list.
- **A terminal that cannot open names the missing file.** When a sandbox's image cannot open a terminal for a `pty` process or stream (for example, an image without a devpts at `/dev/pts`), the error now names the file that failed, such as `/dev/ptmx: No such file or directory`, instead of the system error alone.
- **`idempotency_key_reused` errors include `details` on every route.** A 422 `idempotency_key_reused` now always returns `details.firstUsedAt` and `details.operation`, naming when the key was first used and for which operation. Some routes previously omitted `details`.
- **A fork retried with its `Idempotency-Key` after a 503 now creates its copies.** When `POST /v1/sandboxes/{id}:fork` returns 503 because its copies could not be opened, nothing is created, and sending the same request again with the same `Idempotency-Key` now forks the sandbox, instead of returning `500 operation_failed` ("its copies were withdrawn") on every retry. A fork that succeeded returns its original response to a retry with its key, including after its copies are deleted, and never forks again.
- **Pull request checks into non-default branches use at most half of an account's CI/CD machines.** Checks of pull requests whose base is a branch other than the repository's production branch now hold at most half of the machines the account can run at once, combined. The other half stays available for checks of the production branch and of pull requests into it, so those start immediately even when many pull requests into another branch are being checked. A check waiting on this limit shows the reason in its jobs: how many machines checks into other branches hold and the most they may hold.
- **Requests that a secret's rules do not allow now return 403 from Runtime.** A request that carries an egress secret's placeholder in a credential header, to a method and path that none of the secret's `rules` allows, is no longer sent to the destination with the placeholder. It returns `403 Forbidden` with `X-Runtime-Egress: secret-rule-not-matched`, and the body names the secret, the method and the path. Previously the destination received the placeholder and typically returned `401` with no explanation. The `sandbox.secret_not_applied` event with reason `rule_not_matched` is still sent.
- **A process start whose program is missing returns `422 program_not_found`.** When the program to run, or the interpreter it names (a script's `#!` line or a binary's loader), does not exist in the sandbox (for example, an image without `/usr/bin/env`, through which a command named without a path runs), `POST /v1/sandboxes/{id}/processes` now returns 422 with the code `program_not_found` and the missing path in `details.path`, instead of `502 guest_failed`. A `cwd` that does not exist returns `422 cwd_not_found`. Nothing runs, and a retry returns the same response.
- **Interpreter `503 busy` errors include their cause.** When a code interpreter request returns `503` with code `busy`, `error.details.cause` now describes why the request could not be confirmed, for example that the interpreter process exited before it answered. Use it to tell a transient condition that a retry resolves from one that persists.

- **Commands start faster in new sandboxes.** `POST /v1/sandboxes/{id}:exec` and process starts no longer wait for the API to look up the organization's egress secret placeholders. The sandbox supplies them from its host before every command, so each command still receives them. A command in a sandbox seconds old previously waited about 1.4 s for that lookup.
- **Egress secrets reach every new sandbox.** A sandbox whose start carried no organization in its network rules trusted the egress CA but received none of its organization's secrets: their variables were missing from commands, and requests to the secrets' hosts were sent without credentials. Such a sandbox now gets its secrets like any other.

- **SDK methods for workflow runs, steps and events.** The TypeScript, Python, Go,
  Java and Ruby SDKs add `workflows.start` and `workflows.runs` for a workflow's runs,
  `jobs.start` for a job's run, `jobRuns.getStep` and `jobRuns.recordStep` for a run's
  durable steps, and `jobEvents.send` for events. In TypeScript, `withruntime/workflows`
  exports them, and `runSteps()` authenticates with the run's `RUNTIME_RUN_TOKEN`.
  `PUT /v2/job-runs/{id}/steps/{name}` with none of `output`, `error`, `sleepUntil` and
  `event` now records the step with a `null` result instead of returning `400`, so a
  step that returns nothing is kept and does not run again.

- **Run tokens for job and workflow runs.** Each run gets a token in its
  `RUNTIME_RUN_TOKEN` environment variable. Send it as `Authorization: Bearer` to
  `GET` and `PUT /v2/job-runs/{id}/steps/{name}` for the run's own steps, so a
  workflow no longer needs an API key in its `env`. A run token works only for its
  own run's steps.
- **Idempotency keys for job and workflow runs expire after 24 hours.** An
  `Idempotency-Key` sent to `POST /v2/workflows/{id}/runs` or `POST /v2/jobs/{id}/runs`
  returns the run it started for 24 hours; after that, the same key starts a new run.
- **Durable steps and events for workflows in the v2 API.** `POST /v2/workflows/{id}/runs`
  starts a workflow run with an `input` (and `POST /v2/jobs/{id}/runs` a job's run), once
  per `Idempotency-Key`. A run's code records each step's result with
  `PUT /v2/job-runs/{id}/steps/{name}` and reads it back with `GET`, so a continued run
  replays it; a step can sleep until a time or wait for an event, sent with
  `POST /v2/job-events`, and its run continues when the time or event arrives.

- **Sandboxes: mount file shares.** `POST /v2/sandboxes` accepts `spec.fileShares`, a list of up to 16 `{name, path, readOnly}` entries; each file share of the project is mounted at its `path` before the sandbox's phase is `running`, and again each time it resumes or starts. The API key needs `file-shares:read` on each share, and `file-shares:write` on each one not mounted `readOnly`: a share the key cannot read, or that does not exist, returns 404; one mounted read-write by a key that may only read it returns 403. `fileShares` is set when the sandbox is created and cannot be changed. A sandbox with file shares cannot be forked, and a sandbox started from a snapshot mounts none. Writes to a share mounted `readOnly` return `EROFS`. Each `path` must be absolute, outside `/proc`, `/sys` and `/dev`, and neither at nor inside another share's path; otherwise the request returns 400.
- **Alerts: count rules.** `PUT /v2/alerts/rules/{id}` now accepts rules with `"query": {"kind": "count", "selector": "...", "window_ms": ...}`. A count rule counts the log lines that match a LogQL stream selector and line filters (for example `{service_name="api"} |= "error"`) within the window, and fires when the count crosses its condition. Each line is counted once, as soon as it is accepted, so a count rule's webhook is sent about 10 ms after the line that fires it.
- **Sandboxes: call the API without a key.** A sandbox created with `spec.permissions` (for example `["sandboxes:list", "sandboxes:create"]`) can call `https://api.withruntime.com` without an API key. Its host adds a short-lived token for that sandbox to each request and replaces any `Authorization` header the sandbox sends, so no credential is ever stored in the sandbox. Each action must be one the creating key allows; otherwise the create returns 403. A fork gets its own identity with its source's permissions. `permissions` cannot be changed after a sandbox is created.
- **Alerts: delete a rule.** `DELETE /v2/alerts/rules/{id}` deletes a rule and returns `{"id": ..., "deleted": true}`, or 404 when no such rule exists. A rule can be deleted while its alerts are firing: evaluation stops within a second, and each firing alert is sent to the rule's webhooks once more with status `resolved`. The limit of 100 rules per organization now also holds when rules are created concurrently; a create past the limit returns 400.
- **Logs: faster live tail.** `GET /v2/logs/v1/logs/tail` now delivers a line about 15 ms after it is accepted, down from about 100 ms. A tail now waits for new lines instead of checking for them on an interval.
- **CI/CD setup can be a list of layers.** `setup:` in `runtime.yml` now also accepts a list of up to 16 commands, run in order. A push to the production branch keeps each finished layer as a snapshot, keyed to that layer, the layers before it, the machine size and the `cache` files. A later setup starts from the deepest layer that is ready and runs only the layers after it, so a change to the last layer does not run the earlier ones again, and a setup that is stopped or fails partway keeps the layers it finished. Pull request checks start from these snapshots but never write them. A `setup:` of one command works as before.
- **Logs: live tail.** `GET /v2/logs/v1/logs/tail?query=` now streams matching log lines as Server-Sent Events, resumable with `Last-Event-ID`. A tail stays open for as long as the API key that opened it is valid. It ends with an `end` event with code `tail_unauthorized` once the key is revoked or no longer grants `logs:read`. If the key cannot be verified for two minutes, the tail ends with code `tail_unverified`; open it again with the ID of its last event. The Loki WebSocket tail (`/v2/logs/loki/api/v1/tail`) still returns 501.
- **CI/CD: checks a release waits on get machines first.** When an account's checks are short of machines, a pull request from the repository's own branches into the production branch gets them first, then a push to the production branch, each oldest first, then every other check. While one of these waits, the account's lower checks hand it machines as their running tasks end. A pull request from a fork is ordered with every other check. To skip pull requests into a branch whose commits are tested another way, such as a staging branch, list the branches to check in the production branch's config: `pull_requests: { branches: [main] }`.

## 30 October 2026

- **Sandboxes: `networkRules` in API v2.** `POST /v2/sandboxes` accepts `spec.networkRules` (`internet`, `allow`, `deny`, `connect`), the same rules as the v1 `network` field, enforced on every connection the sandbox opens. A rule that cannot be parsed returns 400 `invalid_network_rule` in v1 and reports the sandbox as `failed` in v2. Changing `networkRules` after a sandbox starts stops it with its disk kept; create a new sandbox to use different rules. Network rules on a copy of a snapshot are not supported yet: v1 returns 501 `feature_unavailable`, and v2 reports the sandbox as `failed`. A fork keeps its source's rules.
- **CI/CD checks that run their setup start jobs immediately.** When a check runs its `setup` (its key has no warm snapshot yet), its first job now starts on that set-up machine as soon as the setup ends. Before, the machine was deleted once it was copied, and every job waited for machines started from the copy, which only one server held: when that server was full, a check could wait minutes with no job running. Machines for the rest of its work still start from the copy.
- **Usage export shows the carry on each outbound traffic row.** In `GET /v1/usage/export`, each sandbox `egress` row's `outbound` measurements now include `carried`: the fraction of a microdollar the row started from, carried in from earlier outbound traffic in the same month, in bytes times microdollars per decimal GB. The row's charge plus `written_off_micros` equals `floor((carried + billable bytes × rate) / 1,000,000,000)`. Charges are unchanged.
- **Agent sessions keep their task in the console after their history is archived.** A session's history moves to cold storage a week after the session ends. The console now still shows what the session was asked to do: the opening words of its first input. Before, the console showed no task for these sessions. Sessions archived before this change still show no task in the console; their full history is still available through the API.
- **The MCP server accepts newer protocol versions.** A client that requests an MCP protocol version newer than the server supports, such as `2026-07-28`, now gets a working session at the server's newest version (`2025-11-25`). This applies to `initialize` and to the `MCP-Protocol-Version` header on later requests. Before, those later requests returned `400 Bad Request: Unsupported protocol version`, so clients such as Claude's connectors could not connect. A malformed version, or one older than the server supports, still returns 400.
- **A sandbox has all its memory when its create returns.** `POST /v1/sandboxes` now returns only after the sandbox's guest holds all the memory it asked for (`memoryMiB`), so `/proc/meminfo` reports the full amount from the first command. Previously a sandbox could start with part of its memory and receive the rest during its first seconds. A sandbox created with a memory size other than the default can take longer to create, while the memory past its starting size is added.
- **A job is no longer failed when its machine is paused by its host.** When a check's machine stops responding because its host paused it, the tasks it held now run on the check's other machines and do not count toward the three losses that end a job with "Lost 3 times, never reported".
- **A check that times out while jobs wait for a machine reports "Could not run".** When a check's `timeout:` expires while every job that has not finished is still waiting for a machine that was refused for lack of capacity, those jobs now end with the reason `no machine came for its jobs in N minutes (...); re-run it once there is room`, and the check's GitHub run is titled "Could not run". Before, those jobs were reported as "Ran past its time limit", as if the code under test had hung.
- **A sandbox's lease counts from when it first runs.** A paid sandbox that waits in `starting` for its server to have room now has its lease renewed while it waits, so it is no longer stopped with `time_limit` before it ever runs, and its server no longer refuses the start as `invalid_lease` once the wait used up its lease. No compute is charged for the time spent waiting. `diskKept` on a stopped sandbox is now `true` only when `POST /v1/sandboxes/{id}:restart` starts it from its disk: a stopped sandbox whose server was lost now returns `diskKept: false`.
- **Evictable sandboxes.** A create or update can now set `evictable: true`. Runtime may then delete the sandbox once it has been paused or stopped for at least 15 minutes and its server needs the disk, the sandbox idle longest first. It is deleted as by `DELETE`; a running sandbox is never deleted for it. Use it for work you can recreate, such as build caches and CI machines. Sandboxes return the setting in `evictable`, and every SDK accepts it on create.

## 29 October 2026

- **A sandbox waiting on its disk is no longer paused as idle.** Idle pause now counts time a sandbox spends blocked on disk I/O as activity, alongside CPU, network traffic and open calls. Before, a sandbox whose processes were blocked on slow disk writes could use no CPU and be paused in the middle of its work.
- **Sandboxes: `wakeOnTimers` turns off timer wakes.** A sandbox that pauses because it is idle wakes by itself when a process in it is due on a timer, such as a `sleep 600` loop or an agent that polls every ten minutes. This is on by default for every sandbox, and a timer wake is billed as ordinary use from the moment the sandbox runs. To keep request wakes and turn off timer wakes, set `wakeOnTimers: false` at create or with `POST /v1/sandboxes/{id}:update`; turning it off also cancels a timer wake already planned. The setting is in the TypeScript, Python, Go, Java and Ruby SDKs, the CLI (`--no-wake-on-timers`, `--wake-on-timers on|off`) and the MCP tools, and sandbox responses include it. See [timers wake an idle sandbox](./sandbox-environment#timers-wake-an-idle-sandbox).
- **Free machine time in `GET /v1/usage` matches what a create is admitted on.** `trial.availableMs` now counts what running sandboxes hold and the free-usage rules, so a create without credit is refused with `included_usage_used_up` exactly when it is 0. The new `freeUsageHold` field says why an account has no free machine time (`hosting`, `region`, `card`, `withheld`, `no-source` or `unknown`) and what starts it; the refusal's `details.reason` names the same rule, and `npx withruntime usage` shows the message. Before, an account could read free time left while every create was refused.
- **A wake that its server has no room for no longer stays in `resuming`.** If the sandbox's server refuses a wake for memory or disk room, the sandbox returns to `paused` within 30 seconds with its memory intact, and the wake operation reports `host_capacity` or `host_memory_pressure` with the reason. The sandbox can be woken again immediately, including by an automatic wake from a command. Previously the sandbox could stay in `resuming` until its lease ended, and every command returned 409 `sandbox_not_ready`.
- **Accounts with credit keep their remaining trial hours.** An account that has paid or holds credit uses its remaining free trial hours before credit again, wherever it was opened and whether or not a card is saved. Since earlier today, such an account opened outside the 41 advanced economies, or opened by email with no card saved for auto top-up, was charged credit while it still had trial hours.
- **Sandboxes report pressure stall information.** `/proc/pressure/cpu`, `/proc/pressure/memory` and `/proc/pressure/io` are now available in sandboxes started after this release, so tools that read Linux pressure stall information (PSI), such as `systemd-oomd` or a build's own throttling, work inside a sandbox. Sandboxes resumed from a snapshot taken before the release keep their previous kernel settings until they are restarted.
- **Sandboxes: a timer wakes a sandbox that paused while idle.** When a sandbox pauses because it is idle, Runtime records when the next timer of a process in it is due (a `sleep`, a wait with a timeout, a `timerfd`, `alarm` or a POSIX timer) and wakes the sandbox about one second before then. Only timers due within 29 minutes of the pause, and pending for the whole idle time, count, so a process that wakes every few seconds does not keep waking it. A sandbox with no pending timer stays paused. A pause you request, a pause at the end of a time limit or of credit, and a sandbox with `autoWake: false` are not woken by timers. See [timers wake an idle sandbox](./sandbox-environment#timers-wake-an-idle-sandbox).
- **CI/CD: test only the packages and crates a pull request touches.** Add `pull_requests: { tests: touched }` to the production branch's `runtime.yml`. A pull request into the production branch then runs only the tests of the packages (nearest `package.json`) and crates (nearest `Cargo.toml`) that hold its changed files, plus steps whose `inputs` it changes and steps that read every file. The other tests its change reaches are listed on the `left to main` job, and the production branch's check runs them after the merge. Turn on undo with it so that a commit that breaks the production branch is reverted automatically. A change to a root file other than Markdown, a file in a dot folder, a lockfile or toolchain file, a script a step runs, or the config file runs every test it reaches. The default, `tests: reached`, is unchanged.
- **CI/CD: check only pull requests into the branches you list.** Add `pull_requests: { branches: [main] }` to the production branch's `runtime.yml`. A pull request into any other branch ends immediately, uses no machine, and its `runtime` run reads "Not checked" (action required, which never passes a required check). A pull request whose base branch changes is checked again. Without the list, every pull request is checked, as before.
- **Free usage for accounts opened by email starts with a card.** An account opened by email, in the regions with free usage, starts its free usage once its owner adds a card under **Auto top-up** on **Usage & billing**. The card is checked by your bank and is not charged unless you turn on auto top-up. Each card starts free usage for one account. Accounts opened with Google and accounts that have bought credit are unchanged. See [free usage by region](./included-usage#free-usage-by-region).
- **Stricter checks on new email sign-ups.** A sign-up code is not sent to an address at a domain registered less than 90 days ago, or to a fourth new address at the same domain within a day, unless the domain is a major email provider. Addresses that already have an account are not affected. Sign up with Google, or ask a teammate to invite you.
- **One account per inbox when signing up by email.** A new address that is another form of an inbox that already has an account, such as a `+tag` or dotted Gmail address, is not sent a sign-up code. Sign in with the address the account was opened with, or with Google.
- **Free machine time outside the listed regions starts with credit.** An account opened from a region outside the 41 countries in [free usage by region](./included-usage#free-usage-by-region) has no free machine time until it buys credit; buying credit provides the full monthly free usage in every region. Accounts opened from the 41 countries are unchanged.
- **Free usage depends on the region an account was opened from.** An account that has never bought credit and was opened from one of 41 countries, including the United States, Canada, the United Kingdom, most of Western Europe, Japan and Australia, receives the full free machine time. An account opened from any other region receives 15 minutes of a default sandbox (2 vCPU, 4 GiB): 1 GiB-hour of machine memory and 0.5 vCPU-hours of active CPU. Buying credit provides the full monthly free usage in every region. Free saved copies and disks are the same in every region. See [free usage by region](./included-usage#free-usage-by-region).
- **Lower network limits for sandboxes without credit.** A sandbox of an
  account without credit now uploads at up to 10 Mbit/s (was 50 Mbit/s) and
  transfers up to 1 GiB a day, inbound and outbound combined (was 5 GiB).
  Connections to cryptocurrency mining pools are blocked on every port.
  Downloads have no speed limit, and paid sandboxes are not affected. See
  [included usage](./included-usage#without-credit).
- **A wake of a sandbox moving to another server returns 409 `sandbox_moving`; terminals reattach without errors.** A wake, or a call that wakes a paused sandbox, while the sandbox's paused memory and disk are still being copied to another server now returns `409 sandbox_moving` with `Retry-After`, instead of `503 no_capacity`. The sandbox is unchanged and stays paused. The JavaScript, Python, Go, Java and Ruby SDKs wait and retry it as they do `no_capacity`. A terminal opened with `processId` on a shell that another terminal already typed into no longer closes with `502 guest_failed` ("invalid input offset") on its first keystroke. Its input now starts where the shell's input is.
- **Accounts that have never paid are suspended for mining, port scans or internet sweeps.**
  A sandbox of an account that has never paid that connects to a mining pool,
  scans ports, or connects to a large number of distinct destinations within a
  few minutes now has its network cut, and the account is suspended. Accounts
  that have paid are not affected. See
  [included usage](./included-usage#without-credit).
- **Forks start on another server when the source's server is full.** `POST /v1/sandboxes/{id}:fork` now returns `503 no_capacity` only when no server in the region has room for the copies. When the source's server is full, each copy starts on another server in the region, and the snapshot is copied there first, including large snapshots. The fork's memory limit (a quarter of a server's free memory per fork) now applies to each server the copies can start on, not to the source's server alone.
- **A sandbox that stops responding is reported within 5 seconds, and a restart no longer reports a kept disk as deleted.**
  A running sandbox that stops responding now returns `unreachable`, with
  `since` and `reason` (`agent_not_answering`, `disk_stalled` or
  `host_quarantined`), from `GET /v1/sandboxes/{id}`, and the new events
  `sandbox.unreachable` and `sandbox.reachable` are sent to webhooks.
  Previously such a sandbox returned `running` with no indication.
  When the sandbox's server cannot finish writing to its disk, a new command
  now returns `sandbox_unreachable` (503, retryable) after 5 seconds, with
  `details.reason` set to `disk_stalled`. Previously the request waited about
  30 seconds and returned `guest_busy` (429). The request runs nothing, and
  commands already running continue. `POST /v1/sandboxes/{id}:restart` on a running
  sandbox whose server has not confirmed the reboot's stop now returns
  `sandbox_unreachable` (503, retryable) and keeps the disk. Previously it
  returned `not_resumable` (409) with `diskKept: false`. A retry with the same
  `Idempotency-Key` waits for the stop, then starts the sandbox from its disk.
  A command sent to a stopping sandbox now returns `sandbox_stopped` with
  "is stopping" instead of "is stopped (ended earlier)". When the server
  could not pause a sandbox to free disk space, the sandbox keeps running
  instead of refusing every call. See
  [troubleshooting](./troubleshooting#a-running-sandbox-refuses-commands).

## 28 October 2026

- **Usage export lists every running-disk charge, including amounts written off.** In `GET /v1/usage/export`, each sandbox `disk_used` row now covers all disk usage since the previous row, and its measurements include `carried`, the fraction of a microdollar carried in from the previous row. A running-disk charge that your balance, cost cap or spending limits could not cover now appears as a row with `chargedMicros` of `0` and its `written_off_micros`. Charges are unchanged.
- **Woken sandboxes now end at their time limit.** A sandbox woken with `timeoutSeconds` now pauses or stops (as `onTimeout` specifies) exactly when that time limit ends. Previously, a sandbox woken this way and left to reach its limit could be woken again by Runtime and run, billed, up to one more `timeoutSeconds` past the limit.
- **Go, Java and Ruby SDKs: terminals and tunnels stay open when the API restarts.** When the API closes a terminal or tunnel WebSocket with code 1012 (Service Restart), the Go, Java and Ruby SDKs now reconnect with the resume token immediately and continue from the exact byte where they stopped, with nothing lost or sent twice; input written during the hand-off is held and sent after the reconnect. Previously, these SDKs ended the terminal or tunnel. See [Resuming terminals and tunnels after a restart](/docs/api#resuming-terminals-and-tunnels-after-a-restart).
- **Terminals, SSH sessions and port forwards stay open when the API restarts.** Previously, an API release closed every open terminal and tunnel. The API now moves each one to the instance that serves next: the server sends `{"type":"restart"}`, then a resume token, and closes the WebSocket with code 1012 (Service Restart). The JavaScript and Python SDKs, the CLI and the console reconnect with the token immediately and continue from the exact byte where they stopped, with nothing lost or sent twice. Clients that speak the WebSocket protocol directly can follow the same steps; see [Resuming terminals and tunnels after a restart](/docs/api#resuming-terminals-and-tunnels-after-a-restart).
- **A request whose egress secret cannot be added returns 503 instead of sending the placeholder.** When a sandbox's server has not heard from Runtime's API within the last minute (for example, in the first seconds after a server update), it holds secret values back. Previously, an HTTPS connection opened during that time went to the destination without the secret, and every request on that connection carried the placeholder for as long as the connection stayed open, even after the server heard from the API again. Connections to a secret's host are now always handled by the step that adds the secret. A request that carries the placeholder while its value is held back returns `503 Service Unavailable` with `X-Runtime-Egress: secret-not-current` and `Retry-After: 1`, and the connection closes; the value is added again from the first request after the server hears from the API. Server updates also no longer hold secret values back.
- **Commands keep running while a server prepares to pause a sandbox.** When a server paused a busy sandbox on its own (for example, when its disk ran short), it refused every command from the moment it decided to pause, which could be minutes before the sandbox stopped running, and `GET /v1/sandboxes/{id}` still returned `running` meanwhile. Commands are now accepted until the sandbox is paused, the pause is reported immediately, and the next command wakes the sandbox. If the server stops running a sandbox without reporting why, `exec` and file calls now return `503 sandbox_unreachable` (retryable, nothing ran) with a hint to restart it with `POST /v1/sandboxes/{id}:restart`, instead of `409 not_running` for a sandbox whose state is `running`.
- **The audit log records your account's backup encryption key.** Each
  account's backups, snapshot copies and paused sandboxes stored off the
  server are encrypted with a key of its own. The audit log now records when
  Runtime creates that key, rotates it (the old key becomes read-only: it
  still opens existing backups and encrypts no new ones) and destroys an old
  key. A key is destroyed only after no backup, copy or replica still uses it.
  Entries are `account.storage_key_created`, `account.storage_key_rotated`
  and `account.storage_key_destroyed`.
- **A command's output stream continues when its server pauses the sandbox.** When a server paused a sandbox on its own (to make room for another sandbox, or at the end of the sandbox's time limit) while a streamed `exec` or a process output read was in progress, the call returned `409 sandbox_paused` and the command's output was lost to the caller. The API now wakes the sandbox and resumes the call, and the command runs to its exit. This also applies to an `exec` sent with an `Idempotency-Key` (every SDK sends one), which is never run twice. A sandbox with `autoWake: false` still returns `409 sandbox_paused`.
- **Usage for volumes, backups and snapshots.** `GET /v2/volumes/{id}:usage`,
  `GET /v2/backups/{id}:usage` and `GET /v2/snapshots/{id}:usage` return a
  resource's storage usage and charge for one calendar month (UTC), as
  `GET /v2/sandboxes/{id}:usage` does for a sandbox. The SDKs add the
  matching `usage` method to each.
- **Volumes, backups and snapshots report their measured size.** In the v2
  API, `status.usedBytes` on a volume, backup or snapshot is now measured
  every hour, and the new `status.measuredAt` field returns when it was
  measured. For a volume, `usedBytes` is the bytes written to it; for a
  backup or a snapshot, it is the bytes only that backup or snapshot stores,
  which is what its storage is billed on. Prices and billed quantities are
  unchanged.
- **Sandboxes paused for more than an hour resume in under a second.** A
  paused sandbox's memory and disk now stay on its server until that server
  needs the room. Before, they were moved to off-site storage one hour after
  the pause, and a resume after that took 20 to 50 seconds while they were
  copied back. A sandbox whose server does need the room still resumes from
  its off-site copy, with its files and running programs intact.
- **Stopping a sandbox keeps writes made just before the stop, even when its agent is busy.**
  When a sandbox whose disk is kept (or that has a volume attached read-write)
  is stopped, Runtime asks the guest to write its pending data to disk before
  the machine ends. If the guest's agent was briefly unable to take that
  request, for example while the sandbox was out of memory, the request was
  not retried, and data written in the last few seconds before the stop could
  be missing from the disk. The request is now retried until the guest takes
  it, for up to 12 seconds. The stop itself still returns immediately.
- **Sites that block by address are paced per outbound address.** Each
  outbound address shared by more than one account now opens at most 150 new
  connections an hour to Google, Bing, Amazon and the other
  [sites that block by address](./egress#sites-that-block-by-address), for all
  accounts together, and at most 100 an hour for any one account. This
  includes the addresses kept for scrapers, which had no limit, so one
  account's traffic could get such an address blocked for every account sent
  from it. Past a limit, a connection returns `429 Too Many Requests` with
  `X-Runtime-Egress: rate-limited:guarded-site` and `Retry-After`. Before, one
  account could open 300 an hour from a shared address. A dedicated outbound
  address is not limited.
- **A create whose sandbox is deleted while it starts returns 410 `deleted`.**
  If a sandbox is deleted before its own `POST /v1/sandboxes` returns, that
  create now returns 410 `deleted` with `details.sandboxId`. It previously
  returned 404 `not_found`. A create with `getOrCreate: true` whose name's
  holder is deleted while the create waits for it now creates a new sandbox
  instead of returning 404. See [names](./api#sandboxes).

## 27 October 2026

- **A job's runs in the v2 API and every SDK.** `GET /v2/jobs/{id}/runs`
  returns a job's runs, newest first and paginated, and `GET /v2/job-runs/{id}`
  returns one run: its execution, task, attempt, state, exit code and times.
  The SDKs read them with `jobs.runs(id)` and `jobs.run(id)` (`Runs` and `Run`
  in Go).

- **Connections between your sandboxes are no longer reset in bursts.**
  Connections by name (`<name>.sandbox.internal`) were refused past 100 new
  connections a second across the whole account, so a sandbox opening several
  at once saw some of them reset (about 17% with 8 at once). The limit is now
  1,000 a second per account and 500 a second per target sandbox, and a
  connection over it waits for its turn instead of being refused. A sandbox
  created moments ago is also reachable within about a second; before, it
  could be refused with `private-network-off` or `private-network-no-sandbox`
  for up to 15 seconds. See [networking](./networking).
- **OpenTelemetry exports in the v2 API.** The v2 API adds an `otel-exports`
  resource, with matching methods in the TypeScript, Python, Go, Java and Ruby
  SDKs. An export sets `endpoint` (an OTLP/HTTP base URL), `signals` (`logs`,
  `metrics`, `traces`) and `enabled`. `headers` are write-only: they are sent
  with every push and never returned; `status.headerNames` lists their names.
  An update that sends `headers` replaces all of them. A project can have at
  most three exports. The v1 OpenTelemetry export API returns the same
  responses as before.
- **Image builds check variable names in the request schema.** A build
  request to `POST /v1/images` returns 400 `invalid_request` when a key of
  `env`, `recipe.env` or `buildArgs` is not a valid variable name (a letter
  or underscore, then letters, digits or underscores, up to 256
  characters). `details.issues` names each such key. Builds already refused
  these names; the request is now refused before it is read further, and
  the published OpenAPI document declares the rule as `propertyNames`.
- **Webhooks in the v2 API.** The v2 API adds a `webhooks` resource, with
  matching methods in the TypeScript, Python, Go, Java and Ruby SDKs. A
  webhook sets `url`, `events`, `enabled` and `description`. Increasing
  `spec.secretGeneration` by one rotates the signing secret; the previous
  secret keeps signing for `spec.keepPreviousSeconds`. The secret is returned
  only in the response to the create request and to each rotation. The v1
  Webhooks and Events APIs return the same responses as before.
- **Run virtual machines inside a sandbox with `/dev/kvm`.** New sandboxes on
  current-generation hosts boot a guest kernel with KVM and expose `/dev/kvm`
  to every user in the sandbox, so QEMU, Firecracker or an Android emulator
  runs with hardware acceleration instead of emulation. A VM inside a
  sandbox keeps running through pause and resume, and is carried into
  snapshots and forks. To check whether a sandbox has it, run
  `test -c /dev/kvm && echo yes`. Sandboxes created before this change keep
  their kernel until they are recreated.
- **Waking a sandbox keeps the egress CA its running processes trust.**
  A sandbox started before 26 October 2026 and woken afterwards was given a
  new egress CA, and processes that were already running (Node.js with
  `NODE_EXTRA_CA_CERTS`, Bun, Python, Go) failed HTTPS requests that use
  egress secrets with `SELF_SIGNED_CERT_IN_CHAIN` until they were restarted.
  A wake now keeps the CA the sandbox already trusts and writes nothing to its
  trust store. See [security](./security).
- **Accepting an invitation adds you only to the account that invited you.**
  A person whose first sign-in was through an invitation link was also given
  a separate account in their own name. Opening an invitation now creates
  nothing; you join the inviting account when you select Join. See
  [teams](./teams).
- **Sandbox usage.** `GET /v2/sandboxes/{id}:usage?month=YYYY-MM` returns
  what a sandbox used in a calendar month (UTC): its metered periods,
  milliseconds running, vCPU-microseconds billed, MiB-milliseconds of memory,
  and the amount charged, in microdollars. Without `month`, it returns the
  current month. It requires the same permission as reading the sandbox, and
  is available as `sandboxes.usage(id, month)` in the TypeScript, Python, Go,
  Java and Ruby SDKs, as `runtime sandboxes usage <id> [--month YYYY-MM]` in
  the CLI, and as an MCP tool.
- **Volumes on v2 Apps, Functions and Containers.** `spec.volumes` lists up to 16 volumes, each with `volume`, `path` and `mode`. A volume is mounted at any absolute `path` outside the system folders (such as `/var/lib/postgresql/data`) before a copy's process starts. With `mode: write` (the default), one copy mounts the volume read-write, so the service runs one copy and `status.copyLimit` is 1, with `status.copyLimitReason` naming the volume. A new version, a rollback or a restart stops the old copy (`SIGTERM`, then `stopGraceSeconds`, default 30) and unmounts the volume before the new copy mounts it. With `mode: readMany`, each copy mounts its own read-only copy-on-write copy of the volume as it was when the version was made, and the service scales as usual. A volume another sandbox mounts read-write fails the version with `volume_attached`; deleting a service never deletes a volume.
- **A sandbox at its memory limit stays reachable, and every process killed for memory is recorded.**
  Linux's out-of-memory killer now never ends Runtime's agent or the
  sandbox's network relay, so commands keep running after a kill. Each
  process it ends, inside a command or not, is recorded as the event
  `sandbox.oom_kill` with its name, process ID and memory. The event is shown
  on the sandbox's page in the console and sent to webhooks. When the agent
  does not answer, the API returns `sandbox_unreachable` (503, retryable),
  and names a recent out-of-memory kill when there was one. When the sandbox
  cannot read its environment, the API returns
  `sandbox_environment_unavailable` (503, retryable). Both replace
  `guest_busy`, which now means only that the sandbox is running as many
  commands as it can. `POST /v1/sandboxes/{id}:restart` on a running
  sandbox now reboots it from its disk instead of returning 409
  `not_resumable`. See [troubleshooting](./troubleshooting#a-running-sandbox-refuses-commands).
- **Relative file paths work in the compatibility layers, and Vercel's `stop()` sends one request.**
  Paths such as `./hello.txt` or `src/../a.txt` passed to the CodeSandbox,
  Cloudflare, E2B, Daytona and other compatibility layers now resolve against
  the layer's working folder (`/project/sandbox` for CodeSandbox), as the
  vendors' SDKs resolve them. Before, the API returned `400` with
  `invalid_request` for a path containing `.` or `..`. In `withruntime/vercel`,
  `sandbox.stop()` no longer reads the sandbox first: it pauses or stops it
  in one request, saving one round trip per stop.
- **Volumes and backups in the v2 API; snapshots no longer pause the sandbox.**
  The v2 API adds `volumes` and `backups` resources, with matching methods in
  the TypeScript, Python, Go, Java and Ruby SDKs, the CLI and the MCP server.
  A volume sets `dailyBackups` and `backupRetentionDays`; a backup names its
  `volume` and reports `sizeMib` and `expiresAt`. A v2 snapshot now takes
  `mode` (`memory` or `disk`) and `retentionDays`, and reports `expiresAt`,
  `vcpus`, `memoryMib` and `diskMib`. Taking a snapshot of a running sandbox
  no longer pauses it: the sandbox keeps running while the snapshot is made.
  The v1 Volumes and Snapshots APIs return the same responses as before.
- **Connections between your sandboxes are no longer held to upload limits.**
  Connections by name (`<name>.sandbox.internal`) were limited to 100 Mbit/s
  per sandbox, and to 20 Mbit/s after the first 2 GiB, as uploads to the
  internet are. They are now limited only by each server's share of the
  private network. They do not count toward a sandbox's upload limits or its
  daily network amount. Each sandbox can still be reached for 100 GiB a day.
  See [networking](./networking).
- **CI/CD jobs stay `queued` until a machine begins them.** A job is now
  `running` only once one of its machine's tasks starts, and `sandboxIds`
  lists each sandbox as soon as it begins the job, not only when the job
  ends. While a job is queued, its `reason` says what it waits for (for
  example, "Waiting for a machine: the check's machines are starting, or
  running other jobs' tasks"), the console shows how long it has waited, and the
  check's `runtime` run on GitHub says how many jobs are waiting and for how
  long. Previously a job could report `running` for many minutes while its
  tasks waited behind other jobs' tasks.
- **Sandboxes in a compartment reach each other by name.** With the private
  network on, sandboxes created by keys in the same compartment can now
  connect to each other at `<name>.sandbox.internal` or
  `<id>.sandbox.internal`. Before, every connection from a compartment's
  sandbox was refused with `private-network-off`. Compartments stay walled:
  a sandbox reaches only sandboxes of its own compartment, or, outside every
  compartment, only the account's other sandboxes outside every compartment.
  A name across the wall returns `502` with `private-network-no-sandbox`.
- **Requests through a sandbox's web proxy no longer wait 40 ms on responses.**
  The sandbox's web proxy relay (`127.0.0.1:10800`) and
  `guest-egress.py forward` now set `TCP_NODELAY` on the program's connection.
  Previously the kernel held the last segment of any response longer than one
  segment until the program acknowledged the one before, and most clients
  delay that acknowledgement by 40 ms. A call to Runtime's API from a sandbox
  that returns more than about 1.4 KB (creating, pausing or waking a sandbox,
  reading a file, listing sandboxes) completes about 40 ms sooner, as does any
  other request made through the proxy. A sandbox uses the new relay from its
  next boot, or from the wake after its next pause. The transparent relay, used by programs that ignore
  `HTTPS_PROXY`, gets the same change with the next base image.
- **Speed figures are published only from live measurements.** The speed
  page, the guides, the website, llms.txt and the MCP server's instructions no
  longer quote the sandbox timings measured in September 2026. The
  [speed](./speed) page now lists only operations measured by the outside
  probe each minute whose own time is within 2× of their physical floor, with
  p50, p95, p99, sample counts and the raw samples. The disk, network and trace
  overhead measurements moved to [observability](./observability#what-metrics-and-traces-cost).
- **Change a key's reach or daily limit over the API.** `PATCH /v1/keys/{id}`
  (`runtime.keys.update` in the TypeScript SDK, `runtime keys update` in the
  CLI) changes a key's `reach` (`agent` or `account`) or `dailyLimitMicros`
  (`null` removes the limit). A key can widen only the keys it made, never past
  its own reach or daily limit, and returns `403 forbidden` otherwise. It can
  narrow any key it sees, and it never changes itself. Each change is recorded
  in the audit log. Previously only the website could change an existing key.
- **CI/CD reports a job lost with its machines as "Could not run".** When a
  job's task is lost on three machines without reporting a result, the job
  now ends as **Could not run** with the reason (for example, "Lost 3 times,
  never reported; the last on <machine>: no answer for 265 s"). Previously
  it was reported as "Failed in 0.0 s: exit code 1" and annotated on a file
  it never tested. A test failure in the same job still fails it. Lost runs
  are no longer recorded as test failures in flaky-test history.
- **Sandboxes reach each other by name on every server.** A sandbox can now
  connect to another sandbox in its organization at
  `<name>.sandbox.internal` whichever server runs either one; before, only
  sandboxes on one server could. Private networks (WireGuard) are reachable
  from sandboxes on every server too. Connections by name have a daily
  allowance of 100 GiB for each target sandbox, separate from the private
  network's 50 GiB. When the private network is briefly unavailable from a
  server, connections to it return `503` with
  `private-network-unavailable` and are never sent anywhere else; retry
  after a minute.
- **The speed page is measured every minute, from outside, with the raw
  samples.** Runtime now times its operations once a minute (volumes every five minutes)
  through the public API, from a fixed location outside Runtime (a Cloudflare
  Durable Object in eastern North America), and reports Runtime's own time
  and the network's part separately, with p50, p95, p99 and sample counts for
  the last 24 hours. An operation is listed once its own time is within 2× of
  its physical floor, the least time its work can take on today's hardware.
  The summary is at `https://status.withruntime.com/speed.json` and each day's
  samples at `https://status.withruntime.com/speed/samples.jsonl?day=YYYY-MM-DD`
  ([speed](./speed)).
- **Every API response includes a `Server-Timing` header.** The header,
  `Server-Timing: app;dur=12.3`, gives the time in milliseconds from when the
  API received the request until its response headers were ready. Subtract it
  from the time your client measured to get the network's share of each call
  ([the API](./api#responses-and-errors)).

## 26 October 2026

- **The CLI says when a newer version exists after it rejects an option.**
  An installed `withruntime` stays at its version until you update it, and
  `npx withruntime` runs an installed copy before it downloads one, so an
  older CLI could reject an option the docs list, such as
  `secrets scope --only-label`, with no sign that it was out of date. Now,
  when the CLI rejects an option or a command, it checks npm for the latest
  version, for at most 1.5 seconds, and prints the installed and latest
  versions with `npm install -g withruntime@latest`. It skips the check in
  CI and when `RUNTIME_NO_UPDATE_CHECK=1` is set
  ([the CLI](./cli)).
- **Raising a job's timeout no longer requires changing its compute.**
  Previously, `PATCH /v1/jobs/{id}` with only a larger `timeoutSeconds`
  returned 400 with "Invalid integer" when the new timeout exceeded the
  job's `compute.durationSeconds`. Now the update extends
  `compute.durationSeconds` to the timeout plus 60 seconds of start time, up
  to 3,600, as a create does. A timeout that already fits leaves it as it
  is. Refusals of `timeoutSeconds` and `compute.durationSeconds` now name
  the field and the allowed range.
- **HTTPS through egress secrets and preview links keeps working after a
  sandbox moves to another server.** Previously each server signed with its
  own certificate authority, so a process started before a wake, a move or a
  fork onto another server (such as Node with `NODE_EXTRA_CA_CERTS`) failed
  every request to an egress secret's host with
  `SELF_SIGNED_CERT_IN_CHAIN` until it restarted. Now each organization has
  one certificate authority, the same on every server, and running processes
  keep working. Each sandbox switches to its organization's certificate
  authority at its next start or wake; a process started before that switch
  must be restarted once. See [Security](./security).
- **Sandboxes created from older images hold as many outbound connections as
  their limits allow.** Previously a sandbox created from an image or
  snapshot made before 15 October 2026 kept that image's web proxy relay,
  which held 64 connections and closed the 65th without a response, even
  when `GET /v1/sandboxes/{id}/network` reported a higher
  `limits.connections`. Now every sandbox boots with the current relay, so
  it holds its full limit and a connection past it returns
  `503 Service Unavailable` with the limit in `X-Runtime-Egress`. A sandbox
  that resumes saved memory (a wake, or a copy of a memory snapshot) takes
  the current relay immediately before its next pause, so it holds its full
  limit from the wake after that. See
  [The network](./sandbox-environment#the-network).
- **Agents that start from a repository start their sessions.** An agent
  whose definition sets `from: {"repo": "owner/name"}` starts each session
  from that repository's CI/CD warm snapshot. Previously every session of
  such an agent ended immediately with `sandbox_refused` (403 `forbidden`,
  "a create naming another snapshot"), because the session's key was
  allowed to create its sandbox only from a snapshot the definition names
  by id. A session's key may now create its sandbox from any ready warm
  snapshot of the definition's repository, and from no other snapshot.
- **A secret can now be given to the machine as its real value.** Some
  secrets are not HTTPS headers: a database password, an SSH key, a signing
  key or a service account's JSON file. Store one with `--exposed` (or
  `exposed: true` in the API, the MCP tool and the SDKs) and the machines it
  reaches get the value itself in its variable. It may be any text up to
  64 KiB, several lines included. The value is still sealed, and opened only
  on the server that runs the machine. Code in the machine can read it, so
  the placeholder kind stays the default and the one to use for HTTPS APIs.
  For the same reason, it goes only to the sandboxes and Apps you name by id
  (`--only-sandbox`, `--only-app`), never to every sandbox or by label, and
  only a key that may run commands in each of them can store it. Which
  machines get it changes only when you store it again with its value.
  Every secret now has a version too, one more for each change to it: its
  value, who gets it, its hosts or its variable. Pass it as `expectedVersion`
  (`--expected-version`) and a write happens only if no one has changed the
  secret since; otherwise the answer is 409 `version_conflict`.
  `GET /v1/egress-secrets/{name}` and `runtime secrets get` show one
  secret's kind and version, never its value. The website's Secrets page
  offers both kinds and shows each secret's kind and version. See
  [a secret the machine needs itself](./security#a-secret-the-machine-needs-itself).

- **A failed agent session shows why in the console.** When a session fails
  because its sandbox could not be created (`sandbox_refused`), the
  session's page in the console now shows the error the API returned, which
  previously appeared only in the session's events.

- **App deploys report `live` only when the address serves them.** A deploy
  reaches `live` only after every router serves the new version's route, and
  an App's `state` is `waiting` until its first version is served, so
  `waitFor=live`, `runtime apps deploy` and the SDKs return when the address
  answers from the new version.

- **CI/CD: built-in and light-sandbox steps record their result immediately.**
  An `undoes` or `hot-spots` step, a gate, or a `machine: light` step now
  shows its result in the console as soon as it finishes, instead of when the
  check's other jobs end. Previously such a step stayed "running" until then,
  and a check whose other jobs waited more than 40 minutes for capacity failed
  with "undoes sent nothing for 40 minutes" although the step had passed.

- **`GET http://runtime.internal/v1/identity/token` returns 401 for a request
  token that is not the sandbox's current one.** It previously returned 403.
  Read the current token from `http://runtime.internal/v1/environment` and
  retry. The JavaScript and Python SDKs already do this for both statuses.
- **Browsers start with Chromium already running.** A headless browser at
  the default window size (1280 by 800) is now created from a snapshot of
  Chromium that is already running, instead of starting Chromium in the new
  sandbox, which took 1 to 3 seconds. Each browser gets its own CDP secret,
  its own random state, and an empty profile. A server builds the snapshot
  the first time a browser of that size is created on it, so that first
  browser starts as before. Other settings start Chromium as before.
- **An outbound connection that cannot reach Runtime's web proxy returns
  `503 Service Unavailable` with the reason.** Previously the sandbox's relay
  closed such a connection without a response, which clients reported as
  `Connection reset by peer`. Now the response carries
  `X-Runtime-Egress: proxy unreachable (<reason>)` and `Retry-After: 1`. A
  sandbox holds about 1,000 outbound connections at the same time, fewer than
  `limits.connections` for a sandbox with more than one vCPU, until a
  later release raises it; past that, new connections return this response.
- **A sandbox with no time limit can be funded up to 12 hours ahead.** Set
  `leaseSeconds` (from its first lease, 1,800 seconds, to 43,200) on create or `:update` (`--lease` in the CLI,
  `lease_seconds=` in Python, `.leaseSeconds()` in Java, `LeaseSeconds` in Go),
  and each renewal funds it that far ahead instead of 1,800 seconds. It is
  renewed when half is left, so it keeps running for at least half of
  `leaseSeconds` if Runtime's control plane cannot renew it. Each renewal holds
  that much time's credit at the sandbox's rates; what it does not use is
  released. A sandbox on the free usage renews by 1,800 seconds until the
  account has credit. Only an owner's, an admin's or an account-wide key may set
  it, on a sandbox one of those made. If that key or member loses the right, a sandbox
  funded past its first lease is paused or stopped at once, as its lease's end
  would. A sandbox's details include its `leaseSeconds`.
- **CI/CD: a cancelled check names the key that cancelled it, and your
  production branch's check gets machines sooner.** A check cancelled with
  `POST /v1/ci/checks/{id}:cancel`, `runtime ci cancel` or the MCP tool now
  shows the reason `asked through Runtime's API with the key "<label>"` in the
  console, in the API's `reason` field and on GitHub, where `<label>` is the
  calling key's label. The audit log entry also includes the key's id. When
  your account's machine limit is reached, your production branch's check now
  takes machines from your pull requests' checks as their running tasks end.
  Previously it waited for those checks to finish when the limit, rather than
  the servers, held it back.
- **Slack triggers start agent sessions from a channel.** Add Runtime's Slack
  app to a workspace with `runtime agents slack install` (or
  `POST /v1/agents/slack/installs`; the link works only for a signed-in
  member of the account), invite it to a channel, and add a `slack`
  trigger with the workspace's `team` and the channel's id. Each new message
  in the channel starts a session; a reply in its thread joins that session.
  The session's replies and result are posted in the thread, its status is one
  message edited in place, and each ask is posted with a button for each
  option. `GET /v1/agents/slack/teams` lists the added workspaces and
  `DELETE /v1/agents/slack/teams/{team}` removes one. Available in the
  JavaScript, Python, Go, Java and Ruby SDKs (`agents.slack`).

- **SSH to Runtime's own servers counts toward its own limit in the probing
  check.** SSH connections from a sandbox to the public addresses of
  Runtime's servers are still refused. They now count toward a separate
  limit of 10 different servers in ten minutes, instead of the limit of 5
  internal addresses. Previously, a test suite that tried SSH on five of
  them within ten minutes could have its sandbox held. Connections to
  Runtime's servers on other ports still count toward the internal-address
  limit.
- **A paid account's sandbox is reviewed by a person before it is halted.**
  When the abuse checks flag a sandbox of an account that has paid, it is
  held as described above and keeps running, with its processes and files
  untouched. A person then lifts the hold, which turns the network back on,
  or confirms it, which pauses the sandbox. Previously, the sandbox was
  paused immediately.
- **A sandbox held by the abuse checks keeps its files readable.** You can
  read and download a held sandbox's files with
  `GET /v1/sandboxes/{id}/files/content` or
  `GET /v1/sandboxes/{id}/files/archive`. A read wakes the sandbox if it is
  paused, and it can also be woken or started. Previously, every wake and
  start of a held sandbox returned `sandbox_halted` (403), so its files could
  not be read. While the hold is in place, the sandbox's network is off for
  outbound and inbound traffic (previews, custom domains, TCP ports and
  private networks), and commands, terminals, file writes, snapshots and
  forks return `sandbox_halted` (403). See
  [Network access](./security#network-access).

- **A lease that ends without you never deletes a sandbox's disk.** Only a
  request from you deletes data. Previously a sandbox created with
  `onTimeout: "delete"` had its disk deleted when its lease ended before its
  time limit (a renewal that did not arrive, or a pause that failed at the
  lease's end), and a sandbox created with `pausable: false`, one on a server
  that stopped responding, or one stopped while moving between servers had
  its disk deleted when its lease ended or it crashed. Each is now kept: a
  pausable sandbox as a stopped sandbox you can restart, billed as
  [paused storage](./pricing#paused-storage); the others at no charge, until
  you delete them. `onTimeout: "delete"` still deletes the disk when the time
  limit you set ends.

- **CI/CD: built-in history checks finish immediately on production pushes.**
  On a push to the production branch, an `undoes` or `hot-spots` step now
  passes as soon as the plan is made, because the pull request was already
  checked. It no longer waits for a sandbox. On a pull request, these steps
  still run on the check's light sandbox. While that sandbox, or the one that
  runs gates, waits for capacity, the console shows "Waiting for room" on
  each of its jobs, with the elapsed minutes updated every 5 minutes.
  Previously these jobs showed no update while they waited, and a check whose
  jobs waited more than 40 minutes failed with "sent nothing for 40 minutes".

- **Commands in sandboxes and App copies can open 65,536 files.** The
  open-file limit is 65,536, previously 4,096, and a process can raise it
  to 1,048,576 without root (`ulimit -n 1048576`), so one server holds tens
  of thousands of connections. See
  [Limits of one sandbox or one feature](./limits#limits-of-one-sandbox-or-one-feature).

- **Move scheduled jobs from Trigger.dev, Inngest, Modal, Google Cloud Run
  and AWS Batch.** Change one import, or run one command, and the jobs run
  on Runtime unchanged, with their schedules, sizes, timeouts and retries.
  `withruntime/trigger` runs Trigger.dev `schedules.task` and `task`
  definitions, and `withruntime/inngest` runs Inngest functions with cron or
  event triggers; `runtime jobs deploy` builds the project and creates one
  job per task. `python -m withruntime.modal deploy app.py` creates a job for
  each Modal Function with a `schedule` (`modal.Cron` or `modal.Period`).
  `runtime jobs import` reads a Cloud Run job's YAML with its Cloud Scheduler
  job, or an AWS Batch job definition (API JSON, `describe-job-definitions`
  output or a CloudFormation template) with its EventBridge schedule or rule,
  and creates the jobs. Settings with no equivalent, such as a GPU, parallel
  tasks or a mounted bucket, are listed with the reason. The plan is also
  available as `POST /v1/job-imports`, `jobs.importPlan` in every SDK and the
  `runtime_jobs_import` MCP tool. Requires SDK 0.36.0 (Python 0.34.0). See
  [Move jobs from another platform](./jobs#move-jobs-from-another-platform).

- **OpenTelemetry exports can send traces.** Add `"traces"` to an export's
  `signals` and every API call your account makes, including creates,
  commands, file calls, pauses, wakes and snapshots, is sent to
  `<endpoint>/v1/traces` as an OTLP span within about a second, with the
  OpenTelemetry HTTP attributes and the request ID. A call that carries a W3C
  `traceparent` header becomes a child of the caller's span; the TypeScript
  and Python SDKs send that header automatically when OpenTelemetry is set up
  in your process. Exports now report `exportedSpans`, and the span pushes'
  own health in `tracesLastSuccessAt`, `tracesLastError` and `tracesFailures`,
  apart from the logs' and metrics' `lastError` and `failures`. The default signals are
  unchanged ([traces](/docs/observability#traces)).
- **Sandbox metrics include disk and network.**
  `GET /v1/sandboxes/{id}/metrics` and `sbx.metrics()` now return `diskUsedBytes`
  (bytes used on the root file system), `diskReadBytesPerSecond`,
  `diskWriteBytesPerSecond`, `diskReadOpsPerSecond`, `diskWriteOpsPerSecond`,
  `networkReceivedBytesPerSecond` and `networkSentBytesPerSecond` for each
  point and for `latest`. Disk figures are counted by the sandbox's own
  kernel; network figures by the host, for every connection the sandbox opens
  and every request it serves. A value that was not measured is `null`, never
  zero. The sandbox's Activity tab charts disk used, disk reads and writes,
  and network in and out; `runtime sandboxes metrics` prints them; the Python,
  Go and TypeScript SDKs return them; and `getMetrics()` in `withruntime/e2b`
  now returns `diskUsed`. OpenTelemetry exports send them as
  `runtime.sandbox.disk.usage`, `runtime.sandbox.disk.limit`,
  `runtime.sandbox.disk.io`, `runtime.sandbox.disk.operations` and
  `runtime.sandbox.network.io`
  ([metrics](/docs/observability#metrics)).

## 25 October 2026

- **Waking a sandbox paused moments earlier returns sooner.**
  `POST /v1/sandboxes/{id}:wake` now returns as soon as the sandbox's
  processes run again. Its clock is corrected immediately after, before any
  later command for it runs, and the server records the wake with one round
  of disk writes instead of three. Memory, processes and open files are kept
  as before.

- **API requests no longer return `controller_standby` during a controller
  release.** While Runtime switches its API to a new release, a request
  that reaches the previous release is held and then served by the new one,
  instead of returning `503 controller_standby`. Such a request can take up
  to a few seconds longer during the switch; it no longer needs a retry.
- **App and Function deploys go live, or fail immediately with a clear
  error.** Production now runs the address router and the controller loop
  that switch an App or Function to a new version and route its address to
  its copies. Previously a deploy could stay in `switching` until the next
  deploy replaced it, and the App's address returned 404. Where that
  controller is not running, `POST /v1/apps/{id}/deploys`, `/rollback` and
  `:restart` (and the same Function routes) now return 501
  `feature_unavailable` immediately and change nothing.
- **Image deploys that cannot start fail with the reason.** When the API
  refuses an image's start command (for example `cwd_not_found`, because the
  image's start directory does not exist or cannot be entered), the deploy
  now fails immediately with `deploy_health_failed` and that error in
  `lastOutput`. Previously it was retried three times and failed with
  "warming the image stopped 3 times without an answer".
- **Saving an egress secret returns in under half a second.**
  `PUT /v1/egress-secrets/{name}`, `DELETE`, the scope and rules changes, and
  the upstream proxy calls now return as soon as the change is stored. Each
  server that runs your sandboxes receives the change at the same time and
  usually applies it within a second. Previously the call waited until every
  such server confirmed the change, and took 10 to 26 seconds for an
  organization with sandboxes on many servers. `enforced` is `true` when
  every server confirmed before the response, and `false` while one is still
  applying it.

- **Status page hosted outside Runtime: status.withruntime.com.**
  [status.withruntime.com](https://status.withruntime.com) shows the current
  state of the API, the website and sandbox creation, measured from six
  regions outside Runtime's own servers, so it remains available when Runtime
  or withruntime.com is not. The sandbox check creates the smallest sandbox,
  runs a command in it and deletes it; a `no_capacity` response counts as a
  failure. Each check shows up, down since a given time, or no recent reading,
  with a 24-hour history, uptime and median latency. The same data is
  available as JSON at `https://status.withruntime.com/status.json`.
  [withruntime.com/status](https://withruntime.com/status) links to it.
- **Snapshots and forks of long-paused sandboxes.**
  `POST /v1/sandboxes/{id}:snapshot` and `POST /v1/sandboxes/{id}:fork` no
  longer return 409 `snapshot_unsupported` for a sandbox paused long enough for
  its disk to move to cold storage. The sandbox is restored from its stored copy
  first (up to 120 s) and is paused again afterward, including when the request
  fails. A paused sandbox's disk now moves to cold storage one hour after its
  last use, and only once its stored copy is verified.

- **A sandbox can run as root by default.** Create it with `user: "root"`
  (`--user root` in the CLI, `user=` in Python, `.user("root")` in Java,
  `User: "root"` in Go), or set it later with `:update`, and its commands,
  background processes and terminals run as root, through its passwordless
  `sudo`, with no `sudo` in front of each one. A call can still name
  `user: "sandbox"`. Forks and copies of its snapshots run as root too; files
  written through the files API and SSH logins stay the sandbox user's. A
  sandbox's details include its `user`. See
  [who you are](./sandbox-environment#who-you-are).
- **Pagination for secrets.** The `list` action of the `runtime_secrets` MCP
  tool now supports pagination with `limit` (1 to 100) and `after`, as its
  schema documents. Pagination is also supported by `GET /v1/egress-secrets`
  (pass the response's `next` value as `after` to get the next page),
  `secrets.list` in every SDK, and `runtime secrets ls --limit --after`. The
  `runtime_secrets` schema now states which action accepts each field, and a
  field sent to the wrong action returns an error that names the correct one.

- **Clearer comparison and calculator pages.** The pages in the compare and calculators guides use plainer English: shorter sentences and one name for each term. Two figures were corrected: the Blaxel cost in the Daytona vs Blaxel comparison now shows Blaxel's cost instead of Daytona's, and the Runloop vCPU rate on the Runloop alternatives page now shows the published CPU rate instead of a memory rate.
- **New private networks and dedicated outbound addresses are temporarily
  unavailable.** Creating a private network or reserving a dedicated
  outbound address returns `503 no_capacity` until gateway servers and
  address pools are added on sandbox servers. Existing private networks and
  addresses are unchanged. When they return, each new private network is
  assigned to one gateway server, its `endpoint` is that server's address,
  and the organization's sandboxes run on that server; networks and
  addresses are spread evenly across servers.

## 24 October 2026

- **Internet off with an allow list reaches the list.** A sandbox created or
  set with `network: {internet: false, allow: [...]}` was refused every
  connection (`X-Runtime-Egress: internet-off`), though its rules showed the
  list. Internet off with an `allow` list is now allow-list only: the sandbox
  reaches the listed destinations and nothing else, and its rules are stored
  and shown as `internet: true` with that list, on create and on
  `network.set` alike, in the API, every SDK, the CLI, MCP and the console.
  Internet off with no `allow` list still reaches nothing. See
  [the network](./sandbox-environment#the-network).
- **A command's record says how it ended.** A command whose answer was lost
  on the way back (its connection cut, or its sandbox stopped or paused under
  it) is kept as "its answer was lost" (outcome `unknown`), where it left no
  record. One still running when its sandbox is stopped or deleted shows
  `ended by the sandbox's stop` (or `delete`), not running for ever. A
  command that timed out keeps the time limit it ran under. And `bwrap`
  (bubblewrap), which Codex runs its commands under, is in the default image
  from its next build. See [commands and processes](./api#commands-and-processes).
- **Volume backups go first, and one that can't start says so.** A volume
  backup's copy off its server goes ahead of Runtime's own copies there,
  never behind one, and `copyStartedAt` says when it began. A backup whose
  copy hasn't begun 15 minutes after you asked fails with `errorCode`
  `backup_stalled` rather than staying `pending`, unless other backups on its
  server are moving up the line. The volume is unchanged; back it up again.
  See [volume backups](./storage#limits-and-price).
- **Pauses, wakes, restarts and stops are in the audit log.** Each pause,
  wake, restart and stop of a sandbox is an audit log entry
  (`resource.paused`, `resource.woken`, `resource.restarted`,
  `resource.stopped`) with who asked; one Runtime did itself says why: it
  sat idle, it reached its time limit, credit ran out or a spending limit was
  hit. A volume inside the free 10 GiB, and a job on an account without
  credit, now read `funding: trial`, not `paid`. See
  [the audit log](./teams#audit-log).
- **Support chat asks you to sign in.** The Help chat on withruntime.com is
  for signed-in accounts: signed out, it asks you to sign in and brings you
  back to the page, and `POST /api/support/chat` answers `401`. Without an
  account, write to support@withruntime.com. `runtime_support`,
  `npx withruntime support` and **Support** in the console are unchanged.
  See [get support](./feedback-and-support#get-support).
- **A sandbox's page in the console loads again.** A sandbox's page could
  fail to load: the server and the browser wrote its chart's and events'
  dates differently (`Sep 23 at 10:30` against `Sep 23, 10:30`), and the
  browser threw the page away. Both now write them the same way.

- **Volume backups on your own schedule.** A volume can be backed up every N
  minutes (15 or more) or on a cron in UTC instead of daily, and keep its
  backups by counts: the last N, and the newest in each of the newest N hours,
  days, weeks, months and years. The newest ready backup is always kept.
  Set it with `schedule` and `keep` on the backup policy, in every SDK, the
  console, MCP, `/v1/volumes/{id}:backup-policy` and the CLI:
  `runtime volumes backup-policy <id> --every 60 --keep hourly=24,daily=7`.
  `schedule: null` goes back to daily, and `daily` and `retentionDays` work
  as before. See [volume backups](./storage#volume-backups).

- **Sandboxes start from your larger images with no disk to name.** A sandbox
  created from an image of yours larger than the default 4 GiB disk, with no
  `diskMiB`, was refused `disk_too_small`. An image of up to 8 GiB now gets
  an 8 GiB disk, within the 10 GiB a running sandbox's disk
  includes, and starts from the image's started copy of that size. A larger
  image is still refused, now naming the `diskMiB` to ask for; a `diskMiB` you
  name is kept. See [images](./images).

- **Upload links take the 5 GiB they say.** An upload link (`files:link` with
  `method: "PUT"`) refused a body over 64 MB as too large; it now takes up to
  its `maxBytes`, 5 GiB at most, in one request, streamed into the sandbox,
  with nothing to split. A sandbox can open a file link too, to download or
  upload with no key. See [file links](./api#file-links).
- **The usage export says how far it is final, in every SDK and the CLI.**
  `runtime usage export` ends by saying on stderr how far the range is final:
  no more charges will settle before that time. The Python, Go, Ruby and Java
  SDKs gain the export (`usage_export`, `UsageExport`, `usageExport`), with
  `finalThrough` on each page and `final` on each row. See
  [export settled usage](./api#export-settled-usage).
- **E2B's client works in the drop-in.** `new E2B({ apiKey }).Sandbox` in
  JavaScript, and now `E2B(api_key=...).Sandbox` in Python, create and connect
  with the client's key. The client's `Template`, `Volume` and `Secret` refuse
  before anything happens, naming what to use instead: a Runtime image, Runtime
  volumes or a Runtime secret. See [migrating](./migrate).

## 21 October 2026

- **Previews are never indexed.** Every answer on a preview address, private
  or public, carries `X-Robots-Tag: noindex, nofollow`, and each preview
  address serves Runtime's own `robots.txt`, so no preview shows up in search.
  A custom domain serves your site's own headers and `robots.txt`; use one for
  a site that should be found. See
  [search engines](./networking#search-engines).
- **First in line by plan when room is short.** When a region is short of
  room, the room that frees goes first to the highest lane waiting for it:
  Enterprise, then Scale, Pro Max, Pro and Free, from the account's plan,
  and Runtime's own work after every customer's. Until an account chooses a
  plan, paying accounts go before trials. A create or wake refused
  `no_capacity` keeps its place while it is sent again with the same
  `Idempotency-Key`, as the SDKs do, and the refusal says its place, how
  many wait ahead and its lane, also in `details.line`. Nothing already
  running is stopped for a higher lane. See
  [waiting in line for room](./limits#waiting-in-line-for-room).

- **A slow upload is given the time to arrive.** A request's 110 seconds to
  answer now start once its body has arrived, so a chunk of a large upload
  over a slow or busy link is no longer cut while its bytes are still coming
  in, and answered `503 api_unavailable` as if the API were at fault. A body
  may take up to about 280 seconds to arrive. One still arriving after that
  is answered `408 request_timeout` with the bytes received so far; the SDKs
  and the CLI get `503 body_stalled` and send it again by themselves. Many
  uploads at once over one slow link share it: send fewer at once. See
  [files](./api#files).
- **30 days to top up.** When credit runs out in an account that has bought
  credit or saved a card, its stopped and paused sandboxes' disks are kept 30
  days, not seven, with a notice first and a warning the day before, and
  adding credit in that time keeps them. Other stored items, and every item
  in an account that has done neither, keep their seven days. See
  [when your balance runs out](./pricing#when-your-balance-runs-out).

- **A scheduled job keeps data between runs on a volume.** A job's
  `compute.volumes` attaches up to four of your volumes to every run, each at
  a path, as a sandbox create does: read-write, one run at a time, so each run
  reads what the last one wrote, or a read-only `snapshot` copy. In the CLI,
  `runtime jobs create ... --volume <id>:/data`, and for a job you already
  have, `runtime jobs update <job> --volume <id>:/data` or `--no-volumes`; in
  the SDKs' next release. A run that waits for its volume says so with
  `blockedReason` `volume`. See
  [Keep data between runs](./jobs#keep-data-between-runs).
- **A full region answers 503, and an account at its limit 429.** No room
  for a sandbox, a fork, a restart, a wake, a build or a volume,
  `no_capacity`, is now `503 Service Unavailable` with `Retry-After: 1`.
  The account at a limit on what runs at once, `quota_exceeded` or
  `no_credit_running_limit`, is now `429 Too Many Requests` with
  `Retry-After: 5`. All three were `409 Conflict`, which a client that
  retries only 5xx and 429 gave up on. Such a client now retries them with
  no change. The body is the same, so code that reads `error.code` keeps
  working. In the SDKs' next release the error's
  class follows the status: `no_capacity` is a
  `ServiceUnavailableError`, and the two limits are a `RateLimitError`, not a
  `ConflictError`. The SDKs still wait them out on create, wake and restart,
  and return them at once elsewhere, as before. See
  [errors](./api#responses-and-errors).
- **Every error says whether to retry it, and its status means what HTTP
  says.** Each error now has `retryable`, `true` or `false`; a retryable one
  always carries a `Retry-After` header, and no other does. Each code has one
  status, listed with every code in [Responses and errors](./api#responses-and-errors)
  and in the OpenAPI document's `x-error-codes`. Codes are unchanged, so code
  that reads `code` keeps working; a check on the status may need a look:
  - 409 is now only a state you change first, or one that clears by itself
    (`snapshot_not_ready`, `image_not_ready`, `volume_releasing`, ... are
    retryable).
  - Your own limits that clear by themselves are 429, always with
    `Retry-After`: `quota_exceeded` on what runs at once (`details.limit`
    such as `sandbox.count` or `sandbox.memory_mib`), the `no_credit_*`
    limits on what runs, `process_limit`, `transfer_limit`, `guest_busy`,
    `build_in_progress` and the daily caps.
  - A count that falls only when you delete something is 409, with
    `retryable: false` and no `Retry-After`, so no retry library retries
    it: `no_credit_kept_limit`, `limit_reached` (keys, invitations,
    compartments) and `quota_exceeded` on what is kept (volumes, snapshots,
    images, secrets, `sandbox.kept`). Delete one, or raise the limit.
  - A full region or host is 503 with `Retry-After`: `no_capacity`,
    `host_capacity`, `own_share_full`.
  - A product switched off on a deployment is 501, not 503, so no client
    retries it.
  - A fault of ours that a retry does not fix is 500 (`operation_failed`,
    `price_unavailable`, and `watch_failed`: Runtime's own file watcher in a
    sandbox); a service behind the API is 502 or 504.
  - A request that cannot be done as asked is 422: `disk_too_small`,
    `idempotency_conflict`, `no_credit_size_limit`, a program in your sandbox
    that failed (`interpreter_failed`, `tunnel_unavailable`).
- **The SDKs read `retryable`** (in the same versions). They retry an answer
  that says `retryable: true` after its `Retry-After`, and never one that says
  `false`. A create, wake or restart waits out room and the account's limits
  for its own wait for room (two minutes by default; `0` returns at once), and
  a fork returns them at once. An answer whose wait is over a minute (a daily
  cap) is returned at once, with `retryAfterMs`. The Go, Ruby and Java SDKs now
  also resend a call refused `guest_busy`, `busy` or `rate_limited` until its
  deadline, as JavaScript and Python do. The CLI's `--json` errors carry
  `retryable` and `retryAfterMs`.
- **Accounts without credit hold up to 10 API keys.** A new key past ten is
  refused with `no_credit_key_limit` (409) and says how to make room: revoke a
  key you no longer use, or add credit, after which there is no limit. Every
  key an account already holds keeps working, and keys Runtime makes for the
  console, its terminals and image builds are not counted. See
  [free usage](./included-usage#without-credit).

## 20 October 2026

- **`runtime.apps` in the TypeScript SDK, for the Apps private beta.**
  `withruntime`'s next release (`npm i withruntime@latest`) has
  `runtime.apps`: create an App, deploy an image to it, follow the deploy,
  roll back, and list its versions and copies. Apps is a private beta for now: an account outside it gets
  `product_in_beta` (403), with a hint to ask support to join.
- **Book room for a burst.** Book room for up to 10,000 sandboxes of one size
  for a window of up to 24 hours, starting now or within 14 days, and be told
  at once whether you have it. In the window your creates are never refused
  `no_capacity` or `quota_exceeded` up to what you booked; sandboxes you run
  bill as usual. A decline says why, the most that fit and the nearest window that
  takes them all. In the API (`POST /v1/reservations`), the JavaScript,
  Python, Go, Ruby and Java SDKs (`runtime.reservations`), the CLI
  (`withruntime reservations book`) and MCP. See
  [Book room for a burst](./reservations).
- **Booked room left unused costs a little.** Room a booking holds that none
  of your sandboxes uses now costs a quarter of the memory rate,
  $0.001875 per GiB-hour, with no CPU charge; sandboxes you run
  bill as usual. 300 sandboxes of 2 GiB booked for 2 hours cost at most
  $2.25 if none run, and nothing if you cancel at least an
  hour before the start. A booking's answer, the CLI and the console's Booked
  room card say the most it can cost. See [What it costs](./reservations#what-it-costs).
- **Standing room for a pool.** Keep room for a pool of sandboxes until you
  cancel it: name the snapshots it forks from and the room is held on the
  servers holding them, so a sandbox replaced after each use is never
  refused for room or limits. `forKey` keeps it for one key's sandboxes, and
  `inUse` says how much of it runs now. Room none of them uses costs a
  quarter of the memory rate, $0.001875 per GiB-hour. See
  [standing room](./reservations#standing-room-for-a-pool).
- **Audit log entries older than 400 days are now removed.** The audit log
  has always promised to keep each entry for at least 400 days; until now it
  kept every entry forever. From this release, entries past 400 days are
  deleted, oldest first, and none younger is ever touched. See
  [the audit log](./teams#audit-log).
- **Node trusts HTTPS from a sandbox's first command.** A sandbox with
  egress secrets checks its HTTPS with Runtime's own certificate authority,
  and Node, which keeps its own roots, learns it from `NODE_EXTRA_CA_CERTS`.
  A sandbox's or a scheduled job's first commands, in its first few seconds,
  could start without that variable, and Node refused every HTTPS call with
  `SELF_SIGNED_CERT_IN_CHAIN`. They now have it from the start. See
  [networking](./networking).
- **The CLI says when a certificate is not trusted.** Behind a proxy or
  firewall that inspects TLS with its own authority, every call failed as
  "No answer from Runtime". It now says the certificate presented is not one
  your machine trusts, with its code, and to point `NODE_EXTRA_CA_CERTS` at
  the proxy's certificate.
- **`runtime images build -f` reads the Dockerfile as `docker build` does.**
  `runtime images build . -f apps/web/Dockerfile` builds a monorepo's app with
  the repository as its context: `-f` is read from where you run the command,
  and a path inside the folder still works. See [images](./images).
- **Apps and Functions: what Cloudflare's cache serves is outbound traffic
  (private beta).** Once Cloudflare's cache serves Apps and Functions, the
  bytes it serves for an App's or a Function's addresses and custom domains,
  without reaching it, are charged as outbound traffic, the same as a
  sandbox's: from the account's 100 GiB a month free first, then
  $0.02 per decimal GB. They are read from Cloudflare's analytics
  an hour at a time, charged once per hour, and shown in `GET /v1/usage` under
  `outbound`. An App or Function made without credit sends for free and uses
  none of the allowance.
- **Storing several secrets at once no longer fails.** Writing egress
  secrets (`PUT` or `DELETE /v1/egress-secrets/{name}`) or the upstream proxy
  from parallel jobs of one account used to fail with 503 busy for all but
  one of them. Now the writes wait in line and each one succeeds. See
  [the API](./api).
- **Sandbox desktop, browser, MCP servers and mounts in the console.** A
  sandbox's page now lets you open its desktop and watch it live, record it,
  start or stop its browser, and see or stop its code contexts, MCP servers,
  bucket mounts, file watches and tailnet, each stop asked first. Networking
  gains the switch for your sandboxes to
  [reach each other by name](./networking#reach-your-other-sandboxes-by-name).
- **Faster website on phones.** Pages on withruntime.com no longer download
  two extra font files, 140 KB, to look for a single character such as "10⁹"
  or "✓": the home page loads about a third lighter on a phone, and the
  pricing, comparison and blog pages about a fifth lighter. See
  [pricing](./pricing).
- **Clearer page titles in search results.** Guides now show titles that
  say what they cover, such as "Python SDK for agent sandboxes" or "Custom
  sandbox images from any Dockerfile", so they are easier to find. See
  [the Python SDK](./python).
- **CI/CD leaves no run "Waiting" on GitHub after its check ended.** A
  check restarted midway, or one whose tests were split into a different
  number of parts, could leave old `runtime / …` runs queued or in progress
  on the commit for good, though the check itself had passed, failed or been
  cancelled. Within a few minutes of a check's end, every run of it GitHub still
  shows open is now ended: a job's run with its job's result, an extra
  `runtime` run with the check's own, and a run of a job the check no longer
  has as Cancelled, "Not run: its check ended before this run of the job
  began." Another check of the same commit keeps its runs as they are.
- **A CI/CD check that can no longer finish now fails, with the reason.**
  Before, a check whose runner stopped, or whose job hung, could show "in
  progress" on GitHub for hours. Now it fails within minutes of the point it
  can no longer finish, saying why: a job sent nothing for longer than its
  30-minute limit, no
  machine came for its jobs in 45 minutes, no runner has held it for 30
  minutes, or it waited an hour to start. Re-run it on GitHub to check the
  commit again.
- **Choose what happens when an App release gets worse (private beta).** An
  App or Function now has `releaseWatch`: when a new version's errors or speed
  get clearly worse in its first 15 minutes, `alert` (the default) tells the
  account's owners, `rollback` also goes back to the previous version by
  itself, and `off` does neither. Each release judged worse posts an
  `app-release-worse` notice to `GET /v1/notices` for every owner, shown on
  Usage & billing and emailed to them. Set it on create or update from the
  API, the MCP tools, or the JavaScript 0.24.0, Python 0.22.0, Go 0.11.0, Ruby
  0.10.0 and Java 0.10.0 SDKs. Only an account-wide key made on the website
  turns it off: a key in a compartment, a key made by another key and a
  sandbox's own session key may choose `alert` or `rollback`, and `off` is
  refused with `403 forbidden` ([compartments](./security#compartments),
  [run a swarm](./teams#run-a-swarm)).

- **A job tells you when it fails, runs your image, and changes in place.**
  A job's `alert` posts to your webhook, signed with a jobs secret, or emails
  you once runs fail in a row, with the run's reason, exit code and last lines
  of output, and once more when a run succeeds again. Your account's webhooks
  hear `job.run.failed` and `job.recovered`. `--image` starts each run from an
  image of yours, and `runtime jobs update` (`PATCH /v1/jobs/{id}`) changes a
  job's command, image, size, secrets, alert, timeout or retries and keeps its
  history. In `withruntime` 0.29.0 for JavaScript and the CLI, and 0.28.0 for
  Python. See [alerts](./jobs#alerts).
- **Every App has a readable address (private beta).** Every App and
  Function, those you have and every new one, answers at its name, 16 random characters, then its
  account's handle: `https://shop-3f9a1c2e7b04d915-acme1.runtimehost.com/` for the App
  `shop` of the account Acme, in `url` on the App and its deploys, in the API,
  the console and every SDK. It is kept for life: a rename leaves it, and a
  handle is never another account's, even after an account closes. Every App
  keeps its id's address too.
- **A disk snapshot of a sandbox that is writing no longer fails.** A
  `mode: "disk"` snapshot of a running sandbox used to fail with "could not
  confirm that its writes reached its disk" whenever a program in it was
  writing. Its pause now waits for the sandbox to write out what it still
  held in memory before the snapshot is taken. That takes milliseconds when
  the sandbox is quiet and can take a few seconds while it writes. Memory
  snapshots are as fast as before. See [the API guide](./api).
- **A trust center for your security review.** [withruntime.com/trust](https://withruntime.com/trust)
  gathers what a security team asks a vendor for on one page: the public
  documents, where data lives, how sandboxes are kept apart, encryption,
  sign-in, availability and recovery, every subprocessor, and how to report
  a vulnerability. A filled-in questionnaire is on request from security@.
  See [security and compliance](./trust).

## 19 October 2026

- **Fly Machines API on Runtime.** Code written for Fly's Machines API now
  runs on Runtime by changing one address: run `npx withruntime fly-api` and
  point `FLY_API_HOSTNAME` (or fly-go's `FLY_FLAPS_BASE_URL`) at it. Each
  Machine is a sandbox; `init`, `env`, `files`, metadata, leases and the
  restart policy work, and what isn't supported is refused with Runtime's
  alternative. Node services can serve it themselves with `machinesApi()` from
  `withruntime/fly`. See [switching from Fly Machines](./fly-alternative#from-machines).
- **Every router serves the same routes, and a copy stops only once none
  sends it visitors.** An App's or a balancer's change counts served only once
  every Runtime router serves it, so a deploy's old copies stop only after no
  router can still send them a visit. A router that has never had its route
  table yet answers `router_not_ready` (503, `Retry-After: 1`) instead of
  `no_route`. See [Networking](./networking#what-a-visitor-can-get).
- **Functions in the CLI and the console (private beta).** `runtime functions`
  creates, deploys, lists, reads, updates, rolls back and deletes Functions,
  and lists their releases, versions and copies, as `runtime apps` does for
  Apps. In the console, Functions has a list of its own beside Apps, and each
  Function a page with its calls, errors, releases, copies and logs, with
  deploy and rollback. Outside the beta these are refused with
  `product_in_beta`. See the [CLI](./cli).
- **Snapshots kept while you have credit have no end date.** A snapshot taken
  without `retentionDays` used to be deleted a year after it was taken, even
  with credit on the account. Now it is kept for as long as you have credit,
  as the 4 October entry said. See [pricing](./pricing).
- **The Vercel-compatible snapshot's `expiresAt`.** For a snapshot kept while
  you have credit it now reports a year from now, moving on with each read,
  instead of a year after the snapshot was made, a date that would pass while
  the snapshot was still kept. In the JavaScript SDK's next release.
- **The data processing addendum, privacy policy and subprocessors page say
  more, and say what is true today.** A new subprocessor is listed at least 30
  days before it starts, and you may object within those 30 days; email
  legal@withruntime.com to be told when the list changes. A breach affecting
  your data is reported to your account's owners within 72 hours, with what
  happened, who and what it touches and what we are doing. Closing an
  organization destroys its key first, then deletes its data, and the
  addendum gives every step's time limit, including each server's own nightly
  backup, gone within 44 days. Once we hold a SOC 2 report, it is shared under
  a confidentiality agreement as our answer to audit requests. The addendum
  lists the security measures we run now. Anthropic, which runs the AI model
  that answers support, and Slack, which carries our team's alerts and support
  drafts, are now on the subprocessors page. See
  [security and compliance](./trust).
- **Keep-alive ends when its sandbox is deleted.** In every SDK, a sandbox's
  keep-alive (`keepAlive`, `keep_alive`, `KeepAlive`) now ends at the first
  answer that the sandbox is gone, as when it was deleted by id from another
  handle or another process. Before, it went on reading the deleted sandbox
  once a minute for as long as the program ran.
- **Storage is limited in GiB, not only counted.** An account keeps up to
  500 GiB in all with credit (50 GiB without): snapshots, images, volumes,
  volume backups and paused or stopped sandboxes, measured as they are
  billed; snapshots up to 250 GiB of it (20 GiB without). Past a limit nothing
  is deleted or stopped: a new snapshot, image, backup or volume is refused
  with `quota_exceeded`, naming the limit, until there is room. An account
  that already stored more than a limit when it began has what it stored then
  as that limit. Both are on the Limits page and in `GET /v1/limits`. See
  [limits](./limits#storage).
- **Requests in flight grow to your sandbox quota.** An account's requests
  in flight grew by six for each sandbox it holds only up to 1,024 (138
  sandboxes). Now an account whose sandbox quota support raised past 138
  keeps growing, six for each running sandbox up to that quota: 2,592 for
  400 running, so each can stream four commands and two watches at once.
  Watch streams, SSH logins, port forwards and terminals grow with it. See
  [limits](./api#limits).
- **A command may run 15,360 processes and threads.** One command and
  everything it starts may hold up to 15,360 processes and threads together,
  of a sandbox's 16,384; it was 1,024. Test runs that start many processes,
  Java and parallel builds on a sandbox with several vCPUs no longer fail to
  start a thread. A sandbox gets it the next time it starts; a custom image,
  once it is built again. See [limits](./api#limits).
- **Started copies are kept for images in use.** A server keeps an image's
  started copies (the ones a sandbox starts from in about half a second)
  while sandboxes are created from that image there. Once none has been for
  2 days, the copies go. The first sandbox after that gap boots the image (a
  few seconds), and the ones after it start from copies again. Before, every
  image version kept its copies on every server it reached, used or not. See
  [Images](./images).
- **See which files a command read.** Run a command with `traceFiles: true`
  and its answer lists every file and folder it, and anything it started,
  opened, and every file it wrote; other programs on the sandbox never show
  up. Key a test cache by those files and rerun only the tests whose files
  changed. Background processes, every SDK and `runtime sandboxes exec
--trace-files` have it too. See
  [commands and processes](./api#commands-and-processes).
- **A paying account's stopped sandboxes keep their disk 30 days.** When a
  sandbox stops to clean up (a stop from an older client, the end of its time
  limit, or a crash), an account that has paid, holds credit or saved a card
  for automatic top-ups now keeps its disk free for 30 days after the stop, not
  three. Disks already waiting in such an account move to 30 days from their
  stop, never less than a day from now, and you get the deletion notice again
  before the new date. Other accounts keep three days. See
  [paused storage](./pricing#paused-storage).
- **Turn an App's CDN off (private beta).** Cloudflare's CDN sits in front of
  every App's and Function's addresses by default, with no separate fee. Set
  `cdn` to `false` when you create or update one (`--cdn off` in the CLI, `cdn`
  in the API, MCP tools and every SDK) to send visitors straight to Runtime's
  routers, with nothing cached.
- **Read and follow an App's logs (private beta).** What an App's or a
  Function's copies print to standard output and error is kept 14 days and
  read back with `GET /v1/apps/{id}/logs` (`/v1/functions/{id}/logs`), the
  `runtime_apps_logs` and `runtime_functions_logs` MCP tools,
  `runtime apps logs <app>` in the CLI, and `logs` in every SDK. Narrow it by
  `since` (a time, or `30s`, `15m`, `2h`, `7d`; an hour by default),
  `version`, `copy` and `stream`; page back with `cursor`. With `follow` it
  streams each line as it is printed, and the SDKs and the CLI reconnect by
  themselves and give each line once. A key that may read files reads the
  logs of the Apps it can see, a worker's or a compartment's key its own
  Apps' alone. Outside the beta these calls are refused with
  `product_in_beta`.
- **Sandboxes with egress secrets start under heavy load.** Creating a
  sandbox that names its egress secrets (`secrets`) checks its list again
  rather than failing at once with `secrets_unconfirmed` when the service is
  busy, and one account
  sending far more requests than its limit is slowed alone while other
  accounts' calls go through. See [Keys and secrets](./security#keys-and-secrets).
- **Request timeouts on sign-up and webhook routes.** A request to a route you
  call before you have a key (the [MCP sign-up](./mcp), GitHub's webhooks and
  install link, and an agent's reports) whose body has not all arrived after
  5 seconds is now answered `408 request_timeout` straight away: send it
  again. Before, it waited 15 seconds or more and was answered
  `503 api_unavailable` as if Runtime had failed. See [errors](./api#responses-and-errors).
- **The Prime Sandboxes drop-in follows 0.4.7.** Code written for
  `prime-sandboxes` 0.4.7 runs on `withruntime.prime`. Its new `arch` option
  on create works with `"amd64"`, and `"arm64"` gets a plain error before any
  sandbox is made, as Runtime sandboxes are x86-64. `create_lan_network` now
  takes `rules` and, as before, names Runtime's private network instead. See
  [Migrate](./migrate).
- **Workers start from their coordinator's snapshots.** A key made by a key
  can now create a sandbox from a snapshot that its maker, or any key above
  it, took and labelled `share: made-keys`. It can only start from it: it never lists,
  reads, changes or deletes it, and a snapshot without the label stays out of
  its reach. The label is never copied to sandboxes, forks or new
  snapshots made from a shared one: set it on each snapshot you share.
  Worker keys made before this release need to be made again to use it. A
  `share: made-keys` label already on a snapshot was taken off, so nothing
  became shared by itself; a `share` label of any other value is untouched.
  A snapshot of a sandbox that named its egress secrets (`secrets`) is
  never shared: workers get `snapshot_not_found` for it, while its owner
  still starts it. Sharing never crosses a compartment.
  Before, a worker key with reach `agent` was answered
  `snapshot_not_found` for every snapshot but its own. See
  [Run a swarm](./teams#run-a-swarm).
- **A scraping account no longer gets other accounts blocked.** Runtime can
  move an account whose sandboxes scrape sites to outbound addresses kept for
  scrapers, so a site that answers it with a CAPTCHA or a ban does not block
  the other accounts on the same server. The move reaches its running
  sandboxes at their next connection, they keep their internet throughout, and
  the addresses are in the same published list as the shared ones. See
  [Shared addresses](./egress#shared-addresses-and-per-address-limits).
- **MCP sandbox switch and resize refusals say what to do.** Through
  MCP, switching a sandbox's image while asking to keep more than
  `/workspace` again says what a switch keeps and how to keep everything
  (snapshot first), and a resize sent without a restart says that a resize
  always restarts, instead of naming only the field. See [MCP](./mcp).
- **Jobs secrets belong to the key that stored them.** A jobs secret stored
  by an API key can now be used only by that key, by agents you name, and by
  you. Share it with your other keys using
  `runtime secrets share NAME --agent <id>`, `--all` or `--none`
  (`secrets.share` in the SDKs, `POST /v1/secrets/{id}:share`). Secrets you
  store on the website stay every key's. A job that binds a secret another
  key stored stops at its next run until that key or you share it; if another
  of your keys could reach a secret before now, rotate it. A job created with
  a secret its key may not use is refused with `secret_not_shared`. See [secrets in a job](./jobs#secrets-in-a-job).
- **Ask support to stop our emails and get a straight answer.** Email
  support "remove me from your list" and the support agent now tells you
  which of Runtime's emails reach that address, if any, and how to stop each:
  the link at the foot of each optional email, or
  Settings, Emails in the console. It no longer
  passes the request to a person or promises a removal. See
  [Stopping Runtime's emails](./feedback-and-support#stopping-runtime-s-emails).
- **Raise how many sandboxes run at once.** Ask support for a higher count
  and it is raised for your account with the vCPUs, memory and disk to match,
  never below what auto top-up gives, whether auto top-up is on or off. See
  [when you meet one](./limits#when-you-meet-one).
- **A sandbox paused for abuse stays paused until support lifts it.** When
  the abuse checks pause or stop a sandbox for traffic only abuse makes, such
  as reaching a cryptocurrency mining pool, a wake, restart, snapshot or fork of it
  now answers `sandbox_halted` (403) saying why, instead of running it again. Its files are kept,
  and your inbox says what was seen. See [Security](./security#network-access).
- **A build on a busy server waits for room instead of failing.** When the
  server an image builds on has no room for its build machine at that moment,
  the build waits up to five minutes for room and then runs, and its log says
  it is waiting. Before, it failed at once with a fault on our side and asked
  you to build again. See [Images](./images).
- **Narrow a secret without its value.** `runtime secrets set NAME
--keep-value` with a narrower `--host` or `--allow` takes hosts, methods or
  paths away from a secret you stored, with no need to have its value at hand:
  a token that could push to a repository can be made fetch-only by anyone who
  may write secrets. Anything wider is refused, since a new place could learn
  the value. In the API, `PUT /v1/egress-secrets/{name}/rules`; in every SDK,
  `secrets.narrow` (withruntime 0.22.0 for JavaScript, 0.21.0 for Python); in the console, leave the value empty
  when you edit a secret to take hosts or rules away. The audit log records each one.
  See [Secrets sandboxes never see](./security#secrets-sandboxes-never-see).
- **Links to one file in a sandbox, with no API key.** `files:link` (API),
  `sandbox.files.downloadUrl` and `uploadUrl` (JavaScript, with `download_url`
  and `upload_url` in Python, and the same in Ruby, Go and Java) and
  `runtime sandboxes link` make a secret, expiring URL for one file. A GET downloads it
  (Range works, so videos play and downloads resume); a PUT writes it
  atomically, up to 5 GiB. A link lasts 1 hour by default and at most 7 days;
  `revokeLinks` ends every link of a sandbox, and revoking the key that made
  one, or deleting the sandbox, ends it too. E2B's `downloadUrl` and
  `uploadUrl` now work the same way. JavaScript 0.25.0, Python 0.23.0, Go 0.12.0,
  Ruby 0.10.0 and Java 0.10.0. See [files in the API guide](./api#file-links).
- **Apps, Functions and Builds in the Go, Ruby and Java SDKs (private beta).**
  Go 0.7.0 (`client.Apps`, `client.Functions`, `client.Builds`), Ruby 0.6.0
  (`client.apps`, `client.functions`, `client.builds`) and Java 0.6.0
  (`apps()`, `functions()`, `builds()`) carry every method the TypeScript SDK
  has: create, deploy from an image or a build and wait for it, roll back,
  versions and copies; builds of a connected repository with their log,
  followed as it is written. Each can also ask for the link that installs
  Runtime's GitHub App, so private repositories build. Outside the beta these
  calls are refused with `product_in_beta`.

## 18 October 2026

- **GitHub App tokens, push limits and API budgets for secrets.** A secret
  can now hold a GitHub App's private key (`githubApp`): our servers make its
  installation tokens and add them to your sandboxes' GitHub requests and git
  pushes, and the key itself goes into no request. `git.push` names the
  branches a push may update, such as `refs/heads/task/{label.task}`: each
  label's branch belongs to the first sandbox made with it, even once it is
  deleted, and that label can't change after the sandbox is made. Any
  other push is refused with git's own `[remote rejected]`, as is any API call
  that would move, merge or write to another branch. `api` caps each
  sandbox's calls and writes an hour, lists the GraphQL mutations allowed,
  and lets sandboxes share cached reads. A rule's path segment that is `*`
  alone now names any one segment. See
  [GitHub: an App's tokens, branch limits and API budgets](./security#github-an-app-s-tokens-branch-limits-and-api-budgets).
- **SDKs take a secret's GitHub App, push limits and API budgets.**
  `withruntime` 0.25.0 for JavaScript and 0.23.0 for Python, the Go SDK 0.12.0, and
  the Java and Ruby SDKs 0.11.0 set and return `githubApp`, `git` and `api`. See
  [GitHub: an App's tokens, branch limits and API budgets](./security#github-an-app-s-tokens-branch-limits-and-api-budgets).
- **Clear refusals instead of 500 errors on sandbox create.** A create
  that asks for ports beyond 80 and 443 (`network.connect`) from an account
  without a kept top-up is refused with 403 `connect_not_allowed`, saying
  what lifts it, and a `maxTotalCostMicros` below the first minutes a paid
  sandbox holds is refused with 400 `invalid_request` naming that field; both
  answered 500 before. A pause sent while a sandbox is still starting, a
  wake sent while it is pausing, and a restart sent while it is stopping now
  wait for it instead of being refused, and a file call right after a wake
  waits for the sandbox to listen instead of answering `guest_busy`. A
  persistent sandbox stopped before it ever started now reads
  `diskKept: false`, since it has no disk to restart from; it read `true`,
  and its restart was refused. See [networking](./networking),
  [limits](./limits) and [the API guide](./api).
- **API key limited to chosen sandboxes, approved in the browser.** An agent
  with no key can now ask for a key that reaches only the sandboxes it names,
  whichever key or connector made them: `runtime keys create --sandbox <id>
--actions get,exec`. An owner or admin approves it from a link, seeing each
  sandbox and what the key may do. Without `create` it cannot start, wake or
  restart them; a running one is billed as usual until its own time limit. See
  [asked for in the browser](./teams#asked-for-in-the-browser).
- **Snapshot starts no longer stop for CPU on one server.** A sandbox started
  from a snapshot whose server was short of CPU for your other sandboxes used
  to stop with `account_busy_here`. Now it starts on another server that holds
  a checked copy of the snapshot, and stops only when none of them has room
  (or after it has moved 3 times).
  See [A sandbox stopped on its own](./troubleshooting#a-sandbox-stopped-on-its-own).
- **Apps console with traffic and live releases.** Console → Apps shows each
  App as a card with its last day of requests, error rate, copies running,
  last release and this month's cost. An App's page draws its copies by
  version, a release step by step as requests move to the new version, its
  requests, errors and latency over an hour, a day or a week, its busiest
  routes, and log search by request id or any words. A failed release keeps
  its output, and the previous version rolls back in one click. See
  [custom domains on an App](./networking#on-an-app).
- **Move from Cloudflare Sandbox to Runtime.** A Worker written for
  Cloudflare's Sandbox SDK (0.x) now runs on Runtime sandboxes once you change
  its import to `withruntime/cloudflare`, delete the `containers` block from
  `wrangler.jsonc` and add a `RUNTIME_API_KEY` secret. Commands, streaming,
  files, background processes, the code interpreter, preview URLs, sessions
  and `gitCheckout` work as before. See
  [change the import](./cloudflare-sandbox-alternative#change-the-import).
- **A sandbox can name the secrets it gets.** Create a sandbox with
  `secrets: ["ANTHROPIC_API_KEY"]` (`runtime sandboxes create --secret
ANTHROPIC_API_KEY`) and it gets only that egress secret: no placeholder for
  any other, and our proxy puts no other value into its requests. An agent
  given untrusted input can no longer send a key meant for other work. `[]`
  is none; the list narrows each secret's own `only`, is fixed for the
  sandbox's life, and a fork or copy of a snapshot may only narrow it. In the
  API, the MCP tool and every SDK. See
  [secrets sandboxes never see](./security#secrets-sandboxes-never-see).
- **One deletion email a day, not one per pause.** A sandbox with
  `:retention` days of its own is a day or so from deletion after each idle
  pause, and its owners were emailed a warning on every pause, though using
  it again cancels the deletion. Warnings for dates you set this way are now
  emailed at most once a day for the account, listing every sandbox due, and
  never once a sandbox has woken or paused again since; the email says its
  own retention chose the date, and `null` keeps it while you have credit. See [pricing](./pricing#paused-storage).
- **A secret that could not be added is no longer silent.** When a request to
  a secret's host leaves your sandbox without the secret because our server
  could not add it at that moment, the sandbox now gets a
  `sandbox.secret_not_applied` event with reason `withheld`, saying the fault
  is ours and what to do. See [events](./observability#events).

- **A worker's key runs its own Apps.** A key made by another key, or a key in
  a compartment, can now create, list, deploy, roll back and delete the Apps
  and Functions its own agent made, as it does sandboxes, over the API and
  MCP. Another agent's App still answers 404. Such a key deploys from an
  image only: a deploy naming a `build` answers 403 (`forbidden`, or
  `outside_compartment` in a compartment); deploy builds with an account's
  key. Such a key asks an App for at most 2 `minCopies`, 2 `spares` and 20
  `maxCopies`; a larger App is made with a key made on the website. It
  cannot give an App or Function a name one of the account's own Apps holds:
  create or rename answers 409 `name_taken`. See
  [Run a swarm](./teams#run-a-swarm).
- **MCP: `runtime_apps` action `deploy` takes its `id`.** It refused its own
  `id`, and listed no `image` or `build`, for every key; it now takes them.
  The `runtime_apps` tool also answers a worker's or compartment's key in the
  Apps beta, which it refused before.
- **Snapshots and forks in bursts no longer wait running.** A snapshot or a
  fork of a running sandbox now stops it at once, so the snapshot, or the
  fork's copies, hold the memory of the moment you asked, and then waits for
  its turn at the server's disk with the sandbox stopped. Before, it waited
  for that turn with the sandbox still running, and a burst on one server
  could take tens of seconds each, the sandbox changing all the while. A
  sandbox whose time limit or funded time ends soon, on a busy server, still
  waits running and stops at its turn, as before. See [products](./products).
- **Secret scopes in the Python, Go, Ruby and Java SDKs.** The SDKs can now
  give a secret to some sandboxes instead of all of them, as the JavaScript
  SDK can: `only` on `secrets.set` (`only=` in Python and Ruby, `Only` in Go,
  a sixth argument in Java) and `secrets.scope(name, only)` (`Scope` in Go),
  which changes who gets an existing secret without its value. Python is
  0.17.0, Go 0.6.0, Ruby 0.5.0 and Java 0.5.0. See
- **Give a secret to one App's copies.** `runtime secrets scope NAME --only-app <app id>`
  gives a secret to every copy of an App, including copies later deploys,
  restarts and scaling make; a deploy names the secrets its copies see with
  `secrets: ["NAME"]`, and a copy holds only the placeholder. An App copy's
  identity token now says which App it is (`app_id`). See
  [secrets sandboxes never see](./security#secrets-sandboxes-never-see).
- **A sandbox out of memory still answers.** When a sandbox's programs fill
  its memory, Linux now ends one of them for memory, as the guide says,
  instead of the whole sandbox slowing until commands, reads and kills time
  out. Your programs share its memory less a small reserve for the sandbox's
  own services. See
  [when a program runs out of memory](./sandbox-environment#when-a-program-runs-out-of-memory).
- **Upload stalled: a clear answer in 30 seconds, not a 503 after two minutes.**
  A request whose body stops arriving for 30 seconds, such as a chunk of a
  large upload, is now answered at once with the bytes received, where before
  it waited about two minutes and answered `503 api_unavailable`. A body that
  keeps arriving, however slowly, is never cut. The SDKs and the CLI get
  `503 body_stalled` and send it again by themselves with the same key; other
  clients get `408 request_timeout`. See
  [errors](./api#responses-and-errors).
- **Fetch a web page in under a second with a paused browser.** The guides
  show how to keep spare browsers paused, charged only for storage, and wake
  one per page: wake to page done measured 0.56 to 0.81 seconds. Python's
  guide gains its browser section. See
  [Spare browsers, paused](./javascript#spare-browsers-paused).
- **Connection limit per site: 429 Too Many Requests from the egress proxy.**
  A sandbox opens up to 20 new connections a second to one site, and an
  account's sandboxes on one server up to 100 together, after a burst. Past
  it the connection is refused with `429` and a sentence naming the site.
  Downloads over open connections, installs, clones, storage, CDNs and AI APIs
  are never counted. See [connections to one site](./egress#connections-to-one-site).
- **Identity tokens from any running sandbox.** A program with no
  `RUNTIME_ID_TOKEN_REQUEST_*` variables, such as one started before they were
  set or a sandbox kept from older guest software, now gets a token too:
  `Sandbox.identityToken()` (TypeScript 0.17.3), Python's
  `Sandbox.identity_token()` (0.16.2) and `runtime sandboxes identity-token`
  ask the sandbox's host for them, and the docs show the same with curl alone.
  See [identity tokens](./identity-tokens).
- **No 429 for a busy key right after an update of Runtime.** A key whose
  account runs many sandboxes may send up to 8 times the ordinary rate. Just
  after Runtime updated its servers, its first requests met the ordinary
  rate instead, for the moment it took to recognise the key, so a burst
  sent then was answered `429 rate_limited`. Those requests now wait that
  moment, at most two seconds, and are served at the key's own rate.
- **Daytona's GPU and sort enums import from the drop-ins.** The Daytona
  drop-ins follow Daytona 0.225.0 and the Prime Sandboxes one follows 0.4.6.
  `GpuType`, `SandboxClass` and the list sort enums now import from
  `withruntime/daytona` and `withruntime.daytona`, and the sort enums sort
  `list`. A Python create that asks for a GPU type now gets a plain error,
  as TypeScript already did, instead of a CPU sandbox. Prime's new
  `lan_network_id` on create is refused before a sandbox is made, naming
  Runtime's private network. See [Migrate](./migrate).
- **Idle sandboxes now pause after 5 minutes.** A new sandbox, browser or
  sleeping container pauses after 5 minutes with nothing happening in it by
  default, where it was 1 minute before. Rates are unchanged, but an idle
  sandbox that sets no idle time now runs, and is billed for its memory, up
  to 4 more minutes before it pauses; set `idlePauseSeconds` to 60 to keep
  the old default. The shortest idle pause is now 60 seconds, not 10: a time
  of 10 to 59 seconds you set on a new sandbox, or change to, is raised to 60,
  so that sandbox runs, and is billed, until 60 seconds idle. The answer shows
  the 60 it got; 0 still turns pausing off. Sandboxes made before today keep
  the setting they have, under 60 too. See
  [pause when idle](./javascript#pause-when-idle).

## 17 October 2026

- **Browser starts in about 1 to 2 seconds in a new sandbox.** The browser
  now comes ready on the sandbox's host instead of being downloaded and
  installed on its first start, which took up to a minute: `browser.start()`
  in a brand-new sandbox now returns in about 1 to 2 seconds. A custom image
  that is not Ubuntu 24.04 x86_64 still installs it once on its first start
  (withruntime 0.17.2, and 0.16.1 for Python). See
  [A browser over CDP](./javascript#a-browser-over-cdp).
- **Give a sandbox a key without typing it into a command.** In the CLI,
  `--env NAME` with no `=` sends that variable's value from your own shell, as
  `docker run -e NAME` does, on `create`, `update`, `exec` and `run`
  (withruntime 0.17.1). The security guide now shows how to install a key
  your sandbox's server checks on incoming requests, and the same key at
  another provider, and how to rotate it with no failed request. See
  [Shared keys](./security#a-secret-your-sandbox-checks-on-requests-it-receives).
- **Swarm worker keys cannot reach scheduled jobs or their secrets.** A key
  made by another key with reach `agent` now gets `403 forbidden` on
  `/v1/secrets`, `/v1/jobs` and `/v1/job-runs`, and on the `runtime_jobs` and
  `runtime_secrets_jobs` tools, as the guide already said for secrets: a
  job's secrets belong to the person the key's agent serves, often the owner.
  See [Run a swarm](./teams#run-a-swarm).
- **A revoked worker's spend still counts against its maker's limit.** A key
  revoked, expired or retired counts what it spent in the last day toward
  the daily limit its maker's keys share, so revoking a worker that spent its
  limit and making another no longer spends that limit twice.
- **Run commands as root.** A command, background process or terminal now
  takes `user: "root"` and runs as root, with its environment, `PATH` and
  working directory kept and `HOME` set to `/root`, so nothing needs a `sudo`
  in front. The default is still the sandbox user, `runtime`, and each process
  says which it runs as. It is in the API, MCP, the JavaScript, Python, Go,
  Ruby and Java SDKs, and the CLI (`--root` on `exec`, `spawn`, `run` and
  `shell`). Coming from Freestyle, whose VMs run as root? See
  [how to switch](./freestyle-alternative#how-to-switch).
- **Keys limited to sandboxes.** A key can now be limited to a few sandboxes
  and to what it may do to them: look, start and restart, stop, run commands,
  or reach files. It is served nothing else, so a watcher that restarts one
  server holds no key to the rest of your account. Make one with
  `runtime keys create --sandbox <id> --actions get,create`, or `sandboxes` and
  `actions` in `POST /v1/keys` and `runtime.keys.create`. See
  [Teams](./teams#a-key-limited-to-sandboxes).
- **.NET programs run.** Programs built on .NET 7 or later, such as `dotnet`,
  PowerShell and GitHub's Actions runner, no longer stop as they start with
  "File size limit exceeded". Commands in a sandbox had a file-size limit as
  large as its disk, and .NET sizes an in-memory file at 2 TiB to map its code
  twice. Commands now have no file-size limit, as on any Linux machine: a file
  still cannot hold more than the disk, but sparse files and in-memory files
  larger than it work. New sandboxes get this. See
  [Sandbox environment](./sandbox-environment).
- **Wake and restart wait for room.** In the JavaScript, Python, Ruby, Go and
  Java SDKs, a sandbox's `wake` and `restart` now wait for room as `create`
  does. When the sandbox's own server is full (`no_capacity`), the SDK sends
  the call again with the same idempotency key, for up to two minutes by
  default, instead of failing in a few milliseconds. A sandbox stays on its
  server, so waiting is the only way it gets room. Set `waitForCapacityMs`
  (JavaScript) or `wait_for_capacity` (Python, Ruby) on one call; `0` fails at
  once. A fork never waits. See [JavaScript](./javascript#errors-and-retries).
- **API rate limit grows with your sandboxes.** An API key's rate now grows
  with the sandboxes its organization runs, as its requests in flight already
  did: about 170 requests a second in bursts of 675 with 40 sandboxes, up to
  400 a second in bursts of 1,600. Before, every key stayed at 50 a second
  however many sandboxes it drove, so one key running dozens of agents was
  answered `429 rate_limited` for much of its work. See
  [Limits](./api#limits).
- **Paused sandboxes keep their memory when many pause at once.** A sandbox
  told it was paused is now written to disk early enough even while many
  other sandboxes on its server are pausing too. Before, one could wait too
  long behind them, and wake from its disk alone with its memory lost. See
  [pause and wake](./javascript#pause-wake-extend).
- **Console pages no longer hang.** A console page whose data the database
  is slow to give now stops within 15 seconds and shows "This page did not
  load" with Try again, where it could spin for minutes. Nothing you run is
  affected. See [troubleshooting](./troubleshooting).
- **Relabelling a sandbox into a secret's scope takes effect at once.**
  Changing a running sandbox's labels so a scoped secret reaches it (or no
  longer does) now waits until its server holds the change, and the answer
  carries `secretsEnforced: true` (for a key that may read secrets; any
  other key's relabel takes up to 15 seconds, as before). Before, requests could go out without the
  value for up to 15 seconds after the label call returned. See
  [Security](./security#secrets-sandboxes-never-see).
- **A job run that reaches its timeout ends as a timeout.** A run whose
  timeout was as long as its paid time (a one-hour timeout, say) ended
  `unknown` or `canceled` with the reason `compute_stopped` when it ran to the
  end, with no exit code and no retry. It now ends `failed` with the reason
  `timeout`, keeps its exit code and output, and is retried when the job asks
  for retries. See [jobs](./jobs#what-a-run-is).
- **FUSE filesystems.** sshfs, rclone, s3fs, gcsfuse, bindfs or your own FUSE
  program mount in any sandbox as its own user, and a mount lasts through a
  pause and a wake. See
  [FUSE filesystems](./sandbox-environment#fuse-filesystems).

## 16 October 2026

- **Identity tokens in Python and copied programs.** Python's
  `Sandbox.identity_token()` (0.13.1) now asks again with the sandbox's
  current request token when the one a program started with is refused, as
  the TypeScript SDK does, and both SDKs (TypeScript 0.15.1) read it from the
  sandbox itself first, so a server carried into a fork gets a token naming
  its own sandbox instead of a 403. See [identity tokens](./identity-tokens).
- **Private preview link expiry.** A WebSocket, stream or download opened
  with a private preview's link now ends when that link expires, so a link
  made to last ten minutes, or one read through a sandbox session, opens
  nothing past its end. Open it again with a fresh link. See
  [private preview tokens](./api#private-preview-tokens).
- **Enterprise features on the pricing page.** The [pricing](https://withruntime.com/pricing#security-and-team-features)
  page now lists single sign-on, SCIM directory sync, roles, the audit log,
  two-step sign-in, key limits and compartments, the data processing addendum
  and the uptime promise, each free on every account with no enterprise plan
  or seat fee. See [pricing](./pricing#security-and-team-features).
- **Retrying a create refused for no room.** The API guide now says a
  request refused before it ran, such as a create answered `no_capacity`, is
  not replayed: retrying with the same `Idempotency-Key` runs it again, and
  the create reference names the refusal and its `Retry-After`. See
  [retries and idempotency](./api#retries-and-idempotency).
- **Identity tokens in long-running programs.** A program that runs for a
  long time inside a sandbox, such as a server or an agent, now keeps getting
  identity tokens after the sandbox's request token changes: the TypeScript
  SDK asks again with the sandbox's current one instead of failing with a 403.
  See [identity tokens](./identity-tokens).
- **Referral share after a refund or a lost dispute.** If every matched
  payment from someone you referred is refunded or disputed, their use no
  longer earns you a monthly share. If they lose a dispute, your share now
  starts again after one month instead of stopping for good. See
  [referrals](./referrals).
- **Someone leaving no longer deletes what they stored.** When a member is
  removed, or your directory suspends them, the disks,
  snapshots, volumes and images they made stay on the account's credit like
  anything else. Until now their storage stopped being paid for and was
  deleted seven days later, with a notice that blamed missing credit. A
  storage item still stops only when the account itself has no credit, hits
  a spending limit, or is suspended. See [teams](./teams).
- **Faster console pages.** Agents & API keys, Networking, Secrets, Webhooks,
  Two-step sign-in, Audit log, Limits, Support and Close account now download
  about a quarter less code, and Home, Usage & billing and each sandbox's page
  less too, so they open sooner on a slow connection. A mistyped address's
  "not found" page is lighter as well. See [the quickstart](./start).
- **Pay per call credits even after an interruption.** A sandbox paid for
  per call over HTTP 402 is now credited to the paying wallet's account
  within minutes, even if our server stopped right after sending your
  transfer and you never used the claim code. See
  [pay with stablecoins](./pricing#pay-with-stablecoins).
- **Pause vs stop a sandbox.** One table now shows what a pause, a stop
  and a delete each keep, how the sandbox comes back, when each happens on
  its own and what each costs. See
  [pause, stop or delete](./sandbox-environment#pause-stop-or-delete).
- **Open a sandbox in your editor in one step.** `runtime sandboxes code <id>`
  opens the sandbox in VS Code over SSH, and `--editor cursor` or
  `--editor windsurf` in Cursor or Windsurf. It sets up the SSH entry the first
  time and installs an SSH server in a sandbox without one. See
  [SSH and editors](./editors#open-it-in-vs-code-cursor-or-windsurf).
- **Blaxel session default length.** With the Blaxel drop-in,
  `sandbox.sessions.create()` with no `expiresAt` now makes a session that
  lasts a full day, as Blaxel's does, instead of a second less. See
  [moving from Blaxel](./blaxel-alternative).
- **Usage export and held credit.** The API guide now says which charges the
  usage export leaves out: credit held for work still running is not in it,
  and becomes a row once it settles. See
  [export settled usage](./api#export-settled-usage).
- **HTTP/2 to the hosts your secrets name.** A sandbox's HTTPS requests to a
  host that one of your secrets names now go over HTTP/2 when your client and
  the host both offer it, as they already did to every other host. Concurrent
  calls to that host share one connection instead of each taking one of the
  sandbox's connections, and gRPC works there too. Each request is still
  checked on its own: its host, its rules and where the value goes. See
  [security](./security).
- **A restart runs the image's start command again.** A sandbox from an
  image with a start command (a Dockerfile `CMD`, or `start` in
  `images.build`) now runs it again after a stop and `:restart`, a `:resize`,
  or a `getOrCreate` that restarts it, and reports it in `start` as a create
  does. Before, the server it started was gone until started by hand. See
  [images](./images).
- **Identity tokens in scheduled jobs, documented.** The [jobs](./jobs) and
  [identity tokens](./identity-tokens) guides now say that a job's run has
  `RUNTIME_ID_TOKEN_REQUEST_URL` and `RUNTIME_ID_TOKEN_REQUEST_TOKEN`, as any
  sandbox does, so a job can get a token for AWS, Google Cloud or your own API
  with no stored key.

## 15 October 2026

- **Hundreds of outbound connections, and a clear answer at every limit.**
  A sandbox of an account that keeps a top-up now holds 512 outbound
  connections open at once for each vCPU, up to 4,096, where every sandbox held 64. In a test, 500 HTTPS connections opened at once from a 1 vCPU sandbox
  all connected, where 436 of them were reset before. New connections a
  second (20, after a first 128 at once) and new hosts a minute (120) stay
  as they were for every sandbox; past them a connection waits its turn
  instead of being reset. Past any limit a connection gets `503` with the
  limit in `X-Runtime-Egress`, and the account event `sandbox.network.limited`
  says which limit, at most once an hour. `GET /v1/sandboxes/{id}/network`
  shows a sandbox's limits. Accounts without a kept top-up keep 64. See
  [the sandbox environment](./sandbox-environment).
- **Keep sandboxes on separate servers.** A create takes `spreadFrom`, up to
  16 ids of your sandboxes or snapshots, and starts on a server none of them
  is on. Every sandbox and snapshot now shows `placement`, an opaque tag that
  is the same when two share a server. A copy of a memory snapshot starts
  only on its snapshot's server, so keep warm sources apart and spread copies
  across their snapshots: each server starts copies at its own pace rather
  than refusing them `account_busy_here`. See [the API](./api).
- **A sandbox's time limit can be set or changed after it starts.**
  `:update` (`sandbox.update()` in the SDKs, or the CLI's
  `runtime sandboxes update --timeout`) takes `timeoutSeconds`, a new limit counted from now, sooner or
  later than before (`0` removes it), and `onTimeout`, what its end does. A
  sandbox made without a limit can now get one. E2B's `setTimeout` to an earlier
  time works under `withruntime/e2b` instead of throwing. See
  [Sandboxes in the API guide](./api#sandboxes).
- **Custom domain on an App.** An App can serve your own domain, apex or
  `www`, through every deploy and rollback. Its HTTPS certificate is issued and
  checked before you point the name at the App, so the first visitor already
  gets HTTPS, and it renews by itself at least 30 days before it expires. See
  [networking](./networking#on-an-app).
- **Referral and welcome matches always land.** A referral or welcome match
  that could not be decided the moment you paid, for a passing error on our
  side, is no longer lost: it is tried again within minutes until it is paid,
  and your payment is never held up by it. See [referrals](./referrals).
- **Which stopped sandboxes lose their disk after three days.** Pricing now
  names them by client version, not by date: a sandbox made by a JavaScript
  or Python SDK before 0.12.0, Go, Java or Ruby before 0.2.0, or raw HTTP
  without `x-runtime-client: http/2026-10-04` keeps its disk free for three
  days after it stops, then it is deleted. JavaScript 0.11.1 and 0.11.2 and
  Python 0.11.1 came out after 4 October and count as older. See
  [paused storage](./pricing#paused-storage).
- **pip install withruntime on Python 3.9.** The Python SDK now installs and
  runs on Python 3.9, the `python3` a Mac comes with, where `pip` used to
  find no version of it at all. See the [Python SDK](./python).
- **GitHub API rate limit exceeded.** Calls to GitHub's API without a token
  share GitHub's 60-an-hour limit with every sandbox sending from the same
  address. The guide now shows how to save a GitHub token as a secret that the
  network adds to each call, so tools get your own limit with no change. See
  [shared addresses and per-address limits](./egress#shared-addresses-and-per-address-limits).
- **llms-full.txt names each page.** Every guide in `llms-full.txt`, the
  docs in one file, now starts with its address, so an assistant that reads
  the one file can link you to the page a fact came from. AI assistants' search crawlers now get the home page itself
  rather than the plain-text quickstart. See [start](./start).
- **Listing sandboxes is faster.** `GET /v1/sandboxes` and every SDK's
  list answer a page about three times sooner in any account with more than
  one sandbox, and a list of only running sandboxes in an account with
  thousands of stopped ones answers in milliseconds where it read all of them.
  `GET /v1/usage` answers two to three times sooner in large accounts, and
  `GET /v1/me` no longer waits on a usage read. The answers are the same. See
  [Sandboxes](./api#sandboxes) and [Account](./api#account).
- **Refer someone, not only a company.** The referral in Billing and Home
  now reads "Refer someone", and your billing history names someone you
  referred rather than a company: anyone you bring to Runtime counts. See
  [referrals](./referrals).
- **Set up Runtime with one line for your coding agent.** A new account's
  Home now opens on the line to paste into Claude Code, Codex or Cursor,
  shown as it will be pasted, with one Copy button; starting a sandbox in the
  browser comes next, and the key and install steps by hand are folded below.
  The line is shorter everywhere: "Move this project to Runtime Cloud: read
  https://withruntime.com/llms.txt and follow it." See
  [Get started](./start).
- **Free hours card fits on every page.** The "100 free hours" card at the
  end of the changelog, pricing and about pages now holds its whole title on
  wide screens, where its second line ran past the card's edges. See
  [pricing](./pricing).
- **MCP server instructions on first connect.** When `npx withruntime mcp`
  connects through `runtime_connect`, its answer now carries Runtime's full
  instructions (limits, cleanup, safe retries), which an agent's first session
  never saw before. If your client does not show the new tools, restart it:
  the connection is saved. See [MCP](./mcp).
- **`sandboxes run` deletes its sandbox.** `npx withruntime sandboxes run`
  now deletes the sandbox when the command ends, so
  nothing is left billing for disk and an account without credit no longer
  reaches its 10 kept sandboxes after ten runs. `--keep` still keeps it. See
  [CLI](./cli).
- **Volume restored from a backup stays put.** A volume made from a backup
  can no longer be removed after it is ready by a restore attempt that
  finished late, and the nightly backups keep earlier copies whenever a night
  could not read the data they protect. See
  [Volume backups](./storage#volume-backups).
- **A paused sandbox wakes when its server can't take it.** A wake whose
  sandbox's own server is full, out of service or lost now comes back on
  another server from the sandbox's saved copy, files and memory as they were,
  where it was refused `no_capacity`. Each server is checked for this after
  every release before it takes another server's sandboxes. See
  [pause, wake, extend](./python#pause-wake-extend).
- **Free account limits for backups, feedback and support.** An account
  without credit keeps a volume backup at most seven days, like its snapshots
  and paused sandboxes; one that has never added credit files 5 feedback
  reports and sends 40 support messages a day. Adding credit lifts them. See
  [volume backups](./storage) and
  [feedback and support](./feedback-and-support).
- **Preview token expiry explained.** Each create or read of a private
  preview signs its own token with its own `tokenExpiresAt`, so a list after a
  week-long create shows a different token that ends sooner; the token you
  already hold still works until its own expiry or a rotate. See
  [private preview tokens](./api#private-preview-tokens).
- **Sandbox environment changes and running programs.** `:update` changes a
  paused or stopped sandbox's `env` too, and a program already running keeps
  the values it started with, so restart it to pick up a change. See
  [Sandbox environment](./sandbox-environment).
- **Vouch for a scheduled job.** An owner or admin can now vouch for a job on
  its page in the console. Each run's identity token then names the job, its
  version, who made it and who vouched for it, so your own API can accept a
  job's call only when a person stood behind exactly what it runs. Any change
  to the job takes the vouch off. See
  [identity tokens](./identity-tokens#what-a-token-says).
- **Code for the newest rival SDKs runs on Runtime.** The drop-ins follow
  Daytona 0.224.1, E2B 2.56, Blaxel 0.3.30 (Python 0.4.18), Freestyle 0.2.20,
  Modal 0.11.1 (Python 1.6.2), Prime Sandboxes 0.4.5 and Vercel Sandbox 3.8.0
  (Python `vercel-sandbox` 0.9.1 and `vercel` 0.12.0). New here: finding a
  stopped Modal sandbox by name (`includeTerminated`); Prime checkpoints, and
  creating a sandbox from one; input to a running Vercel command (`stdin`,
  `writeStdin`, `onStart`); Freestyle terminals that
  reconnect after a dropped connection, and `connectXterm`; Blaxel's error
  helpers, preview shorthand and `createIfExpired` tokens; a Prime background
  job that cannot start now fails instead of reading as running. Anything
  Runtime cannot do, such as another Daytona region or Prime LAN networks, is
  refused with a plain error rather than ignored. See
  [Migrate](./migrate).
- **A snapshot of a running sandbox answers sooner.** `sandbox.snapshot()` in
  every SDK now asks the server once, and the server pauses the sandbox for
  the capture and wakes it before answering, where the SDKs paused, captured
  and woke it in three calls of their own. A repeat snapshot of a 4 GiB
  sandbox took 1.19 s at the median instead of 1.96 s in Virginia. Snapshots
  and forks also see they are ready sooner on the server.
- **Images start where their base says.** A Dockerfile stage `FROM` an image
  now starts in that image's `WORKDIR`, as its `USER`, with its `CMD` and
  `ENTRYPOINT`, as on Docker: `FROM golang` builds in `/go`. An image built
  from `{image: "redis:7"}` starts redis. See
  [Custom images](./images#build-from-a-dockerfile).
- **Dockerfiles read more like Docker reads them.** An `ENV` now beats an
  `ARG` of the same name in `RUN`, an `ARG` with no value stays unset (so
  `${FOO:-default}` gives the default), quotes and `\$` keep `$` literal in
  `COPY` and `ARG`, and `COPY --chmod` takes symbolic modes such as `a+x`.
  `COPY --from` naming its own stage is refused with a clear message. See
  [Custom images](./images#build-from-a-dockerfile).
- **Containers from slow registries start.** Reading a container's image
  allows 5 seconds for each request rather than for the whole read, accepts
  `index.docker.io` and `registry.hub.docker.com` as Docker Hub, and refuses
  an image built only for arm64 at create instead of failing later.
- **Prove a volume backup restores.** The storage guide now says what a
  `ready` backup already proves, that only a restore checks every byte, and
  how to prove one: restore it, check it, and delete the restored volume,
  charged only while it exists. A restored volume counts toward your volume
  limit. See [volume backups](./storage#volume-backups).
- **Creates from a snapshot no longer fail because its servers are full.**
  When the servers keeping a disk snapshot have no room, the sandbox now
  starts on another server in the region, once a verified copy of the
  snapshot is brought there from its backup. That create takes longer (the
  copy arrives first) instead of failing with `no_capacity`. Each such
  create leaves the snapshot on one more server, so a snapshot used often
  is kept on more servers as it is used.
- **Dockerfile files are owned as Docker owns them.** `COPY` and `ADD` now
  write files owned by root unless `--chown` says otherwise, whatever the
  `USER`, and a `WORKDIR` that does not exist yet is made for the current
  `USER`. So `USER node`, `WORKDIR /app`, `COPY . .`, `RUN npm ci` builds, where
  it failed on an `/app` only root could write. See
  [Build from a Dockerfile](./images#build-from-a-dockerfile).
- **Paid accounts get 1 TiB of sandbox disk.** An account with credit now has
  1 TiB of disk across its sandboxes, up from 400 GiB. One sandbox is still
  at most 400 GiB. See [Limits](./limits).
- **An account without credit keeps 5 sandboxes.** Running, paused or
  stopped, down from 10; each is still up to 10 GiB of disk. A sandbox you
  already keep is never cut off: waking or deleting one is never refused, and
  an account keeping more than 5 makes new ones once it is under. Adding
  credit lifts the limit.
- **Morph Cloud code runs on Runtime after one import.** Change
  `from "morphcloud"` to `from "withruntime/morph"` (`withruntime` 0.16.0):
  snapshots and their cached `setup` steps, instances, `branch`, pause and
  resume, `exec` and HTTP services run as Runtime sandboxes, snapshots and
  previews. See [Switch to Runtime](./migrate).
- **Morph Cloud's Python code runs on Runtime too.** Change `morphcloud` to
  `withruntime.morph` in the imports (`withruntime` 0.14.0 on PyPI):
  `from withruntime.morph import MorphCloudClient`. The same calls work, with
  their `a`-prefixed async twins and Morph's `build` and cached `setup` chains.
- **A reference on the page that did not load.** When a page of your account
  fails to load, it now shows a reference number. Quote it when you ask for
  help, and support can find exactly what went wrong with that page. See
  [Feedback and support](./feedback-and-support).

## 14 October 2026

- **Making /workspace needs permission to write files.** `files:mkdir` on
  `/` or `/workspace` now needs a key that may write files, as on any other
  path, and a key that may only read is refused. If the path exists but is
  not a folder, it answers 409 `not_a_directory` instead of success. See
  [Files](./api#files).
- **A public preview's warning cannot be skipped from a link.** In browsers
  that do not say where a click came from, only the warning's own Continue
  button now takes a visitor past it. A link sent by someone else shows the
  warning first. See [Networking](./networking).
- **Image rebuilds get the newest base image.** A build `FROM python:3.12-slim`
  or `:latest` now starts from the image the tag names today, as
  `docker buildx build` does, instead of an earlier pull kept from a past
  build. `cache: false` (`--no-cache`) now always builds every step afresh.
  See [Faster rebuilds](./images#faster-rebuilds).
- **Comparison tables that read cleanly.** The tables on the comparison,
  blog and how-to pages are soft rounded cards again, with room around the
  text instead of a hard square outline, and Runtime's row in a price ranking
  is one even band. See [compare sandboxes](https://withruntime.com/compare).
- **Best sandbox for AI agents, compared.** A new page ranks every sandbox
  provider by the cost of the same agent job, sets their published start
  times beside ours, and names which one fits each need, GPUs and
  self-hosting included. The price index now opens on which agent sandbox is
  cheapest. See
  [Best sandbox for AI agents](https://withruntime.com/compare/best-sandbox-for-ai-agents).
- **Faster first paint on the website.** Guides, blog posts, comparisons,
  pricing and the home page now load only their own styles: a glossary page
  fetches 30 KB of them instead of 67 KB, the home page 25 KB instead of 61 KB.
- **A worker's own workers share its daily limit.** When a key with a daily
  limit makes keys, the limits of every live key under it, at any depth, now
  add up to at most its own, so a worker cannot multiply its cap by making
  workers of its own. Keys are made at most 8 deep, and a key in a
  compartment makes no keys. See [Run a swarm](./teams#run-a-swarm).
- **A wallet account's key is never lost to a failed save.** If
  `runtime_wallet_claim` cannot save the key it was just issued (a read-only
  config directory, say), it still connects and shows the key once, to keep.
- **A command on a paused sandbox starts sooner.** An exec, a file call or
  any other command sent to a paused sandbox with `autoWake` wakes it with two
  fewer steps before the command runs. A key that may run commands but not
  read the sandbox is still refused before anything wakes, as before. See
  [Wake on request](./javascript#wake-on-request).
- **Cost breakdowns you can read at a glance.** The worked sums on the
  comparison, blog and use-case pages, such as "Cost for the same job", now
  show as one card per provider with its total and a bar to scale, instead of
  text in a code box. The blog, how-to guides, glossary, pricing and changelog
  pages share the cleaner look of the sandbox page. Each page's Markdown is
  unchanged for agents. See [Runtime vs E2B](./e2b-alternative#cost-for-the-same-job).
- **MCP servers at a URL that never expires.** `public: true` on
  `sbx.mcp.start` (`public=True` in Python, `Public` in Go, `--public` in the
  CLI, `public` on `POST /v1/sandboxes/{id}/mcp` and the `runtime_sandboxes_mcp`
  tool) serves the sandbox's MCP servers at a public preview: URLs with no
  link token, so an agent is set up with them once. The `Authorization`
  header still guards every request, and stays the same at every start,
  after a restart too, until you stop the gateway. An idle sandbox pauses with
  its servers in memory and wakes on the next request. Reading the gateway
  no longer turns a public preview of its port back to private. Needs a
  kept top-up. See [MCP servers](./javascript#a-url-to-configure-an-agent-with-once).
- **The console stays fast for busy accounts.** Home, Usage & billing, a
  sandbox's own page and Networking no longer slow down as an account's
  history grows: on an account with 100,000 sandboxes in a month, Home opens
  in under a tenth of a second instead of 1.5 s, and Usage & billing in
  0.15 s instead of 1.2 s. Older pages of the audit log, and the log filtered
  to one kind of change, open as fast as its first page. See
  [the audit log](./teams#audit-log).
- **Your account's limits, from the API.** `GET /v1/limits` (and
  `runtime.limits.get()`, and the `runtime_limits_get` tool) now lists every
  limit the account is held to with what it uses of each now, the numbers a
  create past one is refused `quota_exceeded` by: sandboxes at once, their
  vCPUs and memory, volumes and the rest. An agent can watch them and hold
  back before it is refused. See [Limits](./limits).
- **Agent-only wallet accounts top up, watch their credit and recover a lost
  key.** On an account an agent opened with a wallet and no person pays for,
  an out-of-credit answer now tells the agent to add credit itself with
  `npx withruntime billing topup <usd>` (`details.addCredit.by` is `agent`).
  `GET /v1/limits` gains `credit`: the balance, the daily pace, the days it
  lasts and whether it is `ok`, `low` or `empty`. Webhooks can subscribe to
  `credit.low` and `credit.empty`. A lost key is replaced with the claim code
  (`runtime billing claim <code> --new-key`), which revokes every other key; at
  most 3 times a day, logged in the audit log, until a person takes the
  account over. See [pay with stablecoins](./pricing#pay-with-stablecoins),
  [limits](./api#limits) and [events](./observability#events).
- **Swarm worker keys stay inside their own sandboxes.** A key made by
  another key with reach `agent` now gets `403 forbidden` on the account's own
  settings, whatever its person's role: closing the account, webhooks,
  telemetry exports, the audit log, credit and billing, secrets, domains and
  networks. It still runs sandboxes, reads its own usage and makes its own
  keys; an account-wide one keeps everything. See
  [Run a swarm](./teams#run-a-swarm).
- **Code interpreter cells and terminals show in a sandbox's commands.** A
  sandbox driven only by E2B's `runCode` / `run_code` listed no commands at
  all. Each cell is now kept as its language (`python-cell · exit 1 · 2 s` for
  a cell that raised), and a terminal as its shell; never the code or what is
  typed. See [observability](./observability#commands).
- **`mkdir -p /workspace` through the files API is success.** `files:mkdir`
  (and the files tool's mkdir) on `/workspace` or `/` answered 400 "Refusing
  the root of a tree"; it now answers `created: false`, as for any folder that
  already exists. And `GET /v1/usage?key=` with something that is not a key's
  id answers 400 `invalid_request` rather than 500.
- **Wallet accounts and the welcome match.** An account an agent opened with a
  wallet, and that no person has taken over, no longer earns the welcome match
  or a referral reward on its payments. Once a person takes it over, its later
  payments earn them as usual. See
  [paying with stablecoins](./pricing#pay-with-stablecoins).
- **A key makes more keys over the API, with no browser.** For agent swarms and
  for accounts opened with a wallet. `POST /v1/keys`, `GET /v1/keys` and
  `DELETE /v1/keys/{id}`, `runtime.keys.create/list/revoke/usage` in the
  TypeScript SDK, and `runtime keys create --name worker-1 --daily-limit 5`
  with a key on the machine (`--browser` keeps the browser approval). New:
  `runtime keys ls`, `runtime keys usage <keyId>`, `runtime keys revoke <keyId>`,
  and `GET /v1/usage?key=`. Each key is its own agent, a new key never has more
  than its maker, and the daily limits of the keys a key made add up to at most
  its own. See [run a swarm](./teams#run-a-swarm).
- **The Python, Go, Java and Ruby SDKs no longer take a failure or a cut
  stream for a success.** A call that runs longer than 90 seconds gets its
  status early and its answer after; when that answer is an error (a create
  whose host was lost, say), Go, Java and Ruby now raise it, as JavaScript and
  Python did, instead of returning an empty result. A file read in Go, Java or
  Ruby is checked against the length and SHA-256 the API sends with it, read
  again if it came short, and refused rather than returned short. In Python's
  synchronous client, an event stream (a watch, a log follow) whose connection
  closed part way raises instead of ending as if it had finished. Each arrives
  with that SDK's next release.
- **Free usage is for trying Runtime, and a lower limit applies to every
  account at once.** An account that has never paid gets its 100 free hours
  (100 GiB-hours of memory and 25 vCPU-hours of active CPU) once, across the
  30 days from its opening, and then nothing until it adds credit. An account
  that has paid gets them every month, as before. Saved copies (10 GB) and
  disks (5 GB) stay monthly for every account, and the startup hours are
  unchanged. `GET /v1/usage` shows `freeUntil` on each of `allowances`: when
  the free machine time ends, or null once the account has paid. Usage &
  billing and the sign-in and offer pages say it the same way.
- **Without credit, fewer sandboxes at once, and a few new limits.** Four
  sandboxes run at once, not eight, with at most 8 vCPU and 16 GiB in all,
  not 16 and 32. An account keeps at most 10 sandboxes, running, paused or
  stopped (a create past it is refused with `no_credit_kept_limit`, 409), and
  makes at most 50 a day, in any 24 hours (`no_credit_daily_limit`, 429).
  Waking, resuming or deleting a sandbox you already keep is never refused.
  Scheduled jobs do not run without credit: a job waits with `blockedReason`
  `credits` until the account holds credit. Adding credit lifts all of these.
  Public previews and ports other than 80 and 443 were already for paid
  accounts only. The Python SDK's Inspect integration defaults to four
  sandboxes at a time.
- **Every limit is published, and an account with credit is charged, not
  capped.** With credit, an account keeps up to 10,000 volumes, snapshots,
  images, volume backups, jobs and secrets (5 volumes before), with no limit
  on the GBs of volumes and images, which its credit pays for. A
  `quota_exceeded` now names the limit and its number in its message and in
  `details` (`limit`, `max`, `raise`), including the vCPU, memory and disk
  limits that said only "quota exceeded". The [limits](./limits) guide lists
  every one, and the console's Limits page shows each with what the account
  uses.
- **A stop or delete never loses a snapshot or a sandbox's disk.** Stopping
  or deleting a sandbox while a snapshot of it is still being taken is now
  refused with `snapshot_in_progress` (409) and nothing changes, instead of
  destroying the sandbox and failing the snapshot; wait until the snapshot is
  `ready` and stop it again (see [troubleshooting](./troubleshooting)). A stop
  that comes while a paused sandbox is waking from its saved copy, or is still
  being copied to another host, or just after that copy was restored, keeps
  the copy and the disk. A resize of a sandbox that only its saved copy holds
  wakes it from that copy. A volume lost with its host keeps its newest ready
  backup past its retention, so the backup the error tells you to restore from
  is still there.
- **An agent with no shell can open and pay for an account over MCP.** Two new
  tools, `runtime_wallet_open` and `runtime_wallet_claim` (also at
  `/mcp?signup=wallet`), open an account paid in USDC: the first answers with
  an address per network, the exact amount and a claim code; the second
  connects once the payment lands. There is no free trial on this path. The
  Go, Ruby and Java SDKs gain the wallet calls, and `runtime_connect` picks up a key saved after the MCP server
  started. See [pay with stablecoins](./pricing#pay-with-stablecoins).
- **No paid-or-trial choice in the SDKs.** Free usage comes first, then
  credit, and there is nothing to choose, so the examples and options that
  showed `funding` are gone and Harbor and Inspect tell an account without
  credit to add credit for a bigger size. The option is still accepted
  (deprecated in Go and Java), so existing code runs.
- **A preview, port or private stream keeps going when you extend the time
  limit.** A long download through a private preview was cut at the end of
  the limit it began under even though you had extended the sandbox, and it
  now carries on into the new limit. A limit that really ends still cuts it.
- **Pages in the console answer faster.** Every page waits less for the
  sign-in check and makes fewer database round trips, a click from page to
  page no longer waits a fixed 0.3 seconds, and a new account's Home is
  built once, not twice.
- **A slow command start no longer holds up the sandbox's other calls.**
  Starting a command no longer blocks listing processes, reading or writing
  files and killing processes while it waits for a slot. A command that
  waits in line longer than 6 seconds is refused as busy, which is safe to
  retry, instead of ending with an unknown outcome.
- **A short database outage no longer fails a start, stop, wake or delete.**
  A broken database connection no longer ends one of these as
  `operation_failed`, and after a database restart the first request on a
  reconnected connection is answered instead of failing with the old
  session's error.
- **A member an owner removed stays removed.** If an owner removes someone,
  or they leave, after your directory had deactivated and an invitation had
  brought them back, [single sign-on](./single-sign-on) directory sync no
  longer restores their membership when it turns them on again.
- **A wallet top-up that never reached the payment provider says so.** A
  claim whose top-up was never created no longer shows a pay-by time; it
  says to send the top-up again with the claim code.

## 13 October 2026

- **A secret can go to only some of your sandboxes.** A secret reached every
  sandbox of the account; it can now name the sandboxes that get it, by
  label or by id. `runtime secrets set NAME --host api.example.com
--only-label role=hub` (once per selector) or `--only-sandbox <id>` gives it
  to those alone, `--all-sandboxes` gives it to every sandbox again, and
  `runtime secrets scope NAME` changes who gets an existing secret without
  its value. The API takes `only` (and `PUT /v1/egress-secrets/{name}/sandboxes`),
  the SDKs `only` and `secrets.scope`, and MCP the same `only`. A new value
  keeps the scope it had. Settings → Secrets sets the scope and shows which
  sandboxes each secret reaches, and `GET /v1/egress-secrets` gives each
  scoped secret's `reaches`. See
  [secrets sandboxes never see](./security#secrets-sandboxes-never-see).
- **Every account page is drawn from one kit.** Home, Usage & billing,
  Sandboxes, Jobs, Secrets, Networking, Settings, Support and the rest are
  one column 1040px wide with the same spacing, bigger buttons, 13px text at
  AA contrast or better, and one Select, DatePicker and Input everywhere.
  Each page's loading outline is measured from the page that follows it, so
  nothing moves when it arrives.
- **Identity tokens work in a scheduled job's run.** `identity_token()` in a
  [job](./jobs) answered `identity_refused` (403) because the run read a
  token left from the sandbox's warm start. The command now gets the
  sandbox's current identity-token request token, as a command in the
  sandbox does. See [identity tokens](./identity-tokens).
- **Commands run in a sandbox at its open-connection limit.** A sandbox
  holding all of its open connections (a crawler, a server's keep-alives) had
  every command answered 503 "environment unavailable" until one closed. Its
  environment read now goes through, and everything else over the limit is
  still refused.
- **A terminal or tunnel cut by its sandbox ending says so.** When a sandbox's
  stop, pause, time limit or delete closes a terminal or a tunnel, you now
  get that reason, not `503 guest_failed`.
- **A full house names what it is waiting for.** A create from a snapshot,
  image or volume starts only on the servers that keep it. When those are
  full it answers `no_capacity` (409) saying so, with `details.keptOn` set to
  `snapshot`, `image` or `volume`, instead of saying the whole region is
  full; create without it to start anywhere in the region.
- **A custom image's creates start faster.** A create from a custom image
  goes first to a host that already ran the image at the same vCPU, memory and
  disk, where it restores from a start template instead of booting cold.
- **An email before your sandboxes are deleted.** Every account's owners are
  emailed the day-before deletion warning (it was sent only to pilots), with
  how many sandboxes and other items go and when, and a sandbox is told its
  retention started once, not again beside the warning. On an account without credit, adding credit before the deadline keeps them.
- **Deleting a sandbox the host had already removed completes.** A delete the
  host had carried out is answered as done, no longer "Guest not found" for
  good.
- **The support chat shows what it is doing.** Until the answer arrives, the
  chat says "Searching the docs…" and the like instead of bare dots. Account
  → Support is one chat window, and a short conversation lets the page scroll.
- **A quieter free hours card.** The card on Usage & billing is small: it says
  the hours are included every month for paying accounts, shows one plain
  line once they are used, and is never red.
- **Pasted secrets and plural CLI options work.** `runtime secrets set` drops
  the line breaks, bracketed-paste markers and outer spaces a pasted token
  carries, from standard input and the hidden prompt alike. `--hosts a,b` is
  `--host a --host b`, and likewise for `--allow`, `--deny` and `--connect`;
  any other plural is still refused as a typo.
- **A full snapshot count names its limit.** A snapshot refused at the
  account's count says which limit it is and that every key's snapshots
  count. See [limits](./limits).

## 12 October 2026

- **A new look for the console.** Usage & billing, Home, Settings, Close
  account, Sandboxes, Jobs, Secrets, Agents & API keys, Webhooks, Networking
  and two-step sign-in are rebuilt from one set of pieces: a near-white ground,
  white cards, pill controls and Inter. Usage & billing leads with the balance
  and the amounts to add, with auto top-up and the referral as rows, the month
  beside its products, limits as meters and the statement as a ledger. Home
  opens with one line, "All healthy." or "One thing needs you."
- **A scheduled job whose sandbox was deleted before it started runs
  again.** A run whose sandbox was deleted under it stayed "provisioning" for
  good, and a job runs once at a time, so the job never ran again. The run
  now ends as unknown (`compute_stopped`) and the next occurrence runs.
- **100 free hours every month.** Every account's free usage is now told
  in one figure: 100 free hours a month of a 1 GB machine, which is 100
  GiB-hours of memory and 25 vCPU-hours of active CPU (about 25 hours of a
  2 vCPU, 4 GB sandbox at half busy). Saved copies (10 GB) and disks (5 GB)
  are unchanged. It applies to every account.
  Usage & billing now
  shows the free hours left this month, with the memory and active CPU behind
  them, and the guides call it free usage throughout.
- **The Blaxel and Daytona drop-ins honour the create options they used to
  drop.** In `withruntime.blaxel`, `SandboxInstance.create(config, timeout=N)`
  (1 to 50 seconds, as Blaxel 0.4.13) deletes a sandbox not running in time
  and raises `SandboxCreationTimeoutError`, and `safe=True` checks the new
  sandbox answers. In `withruntime.daytona`, `create(timeout=...)` bounds the
  create, `queue_timeout` is how many minutes it waits for room (then
  `DaytonaQueueTimeoutError`), `pip_install_from_requirements` takes pip's
  index and link options, and `kvm`, a `dockerfile_commands` build context
  and `wait_for_resize_complete` are refused by name instead of ignored.
- **A busy sandbox's refusal keeps its own error.** When a call waits to
  retry `guest_busy` or a full house and its deadline ends the wait, the
  JavaScript SDK now throws that refusal, as it judged it would, instead of
  "The call was cancelled or ran past its deadline". Your own cancel still
  ends the call as a cancel.
- **Why a secret's placeholder arrived unchanged.** The troubleshooting
  guide now covers a rule's near-miss (`/ingest` is not `/ingest/`), paths
  that read two ways, clients that ignore `HTTPS_PROXY`, and what the
  sandbox's own `NO_PROXY` lists; the security guide links to it.
- **JavaScript cells with `await` keep their variables.** A `const`, `let`,
  `class` or function declared in a JavaScript or TypeScript interpreter cell
  that uses top-level `await` is there in the next cell, as in every other
  cell. Before, it ended with its cell and the next one read
  `a is not defined`. A cell run again may declare its `const` and `let`
  again, as in a browser console. See
  [code interpreter](./javascript#code-interpreter).
- **A paused sandbox that will not wake tells you what to do.** When
  `autoWake` is off, a call to a paused sandbox answers `sandbox_paused` (409)
  with "…and autoWake is off, so requests do not wake it: call wake, or update
  it with autoWake: true." The Go KeepAlive example no longer turns `autoWake`
  off, since it is on by default
  ([the API reference](./api)).
- **Clear words for an image limit below the base.** A build from Runtime's
  base (`FROM runtime`, or a recipe without a base) with a `build.maxImageMiB`
  under 3,072 MiB, the base's own size, is now refused when you
  send it, with the smallest value that works, instead of failing after it was
  queued.
- **Know when your usage export is final.** Every page of
  `GET /v1/usage/export` now carries `finalThrough`: no row settled before it
  can still appear or change, so a range ending at or before it is complete
  for good. Each row also says `final: true` once its sandbox or volume is
  deleted and every charge it will ever have is in the export. A volume's
  backups bill until their retention ends, so they are not final when the
  volume is. The CSV gains a last column, `final`. See
  [export settled usage](./api#export-settled-usage).
- **Compartments.** Wall a group of keys off from the rest of your account:
  choose **One compartment** when you make a key at API keys. A key in a
  compartment sees and uses only the sandboxes, snapshots, images, volumes,
  previews, ports and jobs its compartment's keys made; everything else answers
  "not found", and no other key reaches in except an account-wide one. Give one
  to each customer of your platform, or to an agent whose sandboxes nobody
  else may touch. Each compartment has its own sandbox names, so every
  customer can have its own `main` ([compartments](./security#compartments)).
- **An email when your credit is in.** Each time you buy credit, Runtime emails
  you once it lands: what you added, the welcome or referral match it earned,
  and your balance now. An automatic top-up emails everyone on the account who
  may pay. See [pricing](./pricing).
- **Delete sandboxes by label.** `runtime sandboxes rm --label team=search`,
  `sandboxes.deleteAll({ labels })` in JavaScript and
  `sandboxes.delete_all(labels=...)` in Python delete for good every sandbox
  with all the labels given, stopped ones too, the way stop by label already
  stops them. Each returns what it deleted and what failed. In the CLI's and
  each SDK's next release. See [the CLI](./cli).
- **Wallet top-ups say when they are off.** `POST /api/wallet/topups` answers
  404 with code `not_available` while wallet top-ups are switched off, instead
  of 503, so a client can tell an option not offered from an outage.
- **Storage reaches your usage export an hour sooner.** Each hour of storage (a
  paused sandbox's memory and disk, a stopped sandbox's disk, images,
  snapshots, volumes and volume backups) now settles within a minute of its
  end, usually seconds, instead of 58 minutes after it. Nothing is charged
  differently. See [export settled usage](./api#export-settled-usage).
- **A code for a new account by email.** Opening an account by email now asks
  for the six-digit code the email carries, typed on the page where you asked
  for it, instead of a link click. An address with an account gets one email
  with its link and a code, so signing in is still one click. Every address
  sees the same page, "check your email", so the page never says whether an
  address has an account. New accounts by email are not opened from
  data-centre or VPN networks, and no email comes: use Google there, or write
  to support@withruntime.com. An address gets at most five sign-in emails an
  hour, and ten wrong code tries a day; past that, its email has only the
  link.
- **A paused sandbox tells you how to reach it.** When a sandbox has paused
  and its autoWake is off, a request to it now answers `409 sandbox_paused`
  with what to do: call wake, or update the sandbox with `autoWake: true`. The
  Go keep-alive example no longer turns autoWake off, so a sandbox copied from
  it wakes on its next request. See [troubleshooting](./troubleshooting).

## 11 October 2026

- **Faster retries when a server cannot be reached.** When a connection to the
  API is refused before your request leaves, the SDKs (JavaScript, Python, Go,
  Java and Ruby) send it again at once instead of after a quarter of a second,
  so a server that just went away costs your call almost nothing. A request
  that may have reached a server waits and retries under its idempotency key as
  before, so nothing runs twice. In each SDK's next release.

## 10 October 2026

- **Auto top-up.** Usage & billing can add credit from a saved card when your
  balance falls below a line you pick, up to a monthly most you set. Each
  automatic top-up earns 5% more as credit, and while it is on your
  account runs 200 sandboxes at once instead of
  100. A declined charge turns it off and never stops a running
  sandbox. Also `runtime billing auto-top-up`, the SDKs and
  `/v1/billing/auto-top-up`. See [auto top-up](./pricing#auto-top-up).
- **Jobs in the console.** A Jobs page lists every scheduled job: its schedule
  in words, its size, its last run and how it ended, its next run and this
  month's cost, with what needs you first. A job's page shows each run's state,
  start, length, exit code, cost and output, and pauses, resumes or cancels the
  job. See [scheduled jobs](./jobs).
- **Run a job now, or change its schedule.** Run now starts one run at once,
  beside the job's schedule; a paused job runs once and stays paused. Change
  schedule moves the next run to the new schedule's next time, and a run going
  finishes as it started. On the job's page, `runtime jobs trigger` and
  `runtime jobs reschedule`, the SDKs, MCP and `/v1/jobs/{id}:trigger` and
  `:reschedule`. See [jobs](./jobs).
- **Secrets in the console.** Settings → Secrets lists every secret your
  sandboxes and jobs use: the hosts each may reach, where its value goes, its
  rules, whether jobs have a copy, and who added and last changed it. Add a
  secret, replace its value or delete it there, as with `runtime secrets`.
  Values are never shown, there or anywhere. See
  [secrets sandboxes never see](./security#secrets-sandboxes-never-see).
- **Referrals pay on every payment, and for a year.** When a company signs up
  with your link, every credit it adds in its first 30 days is
  matched for both of you, up to $1,000 for each company, not only
  its first top-up. Then, for 12 months, you earn
  10% of what it spends from credit it paid for, up to
  $50,000 a year. Your link opens an invite page with the offer and a
  way to sign up. See [referrals](./referrals).
- **Creates stay fast with a thousand sandboxes.** A create now costs the same
  beside a thousand of your account's sandboxes as beside none: what it checks
  (sandboxes at once, quotas, a server's room) is kept as a running total
  instead of counted again at each create. On a test database with one account
  on one server, a create's database work beside 1,000 sandboxes went from 11
  to 85 ms to 6.3 to 9.7 ms, and 100 creates over 8 connections from 6 to
  11.5 s to 0.5 to 0.6 s. Every limit holds exactly as before.

## 9 October 2026

- **A limit without credit says plainly how to lift it.** Every refusal an
  account meets because it has not paid (sizes, sandboxes at once, builds,
  used-up included usage, public previews, open ports and the network
  features) now answers in one shape: what was refused and the limit, what to
  do now, and that the account's owner adds credit at Usage & billing, with
  the [welcome match](./pricing#welcome-match). `details.addCredit` says the
  same for code. See [responses and errors](./api#responses-and-errors).
- **Out-of-memory kills are reported.** When Linux ends a program because its
  sandbox ran out of memory, the command's result, its process and the
  stream's `exit` event carry `outOfMemory`: the code `out_of_memory`, how
  many processes were ended, the sandbox's `memoryMiB` and a hint (1,024 MiB or
  more, or a resize while paused). Each such command also sends the event
  `sandbox.out_of_memory` to your webhooks. See
  [when a program runs out of memory](./sandbox-environment#when-a-program-runs-out-of-memory).
- **Rebuilt custom images start warm from their first sandbox.** A new build of
  an image starts at the sizes your account's other images use on that
  server, before any sandbox asks for them; only your own account's images
  count. On a test server, a rebuilt image's first 1 vCPU, 512 MiB sandbox
  started in 120 to 139 ms, where it took 2,364 ms. See
  [fast starts](./images#fast-starts).
- **Custom images behave as on Docker in three more places.** A file the image
  puts in `/tmp` is there when a sandbox starts; a string command on an image
  without bash, such as Alpine or BusyBox, runs under `/bin/sh`; and
  `0.0.0.0` and the sandbox's own addresses skip the proxy, so a server you
  start in the sandbox answers from inside it. Existing images get this at
  their next cold start, with no rebuild. See [images](./images).
- **A secret goes only into a request header.** The proxy puts a secret's value
  in the header you set for it, or, with none set, in the credential headers
  (`Authorization`, `x-api-key`, `x-goog-api-key`, `api-key`, `xi-api-key`,
  `x-subscription-token` and `private-token`), never in a URL's path or query
  or another header, where the placeholder now goes out as it is. Stored
  OpenAI, Anthropic and Gemini keys keep working; code that put a placeholder
  in a URL should send it in a header. See
  [secrets sandboxes never see](./security#secrets-sandboxes-never-see).
- **A full disk answers `no_space` with how to free it.** A command, file
  write or other call that finds the sandbox's disk full answers 409
  `no_space`, with a hint: delete files, or create a sandbox with a larger
  `diskMiB`. The sandbox keeps taking commands, so the `rm` that frees space
  runs. See
  [troubleshooting](./troubleshooting#a-command-or-a-write-answers-no-space).

## 8 October 2026

- **Runtime for Startups now speaks of startup hours.** The machine time is
  10,000 startup hours, each an hour of a 2 vCPU, 4 GB sandbox. Storage kept free each month and the at-once limits
  are what Runtime for Startups includes; the amounts and terms are unchanged.
  `GET /v1/usage` now names its fields `startupIncluded` and `startupLimits`,
  with the same shapes.
  The old fields `pot` and `potLimits` still work for 30 days after this change ships, with a warning.
  See [included usage](./included-usage).
- **Sign up with Google in one click, and start a sandbox from Home.** "Start
  free, no card" opens Google sign-in at once, with no human check to wait for
  (a sign-in by email link still has one), and a new account's Home opens on
  a sandbox you start with one click, then the prompt to paste into your
  agent.

## 7 October 2026

- **Every credit you add in your first 30 days is matched, up to $1,000 in total.**
  The welcome match now covers each payment, not only the first: add $20 and
  then $500 and you get $520 more. Home, the billing page and `runtime switch`
  show how much of the $1,000 is used and left
  ([welcome match](./pricing#welcome-match)).
- **Your first top-up is matched, up to $1,000.** Every organization's
  first top-up made within 30 days of signing up is matched with
  credit, up to $1,000, with nothing to claim; Home and the billing
  page show the date it ends ([welcome match](./pricing#welcome-match)). A
  referral now matches up to $1,000 on each side
  ([referrals](./referrals)); the two never stack, and the larger applies.
- **Runtime for Startups gives a startup pot.** An accepted startup gets
  10,000 startup hours, each an hour of a 2 vCPU, 4 GB sandbox, given once and used within 12 months, with
  100 GB of saved copies and 100 GB of volumes
  kept free each month for those 12 months, 8 image builds
  at once, 100 sandboxes at once (up to 1,000 on
  request), and every paid feature. The pot is used after each month's included
  usage and before credit. Apply at
  [withruntime.com/startups](https://withruntime.com/startups).
- **One plural word names each product everywhere.** `/v1/sandboxes`,
  `runtime.sandboxes`, `runtime sandboxes` and `runtime_sandboxes`, and the
  same for every product; from SDK 0.12.0, each product can also be
  imported alone, as `withruntime/<product>`. The old words keep working for 30 days, and each use
  warns with the new name ([the API](./api)).

## 6 October 2026

- **A browser says when its sandbox is small for heavy apps.** `browser:start`
  now answers the sandbox's `memoryMiB` and, under 2 GiB, a `hint`: heavy apps
  such as Google Sheets, YouTube and StackBlitz need 2 GiB. Of 100 visits to
  ten heavy pages, 56 crashed for memory at 1 GiB, 20 at 1.5 GiB and none at
  2 GiB. 1 GiB still suits light pages and scraping, and the browser starts
  at any size. `runtime sandbox browser start` prints the hint.
- **Usage included every month, for every account, and jobs run on it.**
  Every account now gets 100 GiB-hours of machine memory, 25 vCPU-hours of
  active CPU, 10 GB of saved copies (snapshots, images,
  backups) and 5 GB of volumes each calendar month, enough for
  100 free hours of a 1 GB machine, with no card. It renews on the 1st (UTC), is used
  before credit and is never charged. New accounts get it in place of free
  hours; an account given free hours before 6 October keeps what is left of them,
  and has the included usage as well. `GET /v1/usage` lists each product's
  share under `allowances`, and `trial` gains `offer` and `renewsAt`. A
  scheduled job's runs spend it first, then credit, as a sandbox does; a run
  it cannot take, on an account without credit, waits with `blockedReason`
  `credits`. An account holds up to 1,000 jobs and 1,000
  secrets for jobs, where it held 50 and 200. Credit, bought or given, now
  opens every paid feature but three: a kept top-up is needed only for ports
  beyond 80 and 443, public previews, and private networks and Tailscale.
  Without credit, an account runs at most 8 vCPU and 16 GiB at once across
  its sandboxes and image builds, beside 2 vCPU and 4 GiB each and eight at
  once; past it, a create, wake or build is refused with 409
  `no_credit_total_limit`, whose message says what runs now. Seven codes are
  renamed, in the API, MCP, CLI and every SDK: `trial_busy` is now
  `no_credit_running_limit`, `trial_capacity` `no_credit_capacity_full`,
  `invalid_trial` `no_credit_size_limit`, `trial_domain_limit`
  `no_credit_domain_limit`, `trial_build_limit` `no_credit_build_limit`,
  `trial_exhausted` `included_usage_used_up` and `trial_unavailable`
  `included_usage_unavailable`; code that compares with an old name should
  compare with both until it updates. See [included usage](./included-usage)
  and [what a job costs](./jobs#what-it-costs).
- **Volume backups cost $0.02 per decimal GB per 30-day month.** They
  cost $0.012, which is below what keeping each backup in two
  places costs us: one copy beside the servers and one with a second provider.
  A backup made from now costs the new rate. One you already have keeps
  $0.012 until 7 November 2026, then costs the new rate
  too; a backup on the included usage stays free. Nothing else changes, and
  nothing is charged twice: a backup's hour that runs across the date is
  charged each part at its own rate. `GET /v1/usage` shows each backup's rate now under `rates`. See
  [pricing](./pricing).
- **Leaving a block deletes the sandbox it made.** From the next release of
  the TypeScript and Python SDKs, the end of an `await using` or `with` block
  deletes a sandbox that `Sandbox.create()` made there, where it used to stop
  it and keep its disk, which bills. Create it with `keep: true` (Python
  `keep=True`) to stop it instead, as before. A sandbox the block got with
  `get()`, or one `getOrCreate()` found already there, is still only stopped.
  The drop-ins keep each rival's own block exit: `withruntime/e2b` (Python)
  kills, `withruntime/vercel` stops in TypeScript and deletes in Python.

## 5 October 2026

- **A hundred sandboxes at once from the first top-up, and time limits up to
  24 hours.** A paid account runs 100 sandboxes at once as
  soon as its first top-up clears, where a new one ran 50 for its first week;
  only a disputed payment, a suspension or an abuse report holds an account to
  50. Paused and stopped sandboxes no longer count
  toward it, and an account keeps up to 1,000 in all. A time limit goes up to
  24 hours, where it stopped at one, and a sandbox it stops reads `stopReason`
  `time_limit` where it read `lease_expired`, in the API, events, webhooks and
  OpenTelemetry export: code that compares with `lease_expired` should compare
  with both. A sandbox's disk is at most 400 GiB, and a larger `diskMiB`
  is refused at once, naming the limit. See
  [how many at once](./pricing#how-many-at-once).
- **Downloads as fast as the server's link, and TCP ports five times
  faster.** A sandbox's downloads are no longer capped: each sandbox shares
  its server's link, and when several are busy a paid account gets four times
  the share of one without credit. Uploads stay limited, more strictly without
  credit (10 Mbit/s); paid uploads are 500 Mbit/s,
  200 Mbit/s after 10 GiB,
  500 GiB a day. A public TCP port now moves traffic at those
  paid figures, where it was 100 Mbit/s, 20 Mbit/s after 2 GiB and 50 GiB a
  day. See [sandbox environment](./sandbox-environment#the-network).
- **A snapshot of a running sandbox, in one call, at any size.** `POST
:snapshot` and `runtime_snapshot` (action `create`) take a running sandbox:
  they pause it, capture it and wake it, as a fork does, and answer once the
  capture is over. A sandbox with volumes is still refused. A copy of a disk
  snapshot takes the vCPUs, memory and disk you ask for, with a disk at least
  the saved one; a memory snapshot's copy is still the snapshot's size, and
  asking for another size answers `400`. Every sandbox can now pause, fork and
  be snapshotted, and every stop keeps the sandbox's files. See
  [snapshots and forks](./javascript#snapshots-and-forks).
- **What a sandbox serves is billed as outbound traffic, and persistence
  costs nothing extra.** For sandboxes created from today, what a sandbox
  sends back through a preview, a custom domain or a TCP port counts toward
  the account's 100 GiB a month free, then $0.02
  per GB, like what it sends over its own connections; what visitors send in
  stays free. While a sandbox made from today runs, its disk past the first
  10 GiB is billed at $0.08 per decimal
  GB per 30-day month, as a paused disk is; a disk of
  10 GiB or less never pays it. A `persistent` sandbox no
  longer pays $0.11 per GiB for a reserved disk all the time: its
  disk is billed as any sandbox's, and `persistent` means only "keep it
  running". See [pricing](./pricing).
- **More E2B code runs unchanged on `withruntime/e2b`.** In the JavaScript SDK
  0.11.2 and the Python SDK 0.11.1, a hundred commands at once run at once,
  `kill()` deletes the sandbox, a template name resolves with its team and
  tag, `commands.list` gives `cmd` and `args`, file entries carry permissions
  and owners, paths under `/home/user` come back as E2B gives them, and in
  Python every module path e2b 2.52.1 defines a public name in imports. See
  [migrating](./migrate).

## 4 October 2026

- **Paused sandboxes, kept disks and snapshots are kept while you have
  credit.** A paused sandbox, a stopped one's disk and a snapshot stay for as
  long as the account holds credit, with no 30-day or 7-day end, unless you set
  days with `:retention` or a snapshot's `retentionDays`. When credit runs out
  they are kept seven more days, with a notice first, and a top-up keeps them
  again. A sandbox paused on the trial is kept the same way once the account
  holds credit, and its storage is billed from the end of its seven free days.
  See [paused storage](./pricing#paused-storage).
- **The trial's hours, then credit, with nothing to choose.** A sandbox runs
  on the free trial's hours first and on prepaid credit after, automatically:
  at create, when a paused sandbox wakes, and while one runs, so a running
  trial sandbox carries on on credit instead of pausing when the hours run
  out. A request's `funding` is accepted and ignored, and code that sets it
  keeps working. Once an account holds credit, its sandboxes have paid limits
  and still spend the trial's hours first, and a trial sandbox that turns paid
  while it runs gets a paid sandbox's disk share at once and, if the trial
  had slowed it, its full cores back. See [included usage](./included-usage#after-you-add-credit).
- **Public previews follow a kept purchase.** A preview can be public once
  the account has bought credit; credit given alone does not open one. While
  an account is blocked, or every purchase it made is refunded in full, its
  public previews need the token like private ones, and they open to anyone
  again once it pays. See [security](./security).
- **A stop keeps the disk; only a delete removes it.** A stopped sandbox keeps
  its files for $0.08 per decimal GB per 30-day month, reads
  `diskKept: true` and starts again from them with `:restart`, its memory gone;
  deleting it removes them. `onLeaseEnd: "delete"` deletes a sandbox and its
  files when its time limit ends. A stop from a client released before today,
  or from raw HTTP without `x-runtime-client: http/2026-10-04`, keeps the disk
  free for three days, with one notice, and then deletes it. The console shows
  Restart and Delete on a stopped sandbox. See
  [paused storage](./pricing#paused-storage).
- **Ending a sandbox never waits for room.** A delete, stop or pause never
  fails for lack of room, even on a full server.

## 3 October 2026

- **A sandbox runs while it works.** There is no lease to manage any more: a
  sandbox has no time limit unless you set one, runs for as long as it is busy
  and pauses itself when idle, until you stop it or credit runs out. Nothing
  needs extending, and code that extends, sets `timeoutSeconds` or calls
  `keepAlive` keeps working: a time limit you set is still kept. `endsAt` says
  when a sandbox will stop or pause by itself, and is `null` when it never
  will. The E2B, Daytona, Vercel, Blaxel, Modal and Runloop adapters do the
  same when your code sets no timeout. See [the API](./api#sandboxes).
- **Runtime for Startups.** A venture-backed startup building with AI agents
  can apply at [withruntime.com/startups](https://withruntime.com/startups)
  for $5,000 of credit, added over 12 months (since 7 October 2026, the
  startup pot instead: 10,000 startup hours, each an hour of a 2 vCPU, 4 GB sandbox, given once, to use within 12 months).
  An accepted startup's account counts as paid from the day it is accepted.
  See [pricing](./pricing).
- **Two error codes are renamed.** A command whose timeout outlasts the
  sandbox's time limit or its funded time is refused with 409
  `time_limit_too_short`, and `details.secondsLeft` says how long is left:
  `time_limit_too_short` replaces `lease_too_short`. A host that is busy
  answers 503 `busy`, safe to retry with the same key: `busy` replaces
  `fence_conflict`. Code that matched the old names should match the new
  ones. See [errors](./api#responses-and-errors).
- **More requests at once for accounts with many sandboxes.** An organization
  may have 192 requests in flight, and two more for each sandbox it holds that
  is not stopped, up to 1,024, so every sandbox can stream a command and a
  watch at once. See [limits](./api#limits).

## 2 October 2026

- **Export settled usage for a chosen period.** `runtime usage export` and
  `/v1/usage/export` cover every visible product and resource with exact
  charges in the server's CSV. The CLI follows every page; API callers can
  follow the returned cursor. Pending holds stay separate.
  See [the API](./api#export-settled-usage).
- **Archive bytes and root-owned folders.** Native SDK archive helpers return
  or unpack tar bytes, support relative exclusions and explicitly requested
  root access through passwordless guest sudo. JavaScript request cancellation reaches
  transfers and local extraction. See [files](./api#files).
- **Current MCP groups give the replacement call.** Retired aliases fail with
  the canonical group and action before doing work. ChatGPT connections get
  scoped preview links without a persistent gateway credential. See [MCP](./mcp).
- **A browser for Playwright, Puppeteer and browser-use.** `sbx.browser.start()`
  runs Chromium in a sandbox and returns a private `cdpUrl` that
  `connectOverCDP` and `puppeteer.connect` take as it is. The browser is paid
  for as its sandbox and follows the sandbox's network rules, and the desktop
  opens pages in Chromium instead of Firefox. See
  [a browser over CDP](./javascript#a-browser-over-cdp).
- **More E2B, Daytona and Vercel Sandbox code runs unchanged.** The E2B adapter
  runs commands, terminals and files as another `user`, keeps a sandbox for up
  to 24 hours, filters, sorts and resumes `Sandbox.list`, returns a command's
  whole output and works with e2b 2.52.0. The Daytona adapter opens PTY
  sessions you can attach to again, drives the desktop through `computerUse`,
  runs as a `user` from your image, keeps a sandbox past an hour and filters
  `list`. The Vercel adapter creates users and groups, keeps a sandbox past an
  hour and pages `Sandbox.list` with cursors. See [migrating](./migrate).

## 1 October 2026

- **Build images and manage volumes in the console.** Build from a Dockerfile,
  a registry image or a package recipe, start a sandbox from an image version,
  manage tags, and create, back up or restore volumes. Spending and deletion
  ask first. See [images](./images) and [storage](./storage).
- **See API calls, CPU waiting and memory stalls in the console.** Usage &
  billing shows the account's API calls and errors by operation and exports
  settled usage as a CSV file; a sandbox's Activity tab charts CPU wait and
  memory stalls. See [observability](./observability#account-api-calls).
- **Request a feature from the console.** The Support page has a Request a
  feature button, which opens the feedback form on a feature request and asks
  what the feature would let you build. See
  [send feedback](./feedback-and-support#send-feedback).

## 30 September 2026

- **Environment variables for a whole sandbox.** Pass `env` at create, or
  change it later with an update, and every command, background process,
  terminal, SSH session and image start command gets those variables. Values
  are stored encrypted and never shown back. See [the API](./api).
- **Delete a sandbox for good.** `DELETE /v1/sandboxes/{id}`, `sbx.delete()`
  and `runtime sandbox rm` stop it, remove its disk and paused memory, revoke
  its previews and ports, and free its name. Usage and audit history stay.
- **Switch a sandbox to a new image and keep your work.** Switching keeps the
  sandbox's id, name, `/workspace`, volumes, environment, previews and ports;
  processes restart. See [images](./images).
- **Folders over plain HTTP.** Upload or download a whole folder of any size
  as a tar stream. The SDKs verify a downloaded archive before merging its
  folder contents; ordinary file downloads publish only complete files.
- **File changes to your webhooks.** A watch started with `webhook: true`
  sends `sandbox.files.changed` events, signed and retried like every webhook,
  without keeping the sandbox awake. See [observability](./observability).
- **Choose which sites may embed a preview.** `embedOrigins` lists them, and
  a private link's token is refused in any other site's frame.
- **Join your Tailscale network.** A paid sandbox can join your tailnet with
  an auth key stored as a secret. See [networking](./networking#your-tailscale-network).
- **Trial sandboxes keep going while they work.** A trial sandbox that is still
  busy when its lease ends gets its `timeoutSeconds` again, until the trial
  hours run out. See [included usage](./included-usage).

## 29 September 2026

- **Global installs run by name, and pnpm and yarn are ready.** In a new
  sandbox, `npm install -g` failed without `sudo`, and with it, or with
  `bun add -g`, the command installed but was not found. Now all three put
  their commands on `PATH`, so `npm install -g @anthropic-ai/claude-code`
  gives you `claude` straight away, and `pnpm` and `yarn` work through
  Corepack. See [the sandbox environment](./sandbox-environment#who-you-are).
- **Private previews work inside your own site's iframe.** Set an iframe's
  `src` to a preview's `urlWithToken`: the link keeps its token for your site
  alone, a paused sandbox shows its waking page in the frame and reloads by
  itself, and a public preview skips its warning page when it is framed. See
  [previews](./javascript).
- **Disk-only snapshots.** `mode: "disk"` on a snapshot keeps only the root
  filesystem, and a sandbox created from it boots fresh with your files and no
  saved processes. Memory snapshots stay the default. See [the API](./api).
- **Faster disks, shared fairly.** A sandbox's disk no longer has a fixed
  speed or a burst to run out. It shares its server's drives with the
  sandboxes beside it, in proportion: at least about 40 MB/s each way,
  and up to about 1 GB/s when its neighbours are quiet. A busy
  neighbour slows your writes a little rather than stalling them, and a pause
  stays quick on a busy server. See
  [the sandbox environment](./sandbox-environment#disk-cpu-and-memory).

## 28 September 2026

- **A console that reports your day.** Home, Sandboxes, Images, Volumes, Usage
  & billing and Agents & API keys each open on what needs you, then today in a
  line, two charts and the list. Sandboxes describes today's runs as a whole,
  hour by hour against yesterday, by who started them and by image, and its
  list opens on what runs now, with search over every day. A sandbox's page
  says how it ended and why, draws its life from start to stop and copies what
  happened for your agent. Usage & billing shows spend by who started it and
  each key's use against its daily limit. Agents & API keys, in Settings, tells
  agents connected from a tool apart from API keys. Today is counted in your
  browser's time zone.
- **Each sandbox's commands, on its page.** A sandbox's page lists the commands
  run in it, `pytest · exit 1 · 28 s`, with failures in red and a running one
  as running: on its Activity tab while it runs, and in its life once it ends.
  Runtime keeps each command's program name, exit code and duration for 14
  days, never its arguments. See [observability](./observability#commands).
- **Scheduled jobs.** Run a command in a fresh sandbox once at a time you
  choose or on a cron schedule in your timezone, with each run's exit code and
  output kept, retries when you ask for them, and pause, resume and cancel:
  `runtime job create nightly --cron "0 3 * * *" -- python3 report.py`,
  `runtime.jobs` in the SDKs, or the `runtime_job` MCP tool. Runs are paid
  sandboxes at the sandbox rates. See [scheduled jobs](./jobs).
- **Secrets for jobs.** `runtime secrets set NAME --jobs` keeps a copy a job
  puts into its run's environment (`--secret NAME` on `runtime job create`);
  with `--host` as well, one command stores it for sandboxes and jobs alike.
  The jobs copy can be rotated and read back; the sandboxes' copy still never
  can.
- **The region is now `us-east`.** It was `us-east-vin`, the name of one
  building; a region is named for its place, so more data centres nearby can
  join it. Every sandbox, snapshot, volume, image and job moved with it and
  keeps running. Asking for `us-east-vin` now answers `invalid_region` and
  names `us-east`, and an identity token's `region` claim reads `us-east`, so
  update a trust policy that names the old one. `withruntime` 0.8.4 sends
  `us-east` as a job's default region; update with `npm i withruntime@latest`
  or `pip install -U withruntime`. A job that names a region Runtime does not
  have is now refused when you create it, rather than waiting at every run.
- **A sandbox from a browser.** A sandbox session is a short-lived token your
  own web page uses to run commands, read and write files and reach previews in
  one sandbox, with no API key and no proxy of your own. It cannot stop, extend
  or change the sandbox, lasts 1 hour unless you ask for up to
  24 hours, can be revoked at once, and is answered only from the pages
  you list. `sbx.sessions.create({ origins })` makes one and
  `Sandbox.fromSession({ token, sandboxId })` uses it, from `withruntime`
  0.8.3; Blaxel's `sandbox.sessions` and `fromSession` now work in the
  drop-in. See [JavaScript](./javascript) and [Python](./python).
- **Passkeys.** Sign in with a passkey, with no email link and no code, or use
  one as the second step in place of an authenticator app's code. Add them
  under Settings → Two-step sign-in, beside the app or instead of it. See
  [two-step sign-in](./security#two-step-sign-in).
- **A Go SDK.** `go get withruntime.com/go` installs one Go client for every
  Runtime product, with a `context.Context` on every call and only the standard
  library underneath. See the [Go guide](./go).
- **A Ruby SDK.** `gem install withruntime` installs one Ruby client for every
  Runtime product, with only the standard library underneath. See the
  [Ruby guide](./ruby).
- **A Java SDK.** `com.withruntime:withruntime` on Maven Central is one Java
  client for every Runtime product, for Java 17 and later with nothing beyond
  the JDK. See the [Java guide](./java).
- **Faster starts, pauses and stops.** A new sandbox runs its first command
  331 ms after the create request at the median, down from 374 ms, and
  30 of 40 creates were running in under 200 ms. A pause answers in 165 ms,
  down from 226 ms, and a snapshot is ready in 3.27 s. On the server, without
  the network to Virginia, a pause answers in 81 ms, a wake in 75 ms and a stop
  in 37 ms; the [speed](./speed) page now shows those figures beside the ones
  from a laptop.
- **Persistence can be turned off, and a stopped persistent sandbox deleted.**
  `runtime sandbox update <id> --persistent off`, `update({ persistent: false })`
  or `:update` with `{"persistent": false}` now works as the guides said: a
  running sandbox stops paying for its disk at once, and a stopped one has its
  disk deleted and its name freed. A stopped persistent sandbox is listed by
  `runtime ls`, `runtime sandbox ls` and `GET /v1/sandboxes` with the live
  ones, since its disk is still kept and billed.
- **Agents can list images, volumes, volume backups and snapshots.** Over
  MCP, `runtime_image`, `runtime_volume`, `runtime_volume_backup` and
  `runtime_snapshot` take the action `list`, with the filters and pages of
  `GET /v1/images`, `/v1/volumes`, `/v1/volume-backups` and `/v1/snapshots`:
  `state`, `limit`, `cursor` from the last page's `nextCursor`, and `name`,
  or `volumeId` for backups and `name` and `sandboxId` for snapshots. Their
  `get` now reads one by `id`. See [MCP](./mcp).

## 27 September 2026

- **Two-step sign-in.** Turn on a code from an authenticator app after every
  sign-in, whichever way you sign in, under Settings → Two-step sign-in. Owners
  can require it of everyone in the account. See
  [two-step sign-in](./security#two-step-sign-in).
- **Faster wakes, snapshots and stops.** A paused sandbox runs its next
  command 588 ms after the call that wakes it at the median, down from 980 ms;
  a snapshot of a running sandbox is ready in 3.49 s, down from 6.54 s; a
  preview visit to a paused sandbox answers in 0.47 s, down from 0.77 s; and a
  stop answers the moment the sandbox is frozen. See [speed](./speed).
- **An uptime promise, paid automatically.** Paid accounts are promised
  99% API uptime every calendar month, measured by the outside
  check on the [status page](https://withruntime.com/status). A month below it
  gives every paid account 10% of that month's charges back as
  service credit in the first week of the next month, with no claim to file.
  The terms now give 30 days' emailed notice before we end an account without
  cause, and the liability floor is $1,000 instead of $100. See the
  [Uptime Promise](https://withruntime.com/legal/sla).
- **Idle sandboxes pause themselves.** A new sandbox pauses after 60 seconds
  with nothing happening in it, used or not (a `persistent` one only if you set
  an idle time), and pays only paused storage until
  the next request wakes it. A command or terminal still running, an open
  preview, port, SSH or tunnel connection, network traffic or CPU use keeps it
  awake. `idlePauseSeconds` now goes as low as 10 seconds, and 0 still turns it
  off. Sandboxes made before today keep their settings. See
  [pause when idle](./javascript#pause-when-idle).
- **Account-wide keys.** An owner or admin can make a key that sees and uses
  every sandbox, snapshot, image and volume in the account, whichever key made
  it, as a Blaxel workspace key does: choose **Everything in the account** at
  [API keys](https://withruntime.com/account/keys), switch an existing key from
  its row, or approve `runtime keys create --account-wide`. `getOrCreate` with
  a name another key holds then returns that sandbox. Keys made without it are
  unchanged. See [keys in a team](./teams#keys-in-a-team).
- **Switch from Blaxel in one import.** Code written for Blaxel's sandbox SDK
  runs on Runtime after changing `@blaxel/core` to `withruntime/blaxel`
  (`withruntime` 0.8.0), or in Python `blaxel.core` to `withruntime.blaxel`
  (0.8.1). Processes, files, previews, snapshots, forks and the code interpreter
  carry over, and standby becomes a pause that keeps memory and processes until
  the next call wakes it. A switch from Blaxel now earns the [switching
  credit](./pricing#welcome-match): run `runtime switch --from blaxel` before
  your first top-up, and that top-up is matched, up to $100. See [Runtime vs
  Blaxel](./blaxel-alternative).
- **Start a sandbox from the browser.** A new account's Home offers
  **Start a sandbox** beside the agent prompt. It opens the sandbox with a
  shell running in the page, runs on the free hours, and pauses after an idle
  minute. It acts as an agent named Console, one for each member, shown
  on the API keys page like any other. See [Get started](./start#run-your-first-sandbox).

## 26 September 2026

- **Single sign-on through OIDC.** Okta, Entra ID and Google Workspace
  connections by OIDC can be saved and used, as SAML ones could. See
  [single sign-on](./single-sign-on).
- **Paid means paid and kept.** Paid-only features follow a top-up that was not
  refunded or charged back in full, and a refund of a top-up that earned
  matching credit is smaller by any of that credit already spent. See
  [pricing](./pricing).
- **Faster starts, pauses and wakes.** Runtime now keeps machines of the most
  common sandbox shapes started ahead of time, and the servers keep memory
  ready for sandboxes that start or grow at once. Measured through the public
  API: a new sandbox runs its first Python command 374 ms after the create
  request at the median (495 ms p95, down from 981 ms), a pause takes 207 ms,
  a paused sandbox runs its next command 980 ms after the call that wakes it,
  and a preview visit to one answers in 0.77 s, down from 3.99 s. See
  [speed](./speed) for every figure and the samples.
- **Outbound traffic has a price.** Inbound traffic stays free, and each
  account's first 100 GiB out a month is free. Past it, what sandboxes send to
  the internet costs $0.02 per GB, fixed in each new sandbox's quote. Replies
  served through previews, custom domains and TCP ports, traffic to your own
  network, and trial sandboxes are not charged, and sandboxes made before today
  keep free traffic for their whole life. `GET /v1/usage` shows the month so
  far under `outbound`. See [pricing](./pricing#network-products).
- **Your account opens straight away.** A new account now lands in the full
  console. Home shows the setup prompt for your coding agent until the agent
  connects, and keys, billing and settings are in the menu from the first
  visit. Hide the prompt if you would rather start on your own.
- **A smaller MCP tool list.** An agent connected to Runtime's MCP server now
  reads 45 tools instead of 80, in 61,754 characters instead of 80,808, before
  its first call. A product's rarer verbs share one tool that takes an
  `action`: `runtime_volume_get` is now `runtime_volume` with
  `"action": "get"`. The first-session tools keep their names. The old names
  answered until the next release and said what replaced them; they were
  retired on 30 September 2026. See [renamed tools](./mcp#renamed-tools).

## 25 September 2026

- **Sandboxes from a custom image start in half a second.** Once an image is
  ready, a sandbox of the default size created from it starts from a started
  copy of the image: 481 ms from create to running at the median, from 3.7 s.
  See [fast starts](./images#fast-starts).
- **A new console.** Home shows what runs now, with live CPU and memory and
  what just happened across every product. New, or ⌘K, finds any page or
  resource and starts anything, showing the command that does it. A sandbox's
  page opens a terminal in the browser and has Pause, Wake, Snapshot, Fork and
  Stop; Images and Volumes have their own pages; Usage & billing says how long
  your credit lasts and charts daily spend by product. See
  [your account](./products#the-console).
- **A 100-hour free trial.** The free trial is now 100 hours of sandbox time,
  from 50, still with no card. Accounts already on the trial get the extra
  hours too; hours already used still count. See [included usage](./included-usage).
- **Sandboxes up to 16 vCPUs and 64 GiB.** A paid sandbox can now be as large
  as 16 vCPUs and 64 GiB of memory, at the same per-unit rates; a trial
  sandbox stays at 2 vCPU and 4 GiB. See [pricing](./pricing#how-many-at-once).
- **Faster network for paid sandboxes.** A paid sandbox moves up to 500 Mbit/s,
  200 Mbit/s sustained after its first 10 GiB, and 500 GiB a day. See
  [the sandbox environment](./sandbox-environment#the-network).
- **Outbound UDP to any port.** Paid sandboxes send UDP to any public address
  and port: HTTP/3 and QUIC, DNS to a resolver you choose, time sync, game and
  media servers, WireGuard and other VPN clients. Private addresses are
  refused, a sandbox sends at most 50,000 datagrams a second, and a flow that
  gets no answer after 256 datagrams is closed. Trial sandboxes send TCP only.
  See [networking](./networking#outbound-udp).
- **50 sandboxes at once for a new paid account, then 100.** A paid account
  runs up to 50 at once until 7 days after its first top-up clears or $50 of
  paid use has settled, whichever comes first, then 100. A paid account now
  runs 100 from its first top-up. See
  [pricing](./pricing#how-many-at-once).
- **Rules on a secret.** On a paid account, a secret can name the methods and
  paths it goes to, such as `GET /repos/acme/*`; a request no rule allows
  goes out without it. See [security](./security#secrets-sandboxes-never-see).
- **Your own upstream proxy.** A paid account can send its sandboxes' traffic,
  or only the hosts it names, through its own HTTP or HTTPS proxy, with one of
  its secrets as the proxy's password. Runtime's own checks still come first,
  and a proxy that fails refuses the connection rather than going direct. See
  [networking](./networking#your-own-upstream-proxy).
- **Custom images get `sudo`, `adduser` and `useradd`.** Every image Runtime
  builds, from a public image too, gives the sandbox user passwordless
  `sudo`, and the base image now carries `adduser` and `useradd`. A command in
  a sandbox from an image starts in the image's last `WORKDIR` (inside
  `/workspace`). Build logs number only the steps they log.
- **Close your account yourself.** An owner closes the account at
  [Close account](https://withruntime.com/account/close) or with
  `POST /v1/account:close`; `runtime account close` arrived in `withruntime` 0.7.0. See [teams](./teams).
- **Usage per run.** `GET /v1/usage` now gives each resource's name, start
  time, size and billed running time. In `withruntime` 0.7.0,
  `runtime usage --csv` exports one row per resource to the microdollar.

## 24 September 2026

- **Disk bursts.** A sandbox now writes at about 250 MB/s for up to 30 seconds
  before settling at about 40 MB/s, so installs, builds and test runs finish
  sooner. In a measurement a sandbox wrote at 200 MB/s instead of 38 (now up
  to about 1 GB/s, with no burst to run out). See
  [the sandbox environment](./sandbox-environment).
- **Volumes and snapshots are backed up off their server.** Every kept snapshot
  is copied off its server, encrypted with your organization's own key, and a
  volume is backed up daily and on request, then restored as a new volume
  (`runtime volume backup`, `runtime volume restore`). See
  [storage and backups](./storage).
- **Faster default starts.** In matched 20-run public-API measurements, the
  default 2 vCPU / 4 GiB memory / 4 GiB disk sandbox reached running in 207 ms median
  (620 ms p95), and took 351 ms median from create through the first Python result
  (815 ms p95). Both runs had zero errors. See [speed](./speed) for the before
  figures and scope; Python execution itself did not get faster.
- **Python data tools are ready.** The current default image includes NumPy,
  pandas and matplotlib. Imports and PNG plotting were checked in a live
  sandbox. Retained sandboxes keep their existing image.
- **Identity and file permissions.** A new sandbox on the current default image receives its current lease's
  identity-token environment before its first accepted command. File writes apply the
  requested mode, including executable scripts; the default remains 0644.
- **The code interpreter speaks seven languages.** Python, JavaScript,
  TypeScript, R, Java, Bash and Go, each keeping its state between cells (Go
  keeps its declarations and runs each cell as a program). R plots come back
  as PNG and R data frames and JavaScript arrays of objects as tables, and
  `display` returns any file as a result. R, Java and Go install themselves the
  first time you use them. See [JavaScript](./javascript#code-interpreter).
- **Watch files.** `sbx.files.watch`, `runtime sandbox watch` and
  `runtime_sandbox_files_watch` stream create, write, remove, rename and chmod events
  for a directory, with include and exclude globs, batches, a rate cap that
  says when it drops events, and a cursor that loses nothing across a pause.
- **Record the desktop.** `sbx.desktop.recordings` records the screen to MP4
  and fetches it; a recording is bounded in CPU, bit rate and size and stops
  before the disk fills.
- **MCP servers in a sandbox.** `runtime sandbox mcp` and `sbx.mcp` start
  GitHub, Postgres, a Playwright browser, filesystem, fetch and nine more MCP
  servers in a sandbox in one call, each at an authenticated URL your agent
  connects to; secret settings come from Runtime secrets, so the server never
  holds the value. `GET /v1/mcp/catalog` lists them with their licences.
- **Terminals.** An organization may hold 64 terminals open, 12 in one sandbox
  (it was 8).
- **Mount your own bucket.** An Amazon S3, Cloudflare R2 or Google Cloud
  Storage bucket appears as a directory in a sandbox (`runtime sandbox mount`,
  `sbx.mounts.add`). The sandbox never holds the bucket's key: Runtime's egress
  proxy signs each request with it. See
  [mount your own bucket](./storage#mount-your-own-bucket).
- **Single sign-on, free on every account.** Sign in through Okta, Microsoft
  Entra ID, Google Workspace or any SAML or OIDC provider, prove your email
  domain with a DNS record, and require single sign-on for your members. See
  [single sign-on](./single-sign-on).
- **SCIM directory sync.** Your identity provider adds people, sets their roles
  through groups, and removes them the moment they leave, which revokes every
  key they made.
- **Identity tokens for code in a sandbox.** A sandbox gets a short-lived OIDC
  token naming itself, its organization and its image, and trades it for AWS or
  Google Cloud credentials with no stored key. See
  [identity tokens](./identity-tokens).
- **Custom domains, TCP ports, dedicated outbound addresses and private
  networks,** for paid accounts. Serve a sandbox's port at your own hostname
  with automatic HTTPS (`runtime domain add`), open a public TCP port to a
  database or game server (`runtime port open`), send from an address of your
  own for allow-lists (`runtime address reserve`), and reach your sandboxes from
  your own network over WireGuard (`runtime tunnel`). See
  [networking](./networking).
- **MCP tools are renamed, a breaking change.** Every tool now carries its
  product's name, as the CLI does: `runtime_exec` is `runtime_sandbox_exec`,
  `runtime_files_read` is `runtime_sandbox_files_read`,
  `runtime_sandboxes_create` is `runtime_sandbox_create`, and images, volumes
  and snapshots are `runtime_image_*`, `runtime_volume_*` and
  `runtime_snapshot_*`. Every sandbox tool names its sandbox `id`. The old
  names are gone: a call to one fails and its error names the new one. Restart
  your agent, or run `/mcp` in Claude Code, so it lists the tools again, and
  change any permission rule or prompt that names an old tool. The whole table
  is in [MCP](./mcp#renamed-tools).
- **`runtime_sandbox_exec` takes a command as a list** as well as a string; a
  list runs without a shell, as `argv` does.

## 23 September 2026

- **Switch in one import from Daytona and Vercel Sandbox too.** Code written
  for Daytona's or Vercel Sandbox's SDK runs on Runtime after changing one
  import to `withruntime/daytona` or `withruntime/vercel`, in JavaScript and
  Python, as E2B code already does with `withruntime/e2b`.
- **See what you save.** `runtime compare --from e2b` prices the sandboxes you
  actually ran at a rival's published rates and prints the monthly saving.
  Record the provider you are leaving with `runtime switch --from <provider>`
  before your first top-up, and that top-up is matched, up to $100.
- **Works inside the agent tools you use.** A sandbox client for the OpenAI
  Agents SDK, tools for the Vercel AI SDK, LangChain, CrewAI, LlamaIndex,
  Pydantic AI, Google ADK, Mastra and the Claude Agent SDK, a Claude Code plugin,
  and ready configs for Codex, Cursor, Windsurf, VS Code and Gemini CLI. See
  [frameworks](./frameworks).
- **Remote MCP with browser sign-in.** Add Runtime's MCP address to Claude.ai,
  ChatGPT or another remote client, approve it once in your browser, and it
  works with no key to paste. Each connection is listed and revocable on your
  keys page.
- **SSH, editors and port forwarding.** `runtime sandbox ssh <id>` opens a
  shell, `runtime sandbox ssh config --install` lets VS Code and JetBrains
  connect, and `runtime sandbox port-forward <id> 5432` brings any TCP port to
  your machine, all over the API with no port open to the internet.
- **Pause answers at the freeze.** A pause returns as soon as the sandbox's
  processors stop, and compute billing ends there; its memory is saved in the
  background.
- **The SDKs wait for room.** When every sandbox slot is taken, a create waits
  for one to free, for up to two minutes, instead of failing.
- **Every sandbox command lives under `runtime sandbox`.** `runtime sandbox
run`, `runtime sandbox ssh` and `runtime sandbox port-forward`, because
  sandboxes are one product of several. The old `runtime run` says where it
  went.
- **Custom images, all the way.** Build from any Dockerfile: multi-stage,
  `COPY --from`, `ARG`, heredocs, `ADD` from a URL, `FROM scratch` and
  `.dockerignore`, with a build context of up to 100 MiB sent from a folder,
  where a rebuild uploads only what changed. Pull from private registries
  (Docker Hub, GitHub, Google, Amazon ECR and others) with credentials sealed on
  arrival and never returned. Each build of a name is its next version, tags
  such as `latest` point at versions, and a sandbox starts from `name:tag`. An
  image can run a start command and have its sandbox's create wait for a ready
  port or command. Rebuilds start from the steps an earlier build shares, four
  builds run at once on a paid account, and the build log streams. See
  [custom images](./images).
- **Metrics, events and webhooks.** Each sandbox's measured CPU and memory
  over time, with `sbx.metrics()`, `runtime sandbox metrics`, MCP, and live
  charts on the sandbox's own page in your account, where owners can also stop
  it. Lifecycle events (created, running, paused, woken, stopped, start failed)
  for sandboxes, snapshots and volumes, with `GET /v1/events`. Webhooks send
  them to your URL, signed like Stripe's, retried for about three days, with a
  delivery log and a test send; `verifyWebhook` in both SDKs checks them.
  OpenTelemetry export pushes events as logs and CPU and memory as metrics to
  any OTLP/HTTP endpoint. See [metrics and webhooks](./observability).
- **Teams.** Invite people to your account as owner, admin, developer or billing
  member; each role can do what its name says and no more, and a key can never
  do more than the member who made it. A person can belong to several accounts
  and switch between them on the website or with `runtime account switch`. See
  [teams](./teams).
- **Audit log.** Every change to members, keys, connections, limits, credit,
  network rules, secrets and durable resources is recorded with who made it,
  when and from which address, kept at least 400 days. Read it at
  [Audit log](https://withruntime.com/account/audit), with `GET /v1/audit`,
  `runtime audit`, the SDKs or MCP.
- **Paid sandboxes reach every port.** Databases, `git` over ssh, gRPC and
  programs that ignore proxy settings work with no setup, on any public host.
  Trial sandboxes stay on ports 80 and 443, and your network rules narrow every
  port.
- **Secrets sandboxes never see.** `runtime secrets set OPENAI_API_KEY --host
api.openai.com` stores a key once; sandboxes see a placeholder, and the proxy
  adds the value to HTTPS requests to the hosts you named. See
  [security](./security#secrets-sandboxes-never-see).
- **Paused sandboxes wake on request.** A command, a file or terminal call, or
  a visit to a shared port wakes a paused sandbox by itself, in about half a
  second, and the call runs. `idlePauseSeconds` now pauses a sandbox after
  that long without a request, so it costs running time only while it is used.
- **Sandboxes by name.** A name is unique in the account, and
  `Sandbox.getOrCreate(name)` returns that sandbox, woken if paused, or makes
  it.
- **Long-running sandboxes from every interface.** `persistent: true` at
  create, `sandbox.update()`, `runtime sandbox update --persistent on` or the
  API keeps a paid sandbox running while credit lasts, and `keepAlive` extends
  a lease from your own process.
- **50 free hours and 100 sandboxes at once.** The free trial is now 50 hours
  (now 100), up from 20, still with no card and eight sandboxes running at once. A paid
  account starts with room for 100 sandboxes, 200 vCPUs and 400 GiB of memory
  at once, and more on request. Accounts that signed up before get the 50 hours
  too.
- **Forks and snapshots for everyone.** Copy a running sandbox with its memory
  and processes, and choose whether the copies use the trial or paid credit.
- **Code written for E2B runs on Runtime.** Change `from "e2b"` to
  `from "withruntime/e2b"` (Python `withruntime.e2b`) in SDK 0.4.0, and it runs.
- **SDKs work behind proxies and inside Cloudflare Workers.** Both SDKs honour
  `HTTPS_PROXY` and `NO_PROXY`, and the JavaScript SDK runs in a Worker with
  `nodejs_compat`.
- **Keys for CI from the terminal.** `runtime keys create` gets an
  owner-approved key and prints it once, ready to pipe into a secret store.
- **First commands in a fresh sandbox are faster.** Start templates now come
  with Node, npm, Python, pip, Bun, uv and git already warm, so a first `node`
  takes 84 ms instead of 1,284 ms.
- **A public status page.** [withruntime.com/status](https://withruntime.com/status)
  checks the API from outside every two minutes and starts a real sandbox every
  ten.
- **Storage prices for snapshots, images and volumes.** Snapshots and images
  cost $0.08 per GB a month and volumes about $0.11 per GiB a month, and the
  trial keeps three images and 10 GiB of volumes free for good.
- **Read your own limits.** `runtime limits` and `runtime.limits.get()` show
  whether a key is read-only and how much of its daily limit is left.

## 22 September 2026

- **Custom images.** Build an image from a package list, a public image or a
  Dockerfile, and start every sandbox from it.
- **Volumes.** Persistent disks that outlive sandboxes, attached read-write to
  one or read-only to many.
- **Previews.** Give any port in a sandbox an HTTPS address at
  `runtimehost.com`, private with a token unless you make it public.
- **A desktop in any sandbox.** Start a Linux desktop and drive it with clicks,
  keys and screenshots, or watch it live.
- **Code interpreter.** A notebook-style Python or JavaScript session in a
  sandbox, with charts returned as images.
- **Network rules per sandbox.** Allow or deny hosts, turn the internet off, and
  open `host:port` pairs such as a database on a paid account.
- **Interactive terminals.** `runtime sandbox shell` opens a real terminal in a
  sandbox, and the API serves one over WebSocket.
- **Read-only keys and daily spending limits.** An owner can give an agent a
  key that changes nothing, or cap what it may spend in any 24 hours.
- **Buy credit by card.** Add any amount from $10 to $10,000, with no
  subscription.
- **Referrals.** Refer a company and you both get credit equal to its first
  top-up, up to $500 each.
- **A 20-hour free trial.** Every new account gets 20 sandbox hours (now
  100) with no card.
- **One line connects your agent.** `claude mcp add --scope user runtime -- npx -y withruntime mcp`
  (or the same for Codex and Cursor) is the whole setup; the agent asks for one
  browser approval.
- **`runtime run`.** One command creates a sandbox, runs your command, prints
  its output and stops it, connecting the machine on first use.
- **In the official MCP registry.** Runtime Cloud is listed for any MCP client
  to find.
- **The `withruntime` package.** Both SDKs publish as `withruntime` on npm and
  PyPI, and the old names still install it.
- **API 0.2.0.** One API for every product, over HTTP/2, with a public OpenAPI
  document.
- **A hundred commands at once.** One key can have 128 requests in flight, so an
  agent can fan out without refusals.
- **Idle sandboxes pause themselves.** A sandbox left on the default lease and
  never used pauses after five minutes (now any sandbox after a
  minute with nothing happening in it), so it stops paying the running rate.
- **Ask support anywhere.** Ask from the dashboard, with `runtime support`, or
  at support@withruntime.com.

## 21 September 2026

- **Public signup opens.** Anyone can sign up and start a sandbox on the free
  trial.

## 20 September 2026

- **Connect an agent from the browser.** An agent shows you a link and a code,
  and you approve it once.
- **Keys for every product.** An API key works across every Runtime Cloud
  product and lasts until you revoke it.
- **withruntime.com.** Runtime Cloud moves to one address.

## 19 September 2026

- **Wake in about a third of a second.** A paused sandbox comes back with its
  memory and processes in about a third of a second.

## 18 September 2026

- **Pause keeps memory.** A paused sandbox saves its running memory and wakes
  with its processes still running.
- **Pay for the CPU you use.** CPU is charged only while it is busy, and memory
  while the sandbox runs.


---

<!-- https://withruntime.com/docs/choosing-agent-sandbox -->

# How to choose a sandbox for AI agents

An agent sandbox is an isolated computer where an AI agent can run programs, install dependencies and work with files.

The right one completes your real jobs safely, reliably and at the lowest total
cost. This page gives the checks that decide it, and where Runtime stands on
each.

## Where Runtime stands out

- **It bills the CPU your agent uses.** Most agents spend most of their time
  waiting on a model. Runtime charges measured CPU at $0.025 per vCPU-hour, with
  a floor of a twentieth of a vCPU, and $0.0075 per GiB-hour of memory.
- **Idle time bills only storage.** A sandbox pauses itself after
  300 seconds with nothing happening in it. It wakes on the next request. Its memory and processes are intact.
- **It costs 42% to 88% less** than fourteen other sandbox providers on an agent
  job that mostly waits ([the comparison](#compared-with-a-specific-provider)).
- **Every sandbox is a Firecracker microVM** with its own kernel, on dedicated
  servers Runtime operates.
- **Pause keeps memory.** A paused sandbox wakes with its processes still
  running, kept while you have credit. Forks copy a running sandbox, memory
  included.
- **An uptime promise.** Paid accounts get 99% API uptime a month. If a
  month falls short, 10% of that month's charges is returned as credit automatically
  ([Uptime Promise](/legal/sla)).
- **The agent sets itself up.** It asks for access. You approve once in the
  browser. No key goes into a prompt or a project file.
- **Built for agents that retry and spend.** Idempotency keys on every write,
  read-only keys, and a daily spending limit per key.
- **Everything around the sandbox.** Network rules, secrets the sandbox never
  sees, volumes, bucket mounts, a desktop, metrics, webhooks and OpenTelemetry
  export come on every account. Custom domains, TCP ports, dedicated outbound
  addresses and WireGuard private networks come on paid accounts ([products](./products)).
- **Free to try.** 100 free hours of a 1 GB machine every month, no card. Then prepaid credit from $10, with
  no plan fee.

## Start with the workload

Write down one representative task. For example: install a repository's pinned
dependencies, run its test suite, make one change, and export the test report.

Record the language version, CPU and memory needs, network destinations, files
to keep, expected duration and acceptable failure rate.

| Requirement             | What to verify                                                | Runtime                                                                                                                                                         |
| ----------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Isolated code execution | Boundary between guest, host and other tenants                | A Firecracker microVM with its own kernel for every sandbox                                                                                                     |
| Agent integration       | Actual remote execution, structured results, file round trip  | API, CLI, Python, JavaScript and MCP; an OpenAI Agents SDK sandbox client and ready tools for ten agent frameworks                                              |
| Easy authentication     | Connection without secrets in prompts or project files        | Browser-approved CLI connection; local MCP reuses it                                                                                                            |
| Outbound network        | Your package registries and service destinations work         | Every port with a kept top-up, 80 and 443 without credit; per-sandbox rules; secrets the sandbox never sees                                                     |
| Public app hosting      | Reachability, ingress auth and abuse controls                 | Previews: an HTTPS address per port, private by default; custom domains and TCP ports with a kept top-up                                                        |
| Pause and restoration   | Files and memory survive; expiry and failed wake are explicit | Files, memory and processes kept while you have credit; a failed wake says so                                                                                   |
| Custom environments     | Dependencies installed once, reused on every start            | Custom images from a recipe, any public or private image, or a Dockerfile                                                                                       |
| Storage                 | Data that outlives a sandbox, and your own buckets            | Volumes backed up off their server daily; S3, R2 and GCS buckets mounted as directories                                                                         |
| Predictable cost        | CPU, memory, idle time, storage, retries and fees             | Pauses itself after 300 seconds idle; measured CPU with a floor, reserved memory, separately quoted paused storage, 100 GiB out a month free  |
| Spending control        | Limits an agent cannot raise itself                           | Read-only keys and a daily spending limit per key, set only by a person                                                                                         |
| Observability           | What each sandbox did, in the tools you already watch         | CPU and memory metrics, signed webhooks and OpenTelemetry export, at no charge                                                                                  |
| Private connectivity    | Fixed egress for allow-lists; a way into your own network     | Dedicated outbound addresses with credit, WireGuard private networks with a kept top-up; identity tokens for AWS and Google Cloud                               |
| Team access             | Roles for people, and a record of who changed what            | Single sign-on (SAML, OIDC) and SCIM free; owner, admin, developer and billing roles; an audit log kept at least 400 days                                       |
| Reliability             | A published uptime figure, and what you get when it is missed | 99% a month for paid accounts, 10% back automatically; a status page checked from outside                                          |

For exact terms, read [security](./security), [pricing](./pricing),
[free usage](./included-usage), and the [API reference](./api).

## Measure completed jobs

Run the same inputs, dependency versions and output checks on every candidate.
Separate cold starts from warm or resumed runs. Run enough repetitions to
show slow runs and failures. Record:

- Time from request to an executable environment.
- Dependency setup, task execution and artifact export time.
- Median and 95th-percentile end-to-end completion time.
- Successful, failed and retried jobs, including exhausted capacity.
- CPU-seconds, allocated memory, running duration and retained storage.
- Total charge divided by successful jobs, including failed attempts.

State hardware, region, concurrency, dates, SDK versions, CPU guarantees and
pricing assumptions. A shared CPU ceiling is not a reserved physical core, so
compare like with like.

## Exercise the failures you will have to handle

Try a lost create response, an execution timeout, a nonzero exit code, a refused
network destination, a time limit that ran out, and unavailable capacity on wake.

- Retrying the same operation should not create duplicate work or charges.
- Revoking one agent's credential should stop its access without breaking
  another agent's connection.
- For a pause test, write a file and keep a small in-memory value. Pause,
  restore, then verify both. A clean boot is not proof that memory came back.

## Where Runtime fits best

Runtime fits coding agents, test execution, file processing and multi-step jobs
on Linux. Its measured CPU saves the most on workloads that wait on model or
network responses.

A running sandbox still pays its CPU floor and reserved memory. Paused
storage is billed separately. Inbound traffic is free, and each account's first
100 GiB out a month is free, then $0.02 per GB (10⁹ bytes). Sandboxes run Linux on CPUs, in
one US region today. See [products](./products) for everything available.

## Compared with a specific provider

The same job on each provider: 1,000 runs of a 2 vCPU, 4 GiB sandbox, 60
seconds each, 20 CPU-seconds of work. Rival rates were checked
25 October 2026. Each provider's page gives its date.

| Provider                                                 |      Cost for 1,000 runs |              Runtime saves |
| -------------------------------------------------------- | -----------------------: | -------------------------: |
| **Runtime**                                              |     **$0.64** |                          — |
| [Northflank](./northflank-alternative)                   |      $1.11 |      42% |
| [Cloudflare Sandbox](./cloudflare-sandbox-alternative)   |      $1.35 |      53% |
| [Prime Sandboxes](./prime-sandboxes-alternative)         |           $1.52 |           58% |
| [Fly Machines](./fly-alternative)                        |    $1.53 |    58% |
| [Morph](./morph-alternative)                             |           $1.67 |           62% |
| [Vercel Sandbox](./vercel-sandbox-alternative)           |          $2.12 |          70% |
| [Freestyle](./freestyle-alternative)                     |       $2.25 |       72% |
| [Fly Sprites](./fly-alternative)                         |     $2.40 |     73% |
| [CodeSandbox](./codesandbox-alternative)                 |     $2.48 |     74% |
| [E2B](./e2b-alternative)                                 |             $2.76 |             77% |
| [Daytona](./daytona-alternative)                         |         $2.76 |         77% |
| [Blaxel](./blaxel-alternative)                           |          $3.45 |          81% |
| [Modal Sandboxes](./modal-sandbox-alternative)           |           $3.97 |           84% |
| [AWS Lambda MicroVMs](./aws-lambda-microvms-alternative) | $4.20 | 85% |
| [Runloop](./runloop-alternative)                         |         $5.33 |         88% |

Each page has the working, a side-by-side table, and how to switch. The saving
is largest for agents that wait. For a job that keeps every CPU busy the whole
time, Northflank's allocated rate is lower than Runtime's.

## Switch with one prompt

Give your coding agent the one instruction in [migration](./migrate). It
replaces the old provider's calls on a branch, tests them on the free usage, and
tells you what you save each month. Your old code stays on the main branch until
you merge. Code written for E2B, Daytona, Vercel Sandbox or Blaxel runs after
changing one import. Whichever provider you
are moving from, credit you add within 30 days of signing up is matched, up to $1,000 in total
([welcome match](./pricing#welcome-match)). For a new project, start with
[getting started](./start).


---

<!-- https://withruntime.com/docs/claude-managed-agents -->

# Runtime for Claude Managed Agents

Give a Claude Managed Agent access to Runtime's sandboxes through Runtime's remote MCP server. The agent can create, run, share and keep machines, beside its own session container.

Claude Managed Agents runs the agent loop and a container for each session on
Anthropic's side. Add Runtime's MCP server to the agent and it can also create
Runtime sandboxes: Firecracker microVMs with their own kernel. They can run for days, pause with their memory, share a port at an HTTPS address, fork, run Docker, and start from your own images. Runtime bills
them for the CPU they use. The Runtime key stays in an Anthropic vault and
never enters the session's container.

## Set it up

You need an Anthropic API key with Managed Agents access and a Runtime key.
Create the Runtime key on the [API keys page](https://withruntime.com/account/keys)
and give it a daily spending limit
([read-only keys and daily limits](./security#read-only-keys-and-daily-limits)),
so the agent's sandboxes can never spend past it.

```bash no-run
pip install anthropic
export RUNTIME_API_KEY=...   # from your secret manager
```

Four calls, made once in a setup script. Store the ids they return:

```python check
import os

import anthropic

client = anthropic.Anthropic()
RUNTIME_MCP = "https://api.withruntime.com/mcp"

# 1. A vault holds the Runtime key. Anthropic adds it to requests to the MCP server.
vault = client.beta.vaults.create(display_name="Runtime")
client.beta.vaults.credentials.create(
    vault.id,
    display_name="Runtime key",
    auth={"type": "static_bearer", "mcp_server_url": RUNTIME_MCP, "token": os.environ["RUNTIME_API_KEY"]},
)

# 2. The agent declares Runtime's server and may use its tools.
agent = client.beta.agents.create(
    name="Builder",
    model="claude-opus-5",
    system="Build and run software in Runtime sandboxes. Stop every sandbox you start unless asked to keep it.",
    mcp_servers=[{"type": "url", "name": "runtime", "url": RUNTIME_MCP}],
    tools=[
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
        {"type": "mcp_toolset", "mcp_server_name": "runtime"},
    ],
)

# 3. An environment for the session's own container.
environment = client.beta.environments.create(
    name="builder", config={"type": "cloud", "networking": {"type": "unrestricted"}}
)

print(vault.id, agent.id, environment.id)
```

Then every run starts a session with the vault attached and sends the task:

```python check
import anthropic

client = anthropic.Anthropic()


def run(agent_id: str, environment_id: str, vault_id: str, task: str) -> str:
    session = client.beta.sessions.create(agent=agent_id, environment_id=environment_id, vault_ids=[vault_id])
    text = []
    with client.beta.sessions.events.stream(session_id=session.id) as stream:
        client.beta.sessions.events.send(
            session_id=session.id,
            events=[{"type": "user.message", "content": [{"type": "text", "text": task}]}],
        )
        for event in stream:
            if event.type == "agent.message":
                text += [block.text for block in event.content if block.type == "text"]
            elif event.type in ("session.status_idle", "session.status_terminated"):
                break
    return "".join(text)
```

A production client also handles a dropped stream and tool confirmations;
Anthropic's
[Managed Agents documentation](https://platform.claude.com/docs/en/managed-agents/overview)
covers both.

## What the agent can do with Runtime

The agent sees every tool of Runtime's [MCP server](./mcp#tools), named
`runtime_<product>_<verb>`. The ones a builder uses most:

| Tool                            | What the agent does with it                                                     |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `runtime_sandboxes_create`      | Start a sandbox of the size it needs, from Runtime's base image or yours        |
| `runtime_sandboxes_exec`        | Run a command and read its exit code and output, or start it in the background  |
| `runtime_sandboxes_files_write` | Write the files it generated                                                    |
| `runtime_sandboxes_previews`    | Share a port at a private HTTPS address under `runtimehost.com`                 |
| `runtime_sandboxes_manage`      | Pause, wake, extend or stop                                                     |
| `runtime_sandboxes_fork`        | Copy a running sandbox, memory included, to try two approaches at the same time |
| `runtime_images_build`          | Build an image from a Dockerfile once, so later sandboxes start ready           |

A pattern that uses both kinds of machine: the agent writes and tests code in
its session container, then deploys the result to a named Runtime sandbox with a
preview. That sandbox outlives the session. The next session finds it by name,
wakes it, and continues.

## Keep the agent inside its budget

- **The daily spending limit** on the Runtime key bounds every sandbox the
  agent starts. A create or wake past it fails with `spending_limit_reached`,
  and nothing is charged.
- **Idle sandboxes pause.** A sandbox pauses itself when nothing happens in
  it, so a forgotten one stops costing compute. Tell the agent in its system
  prompt to stop what it starts, as the example does, and to set
  `timeoutSeconds` when a task should end at a fixed time.
- **A read-only key** lets a reviewing agent see the sandboxes, their files and
  their cost. It cannot change anything.
- **A session budget** on the Managed Agents side caps the model spend of one
  session, independently of Runtime.

## What it costs

CPU is billed as used, $0.025 per vCPU-hour with a floor of 50 millicores, and
reserved memory at $0.0075 per GiB-hour. A 2 vCPU, 4 GiB sandbox costs $0.08 an
hour with both CPUs busy and $0.03125 an hour while it waits. A paused sandbox
pays only storage ([pricing](./pricing)). Every account gets 100 free hours of a 1 GB machine every month, no card.

## What was verified

- On 25 September 2026 an MCP client sent a Runtime key as
  `Authorization: Bearer` to `https://api.withruntime.com/mcp`, the way a vault
  `static_bearer` credential does. It listed 76 tools, created a sandbox, ran
  `uname` and `python3 --version` in it, and stopped it, all in 1.4 seconds.
- The vault, agent and session calls above match `anthropic` 1.8.0 for Python
  on the same day: `vaults.create(display_name=...)`, a `static_bearer`
  credential with `token` and `mcp_server_url`, and `mcp_servers` with
  `mcp_toolset` on the agent.

Official reference checked 25 September 2026:
[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview).


---

<!-- https://withruntime.com/docs/cli -->

# The runtime CLI

The CLI runs every Runtime Cloud product from a terminal or a script.

It comes with the JavaScript SDK and needs Node 22.12 or later. `runtime --version` returns in about 40 ms, 15 ms more than Node alone. Its one dependency, `undici`, loads only when a proxy applies. You can run it without installing, or install it once. npx adds about a quarter of a second to every call, so an agent that runs many commands should install it:

```bash no-run
printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
npx withruntime sandboxes run -- python3 - < invoice.py   # without installing
npm install --global withruntime                   # then the command is runtime
runtime sandboxes run -- python3 - < invoice.py
```

An installed CLI stays at its version until you update it with `npm install --global withruntime@latest`, and `npx withruntime` runs an installed copy before it downloads one, so it can be older than the docs. When the CLI rejects an option or a command, it checks npm for a later version, for at most 1.5 seconds, and prints how to update when one exists. It skips the check in CI (the `CI` variable set) and when `RUNTIME_NO_UPDATE_CHECK=1` is set. `npx withruntime@latest` always runs the latest version.

The examples below use `runtime`, the installed command. Without installing, write `npx withruntime` in its place. Commands follow the pattern `runtime <product> <command>`, with account commands at the top. Running `runtime` on its own shows whether this machine is connected and what to run first.

Each product is one plural word. The word is the same in the CLI, the API, the SDKs and MCP: `runtime sandboxes`, `runtime images`, `runtime ips`, `runtime networks`. The singular is a typing shortcut for the same product (`runtime sandbox ls`). On 6 October 2026, three words were renamed: `runtime address` is now `runtime ips`, `runtime network` is now `runtime networks`, and `runtime tunnel` is now `runtime networks wireguard`. The old words keep working for 30 days after the rename ships. Each use prints the new command. After that, they fail with `name_retired` and a hint that names the new command.

## One command in a fresh sandbox

```bash
printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
runtime sandboxes run -- python3 - < invoice.py
runtime sandboxes run --keep --vcpu 2 -- nproc   # keeps it, and prints how to run more
```

`run` creates a sandbox, runs the command, prints its output, deletes the sandbox and exits with the command's exit code. It takes the same options as `sandbox create`, with one difference: `--timeout <seconds>` limits the command, as it does for `exec` (exit code 124 when it runs out), not the sandbox. `--keep` leaves the sandbox running for more commands.

## Connect once

Any command connects this machine the first time it needs a connection, so you do not need a separate step. To connect in advance:

```bash no-run
runtime login                 # opens your browser; approve Connect agent
runtime login --no-browser    # prints a link and a code for another device, and exits
runtime login --wait          # waits for an approval already asked for
runtime login --with-key      # or paste a key from withruntime.com/account/keys
runtime login --agent-name "CI deploy bot"   # the name the approval page and the account show
runtime whoami
```

**You never copy an API key.** The CLI receives and saves its own credential.

- At a terminal, login waits for the approval.
- Run by an agent (no terminal), it waits up to 50 seconds, then prints the link and code and exits with `connection_pending`. `--no-browser` exits immediately.
- The request is saved. After it is approved, run the same command again, or any other command, to finish the connection. No new link is needed. A request expires after 15 minutes.

`--with-key` reads the key from standard input (piped, or typed without echo), never from the command line. When `RUNTIME_API_KEY` is set, it overrides the saved connection. CI and scripts use it for this. In CI (the `CI` variable set) or with `RUNTIME_NO_LOGIN=1`, a missing key is an error instead of a browser approval.

## Keys for CI

A CI runner has no browser, so it runs on a key. With a key already on this machine (saved by `login`, or `RUNTIME_API_KEY`), `runtime keys create` uses it to make the new key immediately, with no browser. `--browser` asks for browser approval instead.

```bash no-run
runtime keys create --name ci                    # full access, until revoked
runtime keys create --name ci --daily-limit 25   # at most $25 in any 24 hours
runtime keys create --name monitor --read-only   # sees everything, changes nothing
runtime keys create --name web --account-wide    # uses every sandbox in the account
runtime keys create --name watcher --sandbox <id> --actions get,create --daily-limit 2  # one sandbox: look and restart
runtime keys create --name ci --daily-limit 25 --browser | gh secret set RUNTIME_API_KEY
```

With `--browser`, the command prints a link and a code, as `login` does. An owner, admin or developer of the account opens the link, checks the code, sees the key's name, access and limit, and chooses **Create key**. Without it, the key that is on the machine must be a full-access key made by an owner or admin, and the new key never has more access than that key ([run a swarm](./teams#run-a-swarm)).

The key is printed once, alone on standard output. Everything else goes to standard error, so the key pipes straight into a secret store. `--json` prints the key as one JSON object instead. Store the key now. Runtime keeps only a hash of it. Give it to your jobs as `RUNTIME_API_KEY`.

- With `--browser`, the command waits up to 15 minutes for the approval. Stopping it cancels the request. A key that was approved but not yet received is revoked.
- These options match the API keys page. There are no others. A key lasts until it is revoked. Daily limits are in dollars.
- `runtime keys ls` lists this key and the keys it made, with what each spent in the last 24 hours. `runtime keys usage <keyId>` shows one key's spend, held money and running sandboxes. `runtime keys update <keyId>` changes a key's daily limit (`--daily-limit <usd>`, `--no-daily-limit`) or reach (`--account-wide`, `--own-agent`): a key widens only the keys it made, within its own limit. `runtime keys revoke <keyId>` revokes a key this key made.
- To change a key's daily limit, list every key, or revoke them, use [API keys](https://withruntime.com/account/keys).

## Book room for a burst or a pool

```bash no-run
runtime reservations book --sandboxes 300 --from 21:00 --to 23:00
runtime reservations book --sandboxes 50 --vcpu 4 --memory 8192 --from now --to 02:00
runtime reservations keep --sandboxes 40 --snapshot <id> --for-key
runtime reservations change <id> --snapshot <id>
runtime reservations ls
runtime reservations get <id>
runtime reservations cancel <id>
```

- The command returns immediately. **Booked:** in the window, creates are never refused for room or limits, up to what you booked. Sandboxes you run are billed as usual. Booked room that none of them uses costs $0.001875 per GiB-hour. The output states the most that comes to if none run.
  **Declined:** the command prints why, the most that fits, and the nearest window that fits all of them. It exits with code 1.
- `--from` and `--to` take an ISO time, `now`, or `HH:MM` on this machine's clock: today, or tomorrow if it has passed. A `--to` before `--from` is the next day. A window is at most 24 hours and starts within 14 days.
- Size defaults to 2 vCPU, 4096 MiB memory and 4096 MiB disk. `--json` prints the booking.

## Sandboxes

```bash
id=$(runtime sandboxes create --name demo --label team=search)
runtime sandboxes exec "${id}" -- python3 -c 'print(sum([125, 250, 375]))'
runtime sandboxes exec "${id}" --cwd /workspace --env API_TOKEN -- env
runtime sandboxes exec "${id}" --root -- apt-get install -y jq
runtime sandboxes exec "${id}" --trace-files read.json -- python3 -c 'import json'
runtime sandboxes ls
runtime sandboxes ls --state running --label team=search
runtime sandboxes get "${id}"
runtime sandboxes stop "${id}"
```

`create` prints only the id, so it works inside `$(...)`. It waits until the sandbox is running. `--no-wait` returns immediately. Its options:

- `--vcpu`, `--memory` and `--disk` in MiB. `--timeout <seconds>` (60 to 86,400, 24 hours) sets a time limit. `--on-timeout pause|stop|delete` sets what happens at the limit. Without `--timeout`, a sandbox has no limit: it runs while it works and pauses when idle.
- from withruntime 0.7.0: `--cpu-floor <thousandths>` for guaranteed CPU, and `--cpu reserved` for the highest floor, every vCPU. `--max-total-cost <usd>` caps its total cost over its whole life.
- `--name`, `--label k=v` (repeatable). `--trial` and `--paid` are accepted and ignored, since the free usage is spent first, then credit.
- `--env K=V` (repeatable) sets a variable for every command, terminal and SSH session in the sandbox, for its whole life. Values are never shown again. From withruntime 0.17.1, `--env K` alone sends `K`'s value from your own shell, so a secret does not appear in any command line ([shared keys](./security#a-secret-your-sandbox-checks-on-requests-it-receives)).
- Network rules: `--no-internet`, `--allow <host>`, `--deny <host>` and `--connect <host:port>`. With `--no-internet --allow <host>`, the sandbox reaches only the listed hosts.
- `--secret NAME` (repeatable) lets the sandbox use only the egress secrets you name, from those that would otherwise reach it. `--no-secrets` gives it none. Without either option, it gets every secret that reaches it. This setting is fixed for the sandbox's life. `fork` takes the same two options and may only narrow the list. `get` shows it.
- `--idle-pause <seconds>` pauses the sandbox after that long with nothing happening in it. The default is 300. The range is 60 to 86,400, or 0 for never. `--no-auto-wake` keeps a paused sandbox paused until you run `wake`. `--no-wake-on-timers` keeps request wakes but stops a process due on a timer from waking an idle-paused sandbox.
- `--persistent` keeps a paid sandbox running until you stop it, idle or not, while credit lasts.
- `--user root` runs its commands, background processes and shells as root, with no `sudo` in front, unless one says otherwise.
- `--lease <seconds>`, with no time limit, funds each renewal that many seconds ahead, from the first lease (1,800) to 43,200 (12 hours); the default is 1,800. The sandbox keeps running for at least half of that if Runtime's control plane cannot renew it.
- `--get-or-create` with `--name` prints the id of the sandbox that already has the name, woken if paused. Without it, the command fails with `name_taken`.

From withruntime 0.7.0, every command refuses an option it does not take, before it sends anything. It names the option you likely meant: `--memory-mib` gets "Did you mean --memory?". A value option followed by another flag fails locally. For example, `--name --json` fails with `--name needs a value.` Boolean options accept `=true` or `=false`. `--persistent=maybe` fails with `--persistent takes true or false.` Explicit numeric values, including zero, are sent to the API for validation. They do not silently use a default. `--help` after any command prints its product's help and runs nothing.

`ls` lists the live sandboxes and the stopped ones that keep their disk. `ls --all` adds the rest, and lists every sandbox the account has had, oldest first, so the newest are last. `get` shows its time limit, when it ends (or that it runs while it works), what happens then (`pause` or `stop`) and, once a sandbox has paused or ended, when and why it stopped ([troubleshooting](./troubleshooting#a-sandbox-stopped-on-its-own) explains each reason). A refused option is named as the option you typed, such as `--timeout`, not as the API's field (`timeoutSeconds`).

`exec` streams all of the output as it happens. `--max-output-bytes <n>` prints at most `n` bytes of each stream and says on standard error how many bytes each one wrote. Without `--json` there is no other limit; with `--json`, the result holds up to 256 MiB of each stream. It exits with the command's own exit code (124 when it timed out), so `set -e` scripts work as expected. `--root` runs the command as root with no `sudo` in front, keeping its environment and `PATH`. `spawn`, `run` and `shell` also take `--root`, and `ps` shows each process's user. Without `--timeout`, a command may run for 24 hours. With `--json`, it may run for 60 seconds. Everything it starts, `nohup … &` included, ends when the command returns. To run a server, start it with `spawn` (below) instead. Pass a secret with `--env NAME` alone. This reads the value from your shell. The value is never written into the command. Piped input reaches the command, up to 1 MiB: `echo 'print(1)' | runtime sandboxes exec "${id}" -- python3 -`.
`--trace-files <file.json>` writes to that file, on your machine, every file the command and anything it started read and wrote, as `{"read", "written", "truncated"}`. Use the files a test really read as the key for its cache ([which files a command read](./api#commands-and-processes)).
A program is found on the sandbox's own `PATH`, so `python` in an image from `python:3.12-slim` runs as it does there.

A command that writes faster than it is read keeps its latest 1 MiB. If any output was lost, `exec` says so on standard error. From withruntime 0.7.0 it also never exits 0 then. Ctrl-C stops the command in the sandbox too (it is sent SIGTERM) and exits 130. A connection that drops mid-command resumes where it stopped. If it cannot resume, the error names the process. Read its output with `logs`, or stop it with `kill`. For large output, write it to a file in the sandbox and copy the file out.

With `--json`, `exec` returns one result instead. It holds at most 64 KiB of `stdout` and 64 KiB of `stderr` for a command with a `--timeout` of 60 seconds or less. `stdoutTruncated` and `stderrTruncated` say whether anything was dropped. For more output, drop `--json`, or write the output to a file and read it with `runtime sandboxes cat`.

Background work, logs and a terminal. `logs` prints what a process has written so far and returns, even while the process runs. `-f` follows the output until the process exits. On a terminal, `sandbox logs`, `job logs` and `image logs` show control characters as `\u001b` and similar, so an escape sequence in a log cannot clear the screen or change what you read. With `--raw`, or when the output goes to a pipe or a file, control characters are written unchanged:

```bash
id=$(runtime sandboxes create)
pid=$(runtime sandboxes spawn "${id}" -- python3 -m http.server 8000)
runtime sandboxes ps "${id}"
runtime sandboxes logs "${id}" "${pid}"
runtime sandboxes kill "${id}" "${pid}"
runtime sandboxes stop "${id}"
```

`runtime sandboxes stop --label team=search` stops every live sandbox that has all the labels given. It exits 1 if any of them failed to stop. `runtime sandboxes rm --label team=search` deletes for good every sandbox that has all the labels given, stopped ones included. It exits 1 if any of them failed.

```bash no-run
runtime sandboxes shell "${id}"               # an interactive terminal, like ssh
runtime sandboxes shell "${id}" --command zsh # another program than the default bash -l
echo "ls" | runtime sandboxes shell "${id}"   # piped input runs, then the shell exits
runtime sandboxes spawn "${id}" --pty -- htop # in a terminal, for programs that need one
runtime sandboxes logs "${id}" "${pid}" -f      # follow until the process exits
```

Files. Give a sandbox path as `<id>:/path`. Directories copy whole. A file keeps its permissions, so a script stays runnable. `files` marks a directory `d` and a symbolic link `l`. It lists one level deep, unless `--depth` asks for more:

```bash
id=$(runtime sandboxes create)
mkdir -p project && echo "print('hi')" > project/main.py
runtime sandboxes cp ./project "${id}:/workspace/project"
runtime sandboxes files "${id}" /workspace --depth 2
runtime sandboxes cat "${id}" /workspace/project/main.py
runtime sandboxes cp "${id}:/workspace/project" ./project-copy
runtime sandboxes stop "${id}"
```

`cp` and `cat` stream data, so a file of any size copies without filling memory. Both check every byte against the file's length. A short copy is retried. If it is still short, the command fails with `download_incomplete` and exits 1. It never leaves a short file under the name you gave.

A sandbox's name works wherever its id does: in every `runtime sandboxes` command and in `--sandbox` filters, when one live sandbox has that name.

Lifecycle: `pause`, `wake` (a sandbox that is already awake stays as it is), `restart`, `extend <id> <seconds>` (it moves the time limit and prints the new end; a sandbox with no limit needs nothing), `stop`. A paused sandbox also wakes by itself when a command, file or terminal call, or a visit to a shared port, reaches it. It is billed as any wake, from the moment it runs.

A sandbox you come back to, by name, that pauses when idle and wakes when used:

```bash no-run
id=$(runtime sandboxes create --name dev --get-or-create --idle-pause 900)
runtime sandboxes exec "${id}" -- git -C /workspace/app pull
```

`update` changes a sandbox's settings after creation. Settings you leave out stay as they are:

```bash no-run
runtime sandboxes update "${id}" --idle-pause 0 --auto-wake off
runtime sandboxes update "${id}" --user root    # later commands run as root
runtime sandboxes update "${id}" --lease 43200  # funded 12 hours ahead; --lease default undoes it
runtime sandboxes update "${id}" --persistent on --max-total-cost 50   # dollars
runtime sandboxes update "${id}" --name dev-2 --label team=search
runtime sandboxes update "${id}" --env MODE=drain --unset-env QUEUE_URL
```

`runtime sandboxes switch-image <id> web:v2 --keep-workspace` moves a sandbox to another image. It keeps the sandbox's id, `/workspace` (your home), volumes, environment and previews. Its processes restart, and the rest of its old disk is lost. The flag is required. To keep everything, take a snapshot first ([images](./images#move-a-sandbox-to-a-new-version)).

`runtime sandboxes rm <id>` (or `delete`) removes a sandbox for good, in any state. It stops the sandbox, deletes its disk and paused memory, revokes its previews and ports, and removes it from every list. Its snapshots stay. Running the command again prints the same result.

`--persistent on` keeps a sandbox running until you stop it, idle or not, while credit lasts. It runs up to `--max-total-cost`. Its disk is billed as any sandbox's disk is. A stopped sandbox keeps its disk, so `restart` starts it again. It stays in `runtime ls` and `runtime sandboxes ls`, until `rm` deletes it. `--persistent off` makes it an ordinary sandbox again. `rm` removes it for good. `get` shows the automatic wake, idle pause and persistence settings.

Watch a directory. `watch` prints each change as it happens (create, write, remove, rename, chmod) until Ctrl-C:

```bash no-run
runtime sandboxes watch "${id}" /workspace --recursive --exclude node_modules --exclude '.git/**'
runtime sandboxes watch "${id}" /workspace/src --events create,write --include '**/*.py'
```

Create a link to one file that anyone can open with no API key. By default, the link downloads the file and lasts one hour. `--put` creates a link that accepts an upload. `--expires` takes `90s`, `10m`, `1h` or `7d` (60 seconds to 7 days):

```bash no-run
runtime sandboxes link "${id}" /workspace/report.csv --filename report.csv --expires 10m
runtime sandboxes link "${id}" /workspace/incoming.bin --put --max-bytes 10485760
runtime sandboxes link "${id}" /workspace/out --archive        # a folder, as a .tar.gz
runtime sandboxes link revoke "${id}"                          # ends every link of the sandbox
```

The link wakes a paused sandbox unless you pass `--no-wake`, which makes it return `sandbox_paused` instead. A link ends when it expires, when `link revoke` runs, when the key that made it is revoked, or when the sandbox is deleted ([links in the API guide](./api#file-links)).

## Code, previews, network rules and the desktop

```bash no-run
runtime sandboxes run-code "${id}" analysis.py --out-dir charts   # a notebook cell; charts saved as PNG
runtime sandboxes run-code "${id}" model.R                        # R, by the file's extension
runtime sandboxes run-code "${id}" - --lang go < main.go          # Python, JavaScript, TypeScript, R, Java, Bash or Go
runtime sandboxes run-code "${id}" step2.py --context "${ctx}"   # a context you made, not the language's default
runtime sandboxes preview "${id}" 3000                           # an HTTPS address for a port, private with a token
runtime sandboxes preview "${id}" 3000 --public                  # public, no token: paid sandboxes only
runtime sandboxes previews "${id}"
runtime sandboxes preview rotate "${id}" 3000                   # withruntime 0.7.0: refuse every token so far
runtime sandboxes unshare "${id}" 3000
runtime sandboxes session create "${id}" --origin https://app.example.com --ttl 900   # a token a web page uses; printed once
runtime sandboxes session ls "${id}"
runtime sandboxes session revoke "${id}" "${session}"
runtime sandboxes network "${id}"                                # show its rules
runtime sandboxes network "${id}" --allow pypi.org --allow '*.pythonhosted.org'
runtime sandboxes network "${id}" --no-internet
runtime sandboxes network "${id}" --internet                     # the internet back on
runtime sandboxes desktop "${id}" start                          # prints a link to watch it
runtime sandboxes desktop "${id}" open https://example.com
runtime sandboxes desktop "${id}" screenshot screen.png
runtime sandboxes desktop "${id}" record start --fps 10 --max-mib 256 --max-seconds 600   # prints the recording id
runtime sandboxes desktop "${id}" record stop "${rec}"
runtime sandboxes desktop "${id}" record fetch "${rec}" demo.mp4
runtime sandboxes browser "${id}" start                          # Chromium; prints its private CDP address. Heavy apps need a sandbox made with --memory 2048
runtime sandboxes browser "${id}" start --headed --width 1280 --height 800   # on the desktop, to watch
runtime sandboxes browser "${id}" stop
```

A session lets your own web page reach one sandbox's commands, files and previews directly. It lasts 1 hour by default, unless `--ttl` sets another length, and 24 hours at most. See [a sandbox from a browser](./javascript#a-sandbox-from-a-browser).

The desktop and the browser come ready on every server. The first `desktop start` in a sandbox installs nothing on its disk and takes about a second. The first recording installs ffmpeg. A recording is an MP4 file on the sandbox's own disk. It never grows past `--max-mib` or runs past `--max-seconds`, and it stops before the disk fills. A sandbox keeps at most 8 GiB of recordings.

A preview's address is under `runtimehost.com`. That domain serves everything sandboxes serve, and it is kept apart from Runtime's own site.

## Secrets

```bash no-run
printf %s "$OPENAI_API_KEY" | runtime secrets set OPENAI_API_KEY --host api.openai.com
runtime secrets set GITHUB_TOKEN --host api.github.com --header Authorization --format 'token {value}' < token.txt
runtime secrets set GITHUB_TOKEN --host api.github.com --allow 'GET,HEAD /repos/acme/*' < token.txt
runtime secrets set SLACK_APP_TOKEN --host slack.com --only-label role=hub < token.txt   # only sandboxes labelled role=hub
runtime secrets set DEPLOY_KEY --host api.example.com --only-sandbox "${id}" < key.txt     # only that sandbox
runtime secrets scope OPENAI_API_KEY --only-app "${app}"                                     # every copy of an App
runtime secrets set SLACK_APP_TOKEN --host slack.com --all-sandboxes < token.txt           # every sandbox again
runtime secrets set GITHUB_TOKEN_WEB --host api.github.com --only-label repo=web --env GITHUB_TOKEN < web.txt   # seen as GITHUB_TOKEN
runtime secrets scope SLACK_APP_TOKEN --only-label role=hub                                  # change who gets it, no value
runtime secrets set GITHUB_TOKEN --keep-value --allow 'GET /repos/acme/app/*'               # narrow it, no value
runtime secrets set DB_PASSWORD --exposed --only-sandbox "${id}" < password.txt             # that sandbox gets the value itself
runtime secrets set DEPLOY_KEY --exposed --only-app "${app}" --env SSH_KEY --from-file deploy_key   # several lines, read as they are
runtime secrets set OPENAI_API_KEY --host api.openai.com --expected-version 3 < key.txt     # only over version 3
printf %s "$DB_PASSWORD" | runtime secrets set DB_PASSWORD --jobs
runtime secrets get DEPLOY_KEY                                                               # its kind, version and variable
runtime secrets ls
runtime secrets ls --limit 10 --after GITHUB_TOKEN    # a page of 10, by name
runtime secrets rotate DB_PASSWORD < new-password.txt
runtime secrets reveal DB_PASSWORD
runtime secrets share DB_PASSWORD --agent "${agent}"   # or --all, or --none
runtime secrets rm OPENAI_API_KEY
```

The value is read from standard input or `--from-file PATH`, so it stays out of your shell history. Typed at a terminal, it is not shown. After this, every sandbox in the account has `OPENAI_API_KEY` set to a placeholder. The proxy swaps in the real value on HTTPS requests to the hosts you named. On accounts with credit, from `withruntime` 0.7.0, `--allow` narrows that to some methods and paths, once per rule:
`--allow /v1/chat/completions` for every method,
`--allow 'GET,HEAD /repos/acme/*'` for two. With `--keep-value` (from 0.22.0), `set` reads no value. It only narrows the `--host` and `--allow` an existing secret has. Anything wider is refused, because widening needs the value. `--only-label key=value` (once per selector) and `--only-sandbox <id>` give the secret to those sandboxes alone. `--only-app <id>` gives it to every copy of that App, whatever its version. A new value keeps that scope until `--all-sandboxes`. `--env VAR` puts the placeholder in `VAR` instead of `NAME`. Secrets scoped to different sandboxes may share one, such as a `GITHUB_TOKEN` per repository. A set that would give one sandbox two of them is refused. `ls` shows names, kinds, versions, hosts, placeholders, rules and which sandboxes get each secret. It never shows values. See [Security](./security#secrets-sandboxes-never-see).

`--exposed` stores a real value instead of a placeholder. The machines the secret reaches get the value itself in its variable. Use it for a database password, an SSH key, or anything that is not an HTTPS header. Code in the machine can read it, so prefer `--host` when you can. It takes no `--host`, `--header`, `--format`, `--allow` or `--github-app`. A new one needs `--only-sandbox <id>` and/or `--only-app <id>`; it takes no `--only-label` or `--all-sandboxes`, because code in any sandbox it reaches can read it. To change which machines get it, set it again with its value: `scope` is refused for it. Only a key that may run commands (`exec`) in each of its machines can set it; otherwise it is refused with `forbidden`. `--env` works as usual, but never with a variable that makes programs load or run code, such as `BASH_ENV`, `NODE_OPTIONS`, `GIT_SSH_COMMAND`, `PYTHON*` or `LD_*`. Its value is read exactly as it is, several lines and a last new line included, up to 64 KiB. Give `--exposed` on every set of such a secret. See [a secret the machine needs itself](./security#a-secret-the-machine-needs-itself).

`--expected-version N` works on every `set`. The secret is written only if it is still at version `N`. Every change counts a version: a new value, who gets it, its hosts or its variable. `0` means it must not exist yet. Otherwise nothing changes, and the error gives the current version. `get NAME` prints one secret: its kind (added on the way out, or real value), version, variable, hosts, scope, placeholder, size and last change. It never prints the value. `--json` prints the same as JSON.

`--jobs` keeps a copy that [scheduled jobs](./jobs#secrets-in-a-job) put into their run's environment. The copy is bound with `runtime jobs create --secret NAME`. Give `--host` too, and the secret goes to both. The jobs copy has its own versions (`rotate`), and it can be read back (`reveal`, with a key allowed to reveal). The sandboxes' copy is never readable. `rm` deletes every copy.

A jobs copy stored by an API key belongs to that key. Your other keys need it shared, with `runtime secrets share NAME --agent <id>` (repeat the flag; an id is the `principalId` from `runtime me`), `--all` for every key of yours, or `--none` for only the key that stored it. It replaces the list and prints who may use it now. A secret stored on the website belongs to every key.

## Scheduled jobs

```bash no-run
runtime jobs create nightly --cron "0 3 * * *" --timezone Europe/Berlin -- python3 /workspace/report.py
runtime jobs create once --at 2026-10-01T03:00:00Z --timeout 600 --attempts 3 -- bash -lc 'make report'
runtime jobs ls
runtime jobs runs "${job}"
runtime jobs logs "${job}" -f
runtime jobs trigger "${job}"
runtime jobs reschedule "${job}" --cron "30 4 * * 1-5" --timezone Europe/Berlin
runtime jobs pause "${job}"; runtime jobs resume "${job}"; runtime jobs cancel "${job}"
runtime jobs update "${job}" --image hub:latest --alert-email -- bash -lc 'make report'
```

A job runs its command in a fresh sandbox each time. It runs once (`--at`, an ISO time or `now`) or on five cron fields (`--cron`, in `--timezone`, UTC unless set). A schedule the CLI cannot read is refused. The error names the field or the timezone, such as `The minute field "61" is not a minute`.
A job takes the sandbox's size flags (`--vcpu`, `--memory`, `--disk`, `--cpu`). It also takes `--timeout` up to 60 minutes, and `--attempts` up to 5 for a run that exits non-zero. `--secret NAME[=ENV_NAME]` takes a secret stored with `--jobs`. `--max-cost` and `--max-total-cost` take dollars. `--image` starts each run from an image of yours. `--alert-webhook <url>` (signed with `--alert-secret NAME`, a secret your key may reveal) or `--alert-email` sends you one alert when `--alert-after` runs in a row fail. It sends another when a run succeeds again.
`runtime jobs update <id>` changes any of these, or the command after `--`, in place. Runs are paid sandboxes, billed at the sandbox rates. See [scheduled jobs](./jobs).

## SSH and port forwarding

```bash no-run
runtime sandboxes ssh "${id}"                          # a shell, as the sandbox user
runtime sandboxes ssh "${id}" -- make test             # one command; exits with its code
runtime sandboxes ssh config --install                 # `ssh <id>.runtime` from ssh, VS Code or JetBrains
runtime sandboxes code "${id}" --editor cursor          # open it in Cursor (or vscode, windsurf)
runtime sandboxes port-forward "${id}" 5432            # localhost:5432 here is port 5432 in the sandbox
runtime sandboxes port-forward "${id}" 3000 15432:5432 # several at once, local:remote
```

Both go through Runtime's API with your key, so the sandbox opens no port to the internet. A sandbox can be named by its id or its name. On first use, `ssh` creates an SSH key for this machine. It sends only the public half, into the one login it opens. `ssh proxy <id>` is the `ProxyCommand` the config uses.
`port-forward` carries any TCP port on the sandbox's loopback. It listens on `127.0.0.1` unless `--address` says otherwise, and it runs until Ctrl-C. Start the server with `spawn`, which keeps it running. A process started by `exec` ends with its command. When nothing listens on the port, `port-forward` says so. See [SSH and editors](./editors).

Away from your terminal, the **Terminal** tab on a sandbox's page at withruntime.com opens a shell in the browser. **Connect** on Home and Sandboxes copies `runtime sandboxes ssh` with the sandbox's name. The page's **Pause**, **Wake**, **Snapshot**, **Fork** and **Stop** buttons do what `runtime sandboxes pause`, `wake`, `snapshot`, `fork` and `stop` do.

## Images, volumes and snapshots

```bash no-run
img=$(runtime images build --pip pandas --apt jq --name data)   # or a folder: runtime images build . -t app:v1, or --from python:3.12-slim
vol=$(runtime volumes create --size-mib 10240 --name cache)
id=$(runtime sandboxes create --image "${img}" --volume "${vol}:/data")
base=$(runtime sandboxes create --image "${img}")
runtime sandboxes fork "${base}" --count 3              # three running copies of it
runtime sandboxes fork "${base}" --no-secrets           # a copy with none of its egress secrets
snap=$(runtime sandboxes snapshot "${base}" --name ready)
runtime sandboxes create --snapshot "${snap}"           # a copy, any time later
other=$(runtime sandboxes create --spread-from "${base}")   # starts on a server "${base}" is not on
runtime images ls; runtime volumes ls; runtime snapshots ls
runtime images get data; runtime volumes get "${vol}"; runtime snapshots get "${snap}"
runtime snapshots extend "${snap}" <days>              # keep it longer
runtime snapshots rm "${snap}"; runtime volumes rm "${vol}"; runtime images rm data
```

`runtime images build <folder>` builds the folder's Dockerfile (or `-f <file>`) with the folder as its context, as `docker build` does. Its `.dockerignore` applies. The context may be 100 MiB compressed. A rebuild uploads only what changed. `-t app:v2` names the image and tags it. Each build of a name is its next version, tagged `latest` when no tag is given. `--target`, `--build-arg K=V` and `--no-cache` work as they do in Docker. `--start <command>` with `--ready-port <port>` (or `--ready-command <command>`, which must exit 0) sets what a sandbox from the image runs and when its create command returns.
`runtime images versions <name>`, `tag`, `untag`, `logs --follow` and `rm` take an id, `name`, `name:tag` or `name@version`. So does `sandbox create --image`. `runtime images registry set <registry> --username <u>` reads a token from standard input and stores it for private images. See [custom images](./images).
Images, volumes and kept snapshots are charged as storage ([pricing](./pricing#snapshots-images-and-volumes)). A volume lives on one server. It is backed up off that server every day and whenever you ask. A backup restores as a new volume ([storage and backups](./storage)).
`runtime sandboxes stop` makes the sandbox write out what it wrote to its volumes first. A time limit or credit that runs out does the same. The sandbox's programs are frozen just before its end, and the write after that is not charged.
`runtime sandboxes mount <id> s3://bucket/prefix /data --secret NAME`, `mounts` and `unmount` mount your own S3, R2 or Google Cloud Storage bucket. The sandbox never holds the key. `--account-id` names an R2 bucket's Cloudflare account. `--endpoint` names any other S3-compatible store ([mount your own bucket](./storage#mount-your-own-bucket)).

A memory snapshot can be ready, and started from, while `compressionPending` is true. It is charged on its final compressed size. `backedUp` confirms that its off-server copy has been checked. See [snapshot storage](./storage#snapshots-survive-their-server).

Forks and snapshots:

- A fork or snapshot pauses a running sandbox for the length of the operation, then wakes it. A sandbox with volumes cannot be snapshotted. Snapshots are kept on the source's server, and copies start there while it has room. When it is full, a copy starts on another server once the snapshot is copied there. Each kept snapshot is also copied off its server after its final compressed form is ready.
- Copies run on what the account's new sandboxes run on (`--trial` and `--paid` are accepted and ignored). Copies keep the source's size and CPU, reserved or a raised floor. They are billed as a create with those settings would be. On an account without credit, a copy must fit the limits without credit.
- The snapshot a fork takes is deleted when the fork ends, whether every copy started or not. It is not billed, unless you pass `--keep-snapshot`.
- If a copy fails, the error names the copies that did start. They are deleted, and billed only when the error is a 4xx. A retry with the same idempotency key returns the same error.
- If a fork stops partway and leaves its source paused, the source stays paused. An account notice says so. Wake the source with `runtime sandboxes wake`.
- A snapshot is kept as long as you have credit, with no end date (7 days without credit), unless `--retention` gives 1 to 365 days.

## Scripts and agents: `--json`

Every command takes `--json` and prints one JSON value. Errors are written to standard error as `{"error": {"code", "message", "hint", "requestId"}}`, with a non-zero exit code.

```bash
id=$(runtime sandboxes create)
runtime sandboxes get "${id}" --json
runtime sandboxes exec "${id}" --json -- uname -a
runtime sandboxes stop "${id}" --json
```

`runtime sandboxes get --json` returns the sandbox in the same form as the API:

```json
{
  "id": "0b8f3c52-6d8e-4b1f-9c67-2f4e6c1d9a10",
  "kind": "sandbox",
  "name": null,
  "labels": {},
  "state": "running",
  "region": "us-east",
  "vcpu": 2,
  "memoryMiB": 4096,
  "diskMiB": 4096,
  "cpu": "shared",
  "cpuFloorMillis": 50,
  "timeoutSeconds": 0,
  "endsAt": null,
  "onLeaseEnd": "pause"
}
```

## Account

```bash
runtime whoami
runtime usage
runtime ls
```

- `runtime usage` prints the balance, the free usage left, and what each kind of resource was charged, in dollars. `--json` gives every figure in integer microdollars, with each resource's rates and CPU time. From 0.7.0, `--csv` exports one row per resource for a spreadsheet. Each row has its name, kind, state, creation time, its vCPUs and memory, how long it ran, the CPU seconds it used, what it was charged, and what running ones are about to use (`held_usd`), in dollars to the microdollar. It covers the newest 100 resources.
  For all visible resources over a date range, use `runtime usage export --since 2026-09-01T00:00:00Z
--until 2026-10-01T00:00:00Z > usage.csv`. This follows every page and prints the server's CSV with one header. It includes settled intervals at `since` and excludes those at `until`, by settlement time. Running time not yet settled is left out. Amounts remain exact. When it finishes, it says on stderr how far the range is final: no more charges will settle before that time. The CSV's `final` column says which resources can be charged nothing more.
  `--json` prints one complete server page per line. Each page rechecks current permissions and reads current settlements. See [export settled usage](./api#export-settled-usage).
- `runtime limits` says whether this machine's key is read-only and what its daily spending limit is. It shows what was used in the last 24 hours and what is left (0.3.1 and later). In versions after 0.8.4, it also shows the free usage left, as `runtime usage` does. The member who made the key, or an owner or admin, sets or changes the limit at [API keys](https://withruntime.com/account/keys). See [security](./security).
- On an account with a pilot, `runtime usage` shows its sandbox hours left. In versions after 0.11.1, `runtime whoami` and `runtime limits` also say how many sandboxes it runs free, and until when. Credit does not run a pilot's sandboxes. To extend a pilot or ask for more hours, write to support.
- `runtime ls` lists everything the account runs, every product.
- `runtime compare --from <provider>` says what the sandboxes you ran in the last 30 days would have cost at another provider. It uses the same vCPUs, memory and running time at that provider's published rates. It also says what you save a month (`--days` up to 90). When your first sandbox in the window is more recent than the window, the month is projected from the days since. The output says so. Sandboxes the free usage paid for are priced at the standard rates, and the output says how many there were. The providers are `e2b`, `daytona`, `vercel`, `modal`, `cloudflare`, `fly` (Sprites), `fly-machines` and the others in the [rate comparison](./pricing#published-rate-comparison). With no sandboxes yet, it prices an example and says so.
- `runtime switch --from <provider>` records the provider you are leaving, before you first add credit. `runtime switch` on its own shows the welcome match. Credit you add within 30 days of signing up is matched, up to $1,000 in total ([welcome match](./pricing#welcome-match)). The command also shows how much of the match is used and left, and how long is left. From withruntime 0.8.3, for E2B, Daytona, Vercel Sandbox and Blaxel, both commands also print the one import that runs your existing code on Runtime.
- `runtime account` lists the accounts this machine is connected to and marks the one in use. `runtime account switch <name>` uses another account for every command after it. `runtime account add` connects one more, chosen in the browser. See [teams](./teams).
- `runtime account close --confirm "<account name>"`, from 0.7.0, closes the account for good. Everything stops and is deleted, and every key stops working. It needs an owner's key for every product. See [closing the account](./teams#closing-the-account).
- `runtime audit` prints the account's audit log (`--action member.`, `--limit`, `--before <next>`), for a key made by an owner or admin.
- `runtime sso` shows the account's single sign-on: each identity provider, its domain and whether it is verified, and SCIM directory sync. An owner changes it on the website. See [single sign-on](./single-sign-on).
- `runtime sandboxes identity-token --audience sts.amazonaws.com [--lifetime 600]`, inside a sandbox, prints an OIDC token that names the sandbox. The token is for AWS, Google Cloud or your own API. It needs no API key. See [identity tokens](./identity-tokens).
- `runtime sandboxes metrics <id> [--range 1h]` shows a sandbox's CPU, memory, CPU wait and memory stalls, now and over the range (`15m`, `1h`, `6h`, `24h`, `7d`, `30d`). Unmeasured waiting is named rather than shown as zero.
- `runtime events [--sandbox <id>] [--type sandbox.stopped]` lists lifecycle events, newest first.
- `runtime webhooks create <url> [--events a,b]` sends signed lifecycle events to your URL and prints its secret once. `ls`, `test <id>`, `deliveries <id>`, `update <id> [--url <url>] [--events a,b] [--disable|--enable]`, `rotate-secret <id>`, `retry <deliveryId>` and `rm <id>` manage them.
- `runtime otel create <endpoint> [--header K=V]... [--signals logs,metrics]` pushes events and metrics to an OpenTelemetry endpoint. `ls`, `flush <id>` and `rm <id>` manage exports. See [metrics and webhooks](./observability).
- `runtime docs <page>` prints any page of these docs.
- `runtime mcp` serves Runtime's MCP tools on stdio, for agents that want a local command. See [MCP](./mcp).

If something is broken, missing or confusing, tell us. Feedback goes straight to the people building Runtime:

```bash no-run
runtime feedback "exec output lost its colours" --kind bug --detail "runtime sandboxes exec ... -- ls --color"
```

```bash no-run
runtime support "my sandbox will not wake"
```

See [feedback and support](./feedback-and-support).

## Sign out

```bash no-run
runtime logout
```

`logout` revokes this machine's connection. It does not stop running sandboxes.

## Domains, TCP ports, addresses, the tunnel and your own proxy

Paid accounts only. See [networking](./networking).

```bash no-run
runtime domains add app.example.com <sandbox> 3000   # prints the DNS records to set
runtime domains verify app.example.com               # live once the TXT record matches
runtime ports open <sandbox> 5432                    # prints address:port
runtime ips reserve                             # every sandbox sends from it
runtime networks wireguard create
runtime networks wireguard peer add office --route 10.0.0.0/16  # writes runtime.conf
sudo wg-quick up ./runtime.conf
runtime networks upstream-proxy set http://proxy.example.com:3128 --secret PROXY_AUTH
runtime networks private on                          # your sandboxes reach each other as <name>.sandbox.internal
runtime networks signed-requests on                  # your sandboxes can sign requests as Runtime's agents
runtime domains ls; runtime domains get app.example.com; runtime ips ls
runtime networks wireguard get                                  # its peers and each sandbox's address
runtime networks wireguard rm                                   # the tunnel and every peer
```

`runtime networks upstream-proxy` arrived in 0.7.0. `runtime networks private on|off|status` lets your sandboxes reach each other by name, for an account with a kept top-up. `runtime networks signed-requests on|off|status` lets them sign their HTTP requests as Runtime's agents, for an account with credit. Each command has its own help: `runtime domains help`, `runtime ports help`, `runtime ips help`, `runtime networks wireguard help`, `runtime networks help`.

The WireGuard configuration contains a private key. The CLI writes it with owner-only permissions and replaces an existing regular file atomically. It refuses a symbolic link or a directory as the output path. If publishing the configuration fails, the error names the protected draft to recover. Check the peer with `runtime networks wireguard get` before you create another one.


---

<!-- https://withruntime.com/docs/cloudflare-sandbox-alternative -->

# Runtime vs Cloudflare Sandbox

Runtime bills CPU by use, like Cloudflare's Sandbox SDK. It costs **53% less** for an agent that mostly waits on a model.

**The saving:** 1,000 one-minute runs of a 2 vCPU sandbox cost **$0.64 on Runtime
and $1.35 on Cloudflare**. At 100,000 runs a month that is $63.89 against
$135.04, **$71 a month saved**. You need no Worker to deploy and no $5 plan to
hold.

Comparing more than two? [Cloudflare Sandbox alternatives](/compare/cloudflare-sandbox-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **65% cheaper CPU.** Active CPU costs $0.025 a vCPU-hour on Runtime and $0.072 on Cloudflare. Memory is cheaper too, at $0.0075 per GiB-hour
  against $0.009.
- **Waiting costs storage, not compute.** A Runtime sandbox left idle for 300 seconds pauses by
  itself and keeps its memory. It then pays $0.08 per GB (10⁹ bytes) a month
  until a request wakes it.
- **An uptime promise that pays itself.** Paid accounts are promised
  99% API uptime each month. A month below it returns 10% of that
  month's charges as credit. No claim is needed ([Uptime Promise](/legal/sla)).
- **Memory sized to the job.** Cloudflare needs at least 3 GiB per vCPU, so a
  2 vCPU sandbox pays for 6 GiB. On Runtime you choose vCPUs and memory
  separately and pay for no more.
- **Work survives idle time.** A paused Runtime sandbox wakes with its files,
  memory and running processes, kept while you have credit. A Cloudflare sandbox
  restores saved files from filesystem-only snapshots in public beta. Memory
  and processes restart. Snapshots expire 30 days after creation or last restore.
- **A desktop built in.** Start a Linux desktop in any sandbox and drive it
  with clicks, keys and screenshots. Cloudflare removed its Sandbox SDK desktop
  in version 0.10.2, in June 2026.
- **Call it from any backend, with no platform to join.** Runtime is an API
  with JavaScript, Python, Go, Ruby and Java SDKs, a CLI and an [MCP server](./mcp). Prepaid
  credit from $10 is the whole account. The Sandbox SDK runs inside a Worker on
  the Workers Paid plan, deployed with Wrangler and a local Docker build.
- **Keys the sandbox never sees.** Store an API key once. The sandbox holds a
  placeholder. Runtime's proxy adds the value only to HTTPS requests to the
  hosts you name. A prompt injection has nothing to leak ([security](./security)).
- **Your credit matched.** Credit you add within 30 days of signing up is matched, up to $1,000 in total
  ([welcome match](./pricing#welcome-match)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, snapshots and forks with memory, private
previews, metrics, webhooks, OpenTelemetry export, S3, R2 and GCS bucket mounts, identity tokens for AWS and Google Cloud and free
single sign-on. Paid accounts add custom domains, TCP ports, dedicated outbound
addresses and WireGuard private networks. See [products](./products).

## At a glance

Cloudflare's sandboxes run on Cloudflare Containers, so their prices are the
Containers prices. Cloudflare's figures come from its public pricing and
documentation, checked 25 October 2026.

|                | Runtime                                                                                   | Cloudflare Sandbox SDK                                               |
| -------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Isolation      | Firecracker microVM, own kernel                                                           | A container in its own VM                                            |
| CPU billing    | $0.025 per vCPU-hour of measured CPU, with a small floor                            | $0.072 per active vCPU-hour, metered in 10 ms steps |
| Memory billing | $0.0075 per reserved GiB-hour                                                     | $0.009 per provisioned GiB-hour                  |
| Disk           | Included while running; paused storage $0.08 per GB (10⁹ bytes) a month | $0.000252 per provisioned GB-hour                     |
| Plan fee       | None; prepaid credit from $10                                                   | Workers Paid, at least $5 a month      |
| Free start     | 100 free hours of a 1 GB machine in the first 30 days, no card                                        | No free tier; the plan includes 375 vCPU-minutes a month             |
| Sizes          | Up to 16 vCPUs and 64 GiB paid, chosen apart                            | Up to 4 vCPUs, 12 GiB and 20 GB; at least 3 GiB per vCPU             |
| When idle      | Pause keeps files and memory; kept while you have credit                                  | Filesystem-only snapshots; processes restart                         |
| Interfaces     | API, CLI, MCP server, JavaScript, Python, Go, Ruby and Java SDKs                          | A TypeScript SDK called from a Cloudflare Worker                     |

## Cost for the same job

Take 1,000 runs of a 2 vCPU sandbox. Each run lasts 60 seconds and keeps the CPU
busy for 20 CPU-seconds. This is an agent that spends most of its time waiting for a
model. Runtime gets 4 GiB. Cloudflare's smallest custom 2 vCPU size has 6 GiB, because
a custom size needs at least 3 GiB per vCPU. It gets 12 GB of disk, the size in
Cloudflare's own example.

```
Runtime     CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
            Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
            Total                                        $0.64

Cloudflare  CPU    1,000 × 20 s × $0.000020           = $0.40
            Memory 1,000 × 60 s × 6 × $0.0000025      = $0.90
            Disk   1,000 × 60 s × 12 × $0.00000007    = $0.05
            Total                                        $1.35
```

- **Saving:** 53%, or $0.71 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $135.04 on
  Cloudflare.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on
  Runtime against $3.35 on Cloudflare, a 60% saving.
- **Smaller shapes:** Cloudflare's `standard-1` (half a vCPU, 4 GiB, 8 GB of
  disk) costs $1.03 for the same runs. Runtime's nearest shape, 1 vCPU and
  4 GiB, still costs $0.64, because CPU is billed as measured.

The Cloudflare figure assumes each sandbox is destroyed when its run ends. One
left alone keeps billing memory and disk until its inactivity timeout ends.
Workers requests, Durable Object time, the $5 plan minimum, network, taxes and
free allowances are left out of both. On Runtime, inbound traffic is free. Each
account's first 100 GiB out a month is free. After that, outbound traffic costs $0.02 per GB (10⁹ bytes). See
[pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Cloudflare calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### Change the import

Runtime's SDK runs a Worker written for Cloudflare's 0.x `@cloudflare/sandbox`
API, as this page describes from SDK version 0.18.0. The switch is the import,
one config block and one secret, not literally one line. Change the
package name in both lines that name it:

```ts no-run
import { getSandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
export { Sandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
```

In `wrangler.jsonc` (or `wrangler.toml`), delete the `containers` block. The
sandbox runs on Runtime, so there is no image to build and no Docker on your
machine. Keep the `Sandbox` Durable Object binding, its migration and
`nodejs_compat` as they are.

```jsonc no-run
"containers": [
  { "class_name": "Sandbox", "image": "./Dockerfile", "instance_type": "lite", "max_instances": 1 }
],
```

Create a key at https://withruntime.com/account/keys and store it as a Worker
secret, never in the config or the source:

```bash no-run
npx wrangler secret put RUNTIME_API_KEY
```

`getSandbox(env.Sandbox, "my-sandbox")` then reaches a Runtime sandbox kept
for that name. `exec`, streaming, files, background processes, the code
interpreter, sessions, `gitCheckout` and `exposePort` with `proxyToSandbox`
work as Cloudflare documents them. On 18 October 2026 Cloudflare's get-started
Worker, its `minimal` and `alpine` examples and the runnable 0.x examples from
its docs ran unchanged under `wrangler dev` on Runtime sandboxes, with only
those changes.

What works differently:

- **Calls Runtime has no counterpart for refuse by name**, before anything
  happens. The message says what to use instead: backups (Runtime's
  snapshots), tunnels and `wsConnect` (the URL `exposePort` returns),
  terminals, outbound interception in a `Sandbox` subclass (the sandbox's
  network rules and secrets), and container settings such as
  `containerTimeouts` and `transport`.
- **Process ids are Runtime's.** `startProcess(cmd, { processId })` and
  `autoCleanup` refuse, and a process's `pid` is not reported.
- **At most 4 code contexts per sandbox.** Cloudflare's container has no fixed
  number. A fifth `createCodeContext` throws and says to delete one with
  `deleteCodeContext()`. `runCode` without a context uses one per language.
- **Errors keep their message.** Across a Durable Object call, an error arrives
  with its message and without its `code` field, on Cloudflare too. So match
  on the message.

Version 1.0 of `@cloudflare/sandbox` drops `getSandbox` and the `Sandbox`
class: your own Durable Object starts the Container and runs
`this.ctx.container.exec([...])`, and the package keeps only `Files`, `S3Mount`
and `DirectoryBackup`. On Runtime, `container.exec(["sh", "task.sh"])` is
`box.exec(["sh", "task.sh"])`, and `new Files(container).writeFile(path, data)`
is `box.files.write(path, data)`.

### Or port the calls

Cloudflare, inside a Worker, with the 0.x `@cloudflare/sandbox` API:

```js
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request, env) {
    const sandbox = getSandbox(env.Sandbox, "my-sandbox");
    const result = await sandbox.exec("python3 -c 'print(sum([125, 250, 375]))'");
    await sandbox.destroy();
    return Response.json({ stdout: result.stdout });
  },
};
```

Runtime, from any server:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

### Calling Runtime from a Worker

If your application stays on Workers, the Worker can call Runtime itself. This
needs SDK version 0.4.0 or later, and the `nodejs_compat` compatibility flag in
your Wrangler config:

```toml
compatibility_flags = ["nodejs_compat"]
```

A Worker has no saved login. So create a key at
https://withruntime.com/account/keys and store it as a Worker secret, never in
`wrangler.toml` or the source:

```bash no-run
npx wrangler secret put RUNTIME_API_KEY
```

Then create, run and stop:

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

type Env = { RUNTIME_API_KEY: string };

export default {
  async fetch(_request: Request, env: Env): Promise<Response> {
    const runtime = new Runtime({ apiKey: env.RUNTIME_API_KEY });
    // A backstop: the sandbox stops after 5 minutes even if this request is cut off.
    const box = await runtime.sandboxes.create({
      timeoutSeconds: 300,
      onLeaseEnd: "stop",
    });
    try {
      await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
      const result = await box.exec("python3 /workspace/invoice.py", { check: true });
      return Response.json({ stdout: result.stdout });
    } finally {
      await box.stop();
    }
  },
};
```

Earlier SDK versions fail inside a Worker with `connection_error`. Without
`nodejs_compat`, the Worker does not start. This sample is type-checked against
the SDK. On 23 September 2026 it ran under `wrangler dev`: it created a
sandbox, ran the command and stopped it.

What does not carry over:

- **The Durable Object binding.** Runtime sandboxes are not part of your Worker,
  so the `Sandbox` export, its Durable Object binding and the `containers`
  entry are not needed for Runtime. Remove them only when nothing uses
  Cloudflare's sandboxes any more.
- **Sandboxes by name.** `getSandbox(env.Sandbox, "my-sandbox")` becomes
  `Sandbox.getOrCreate("my-sandbox", { client: runtime })`. It returns the
  sandbox with that name, woken if it is paused, or creates it. Names are
  unique in your Runtime account, so no KV entry is needed to find it again.
- **`proxyToSandbox`.** Cloudflare routes a sandbox's preview URLs through your
  Worker. Runtime serves a port from its own address instead:
  `box.previews.create(port)` returns an HTTPS URL under `runtimehost.com` and
  a token (see [share a port](./javascript#share-a-port)). The Worker does not proxy it.

## When Cloudflare may fit better

- **Placement near users.** A Cloudflare sandbox starts in the nearest location
  that has its image, across Cloudflare's network. Runtime runs in one US
  region.
- **Your app already lives on Workers.** Sandboxes then share its account,
  billing and bindings. Filesystem-only snapshots can restore saved files, while R2 bucket data
  outlives individual instances.
- **Very large fleets.** A Cloudflare account can run 1,500 vCPUs and 6 TiB of
  memory at the same time. A paid Runtime account runs 100 sandboxes, 200 vCPUs and 400 GiB
  at the same time, raised on request.

## Sources

Checked 23 September 2026.

Cloudflare's snapshot behavior checked 30 September 2026.

- [Cloudflare sandbox lifetime](https://developers.cloudflare.com/sandbox/concepts/lifetime/)
- [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/)
- [Sandbox SDK pricing](https://developers.cloudflare.com/sandbox/platform/pricing/)
- [Containers limits and instance types](https://developers.cloudflare.com/containers/platform/limits/)
- [Containers architecture](https://developers.cloudflare.com/containers/concepts/architecture/)
- [Sandbox lifecycle](https://developers.cloudflare.com/sandbox/concepts/sandboxes/)
  and [sandbox options](https://developers.cloudflare.com/sandbox/configuration/sandbox-options/)
- [Sandbox backup and restore](https://developers.cloudflare.com/sandbox/guides/backup-restore/)
- [Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/)
- [Deprecating Sandbox SDK features](https://developers.cloudflare.com/changelog/post/2026-06-09-deprecating-sandbox-sdk-features/)
- [Containers and Sandboxes generally available](https://developers.cloudflare.com/changelog/post/2026-04-13-containers-sandbox-ga/)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/codesandbox-alternative -->

# Runtime vs CodeSandbox

Runtime runs agent code in Firecracker microVMs, like the CodeSandbox SDK, and costs **74% less** for an agent that mostly waits on a model.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $2.48 on CodeSandbox**. At 100,000 runs a month that is $63.89
against $247.67, **$184 a month saved**.

If you are weighing more than two, [CodeSandbox SDK alternatives](/compare/codesandbox-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** CodeSandbox bills a VM's size in credits for
  as long as it runs. Runtime measures the CPU your code actually uses, so time
  spent waiting on a model costs only a small floor, a twentieth of a vCPU.
- **Idle time bills only storage.** A Runtime sandbox pauses itself after 300 seconds with no activity, keeps its memory and processes, and runs its next command when a request wakes it. While paused, it pays $0.08 per GB (10⁹
  bytes) of saved state a month.
- **A written uptime promise.** 99% API uptime a month for paid accounts,
  measured from outside, and 10% of a short month's charges back as credit
  automatically ([Uptime Promise](/legal/sla)).
- **Cheaper even when busy.** With both CPUs working the whole time, the example
  job costs $1.33 on Runtime and $2.48 on CodeSandbox.
- **Billed by the second.** CodeSandbox rounds each VM's runtime up to the next
  minute. Runtime compute has no one-minute minimum.
- **Any shape.** CodeSandbox sells fixed VM sizes. On Runtime you choose vCPUs
  and memory for each sandbox and pay for no more.
- **No plan fee for concurrency.** More than 10 VMs at the same time on CodeSandbox
  needs the $170-a-month Scale plan. Runtime has no plan: a
  paid account runs 100 sandboxes at the same time, and support
  raises the limit on request.
- **Secrets stay outside the sandbox.** Code inside sees a placeholder; the
  real key is added at the egress proxy, only on HTTPS to the hosts you allow
  ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file, and the [MCP server](./mcp) reuses the same
  connection.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, snapshots and forks with memory, private
previews, a Linux desktop, metrics, webhooks, OpenTelemetry export, S3, R2 and
GCS bucket mounts, identity tokens for AWS and
Google Cloud and free single sign-on. Paid accounts add custom domains, TCP
ports, dedicated outbound addresses and WireGuard private networks. See
[products](./products).

## At a glance

CodeSandbox's figures come from the Together Code Sandbox documentation, which
covers the CodeSandbox SDK, checked 25 October 2026.

|                  | Runtime                                                        | CodeSandbox SDK                                                                   |
| ---------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Isolation        | Firecracker microVM, own kernel                                | Firecracker microVM                                                               |
| CPU billing      | $0.025 per vCPU-hour of measured CPU, with a small floor | By VM size: Nano (2 cores, 4 GB) is $0.1486 an hour             |
| Memory billing   | $0.0075 per reserved GiB-hour                          | Inside the VM size                                                                |
| Billing unit     | By the second                                                  | By the minute, rounded up                                                         |
| Plan fee         | None; prepaid credit from $10                        | Build free with 10 VMs at the same time; Scale $170 a month |
| Free start       | 100 free hours of a 1 GB machine in the first 30 days, no card             | The free Build plan                                                               |
| Snapshots, forks | Files, memory and running processes                            | Memory snapshot and restore                                                       |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds: an agent that spends most of its time
waiting for a model. On CodeSandbox that is a Nano VM, 10 credits an hour at
$0.01486 a credit.

```
Runtime      CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
             Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
             Total                                        $0.64

CodeSandbox  Size   1,000 × 60 s / 3,600 × $0.1486     = $2.48
```

- **Saving:** 74%, or $1.84 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $247.67 on
  CodeSandbox.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $2.48 on CodeSandbox.

Each run here is a whole minute, so CodeSandbox's rounding adds nothing; a
40-second run would still be billed as a minute there. Plan fees, storage,
network and taxes are left out of both. On Runtime, inbound traffic is free, and
each account's first 100 GiB out a month is free, then $0.02 per GB (10⁹ bytes). See
[pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the CodeSandbox calls on a branch, tests them on the free usage, and
tells you what you save each month. Your old code stays on the main branch until
you merge.

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

## When CodeSandbox may fit better

- **Very large machines.** CodeSandbox VMs go up to 64 cores and 128 GB.
- **Many VMs on a plan.** The Scale plan runs 250 VMs at the same time.

## Sources

Checked 23 September 2026. The rates are from Together's documentation of the
CodeSandbox SDK; CodeSandbox is a Together company.

- [Together: CodeSandbox SDK](https://docs.together.ai/docs/together-code-sandbox-legacy)
- [CodeSandbox SDK pricing](https://codesandbox.io/docs/sdk/pricing)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/company-rollout -->

# Roll Runtime out to your company

One Runtime account can hold your whole company: its people, their agents, one
prepaid balance and one audit log. This guide gives the order to set it up in.
Each step links to the guide with the details.

Single sign-on, directory sync, roles and the audit log are free on every
account. There is no seat fee and no plan to buy.

## 1. Choose the owner

The person who signs in first owns the account. Owners are the only ones who
connect single sign-on, make other owners and close the account.

- Make at least two owners, so the company never depends on one person. At
  [Members](https://withruntime.com/account/members), invite the second person,
  then pick **Owner** in their row.
- Owners always keep Google and email-link sign-in, even when single sign-on is
  required, so a broken identity provider cannot lock you out.

## 2. Fund the account

Everyone in the account spends the same prepaid balance.

- An owner, an admin or a billing member adds credit by card at
  [Usage & billing](https://withruntime.com/account/billing). There is no
  subscription; the page shows how long the credit lasts at this month's pace,
  and each purchase links to its Stripe receipt.
- Give whoever pays the bills the **billing** role. They add credit and see
  payments, and cannot start anything or make keys.
- The first top-up lifts the account from the [free usage](./included-usage) to the paid
  limits. While it is not refunded, it also opens every outbound port,
  custom domains, TCP ports, public previews and private networks
  ([pricing](./pricing#how-many-at-once)).
- Credit you add within 30 days of signing up is matched, up to $1,000 in total ([welcome match](./pricing#welcome-match)).

## 3. Connect your identity provider

Skip this step if you only need a few people; invitations work without it.

At [Single sign-on](https://withruntime.com/account/single-sign-on), an owner:

1. Creates an app in Okta, Microsoft Entra ID, Google Workspace or any SAML 2.0
   or OpenID Connect provider, using the values the page shows.
2. Proves the company's email domain with one DNS TXT record.
3. Chooses the role people get when they first sign in. It is developer unless
   you change it.

Then, if you want:

- **Require single sign-on**, so members other than owners can come in only
  through your provider.
- **Turn on directory sync (SCIM)** in Okta or Entra ID. Your directory then
  adds people, sets their roles from its groups and removes them the moment
  they leave, and revokes every key they made.

The provider-by-provider steps are in [single sign-on](./single-sign-on).

## 4. Bring people in

Pick a role for each person. The full table is in
[teams](./teams#roles).

| Role      | Give it to                                      |
| --------- | ----------------------------------------------- |
| Owner     | Two or three people who own the relationship    |
| Admin     | Team leads who manage people, keys and settings |
| Developer | Engineers who run agents and sandboxes          |
| Billing   | Finance, who add credit and read payments       |

- **With single sign-on,** people join on their first sign-in with the default
  role, or with the role their directory group gives.
- **Without it,** an owner or admin invites each person by email at
  [Members](https://withruntime.com/account/members). The link works once, only
  for that address.
- Someone who already uses Runtime keeps their own account and joins yours as
  well. They switch between the two from the account name at the top of the
  sidebar, or with `runtime account switch` in the CLI.

## 5. Give each agent its own key

Keys belong to the account, not to a person, and everyone in it can see every
key at [API keys](https://withruntime.com/account/keys).

- **One key per agent or application.** The audit log and the bill then say
  which one did what, and you can revoke one without stopping the rest.
- **A daily spending limit on every key that spends.** It is the most that key
  can commit in 24 hours. Only a person can set it, on the website; no key can
  raise its own ([read-only keys and daily limits](./security#read-only-keys-and-daily-limits)).
- **Read-only keys for dashboards, monitoring and CI checks.** They see the
  whole account and cannot start or change anything.
- **Account-wide keys for shared services.** A normal key sees only what it
  made. An owner or admin can make a key account-wide, so a service reaches
  every sandbox in the account ([keys in a team](./teams#keys-in-a-team)).
- **Secrets the sandboxes never see.** Store company API keys once as account
  secrets. Runtime adds them to outbound requests for the hosts you name
  ([secrets](./security#secrets-sandboxes-never-see)).
- **Identity tokens instead of stored cloud keys.** Sandboxes can reach AWS,
  Google Cloud and others with signed tokens ([identity tokens](./identity-tokens)).

A key can never do more than the person who made it. Change that person's role
and their keys change with it on the next request.

## 6. Watch it

- **Audit log.** Owners and admins read every change to members, keys, credit,
  security settings and single sign-on at
  [Audit log](https://withruntime.com/account/audit), or from code with
  `runtime audit`. Entries cannot be edited
  ([audit log](./teams#audit-log)).
- **Spending.** [Usage & billing](https://withruntime.com/account/billing)
  shows what each product cost each day.
- **Events in your own tools.** Send lifecycle events to your URL with
  [webhooks](./observability), or logs and metrics to your collector over
  OpenTelemetry.

## 7. When someone leaves

- **With directory sync,** deactivate them in your directory. They lose access
  immediately, and every key they made is revoked in the same step.
- **Without it,** an owner or admin chooses **Remove** in their row at
  [Members](https://withruntime.com/account/members). The effect is the same.
- What they created, such as sandboxes, volumes and images, stays with the
  account.

## Before you go to production

- Read [security](./security#before-production-traffic) for isolation, network
  rules and the checks to run first.
- Need more sandboxes or capacity than the paid limits? Write to support with
  the numbers ([feedback and support](./feedback-and-support)).


---

<!-- https://withruntime.com/docs/computesdk -->

# Runtime for ComputeSDK

Create Runtime sandboxes through ComputeSDK's provider interface. Run commands, stream output, and use files, preview URLs and snapshots.

`@computesdk/runtime` is a ComputeSDK provider, like its E2B, Modal or Daytona
providers. Change the provider and the same `compute.sandbox` code runs in a
Firecracker microVM with its own kernel. It is built on Runtime's TypeScript
SDK, `withruntime`.

## Install

ComputeSDK publishes its providers to npm from its own repository. The Runtime
provider is one of them, as `@computesdk/runtime` since 28 September 2026:

```bash no-run
npm install computesdk @computesdk/runtime
```

It needs Node.js 22.12 or later. The key comes from `RUNTIME_API_KEY`, or from
`npx withruntime login` on this machine, as in the rest of the SDK.

## Example

```js
import { runtime } from "@computesdk/runtime";

const compute = runtime({ apiKey: process.env.RUNTIME_API_KEY });
const sandbox = await compute.sandbox.create({ envs: { NODE_ENV: "production" } });
try {
  const result = await sandbox.runCommand("node --version");
  console.log(result.stdout);

  await sandbox.runCommand("python3 -m http.server 3000", { background: true });
  console.log(await sandbox.getUrl({ port: 3000 }));
} finally {
  await sandbox.destroy();
}
```

`sandbox.getInstance()` returns the `withruntime` sandbox. Use it for anything
ComputeSDK's interface does not cover: processes, terminals, network rules,
the desktop and the rest.

## Options

Every option is optional.

| Option              | What it does                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `apiKey`            | The API key; defaults to `RUNTIME_API_KEY`, then the key `npx withruntime login` saved                       |
| `baseUrl`           | The API origin; defaults to `RUNTIME_API_URL`, then `https://api.withruntime.com`                            |
| `create`            | Defaults for every create: `funding`, `region`, `image`, `vcpu`, memory, disk, `network` and any other field |
| `previewVisibility` | `private` (default): the URL from `getUrl` carries its token; `public`: anyone with the address, paid only   |
| `previewTtlSeconds` | How long a private preview's token lasts, 60 seconds to 7 days; one day by default                           |

`compute.sandbox.create()` takes ComputeSDK's own options and maps them:
`templateId` is a Runtime [image](./images), `snapshotId` a Runtime snapshot,
`metadata` becomes labels, `timeout` a time limit, `vcpus`, `memoryMiB` and
`diskMiB` the size, and `envs` is set on every command the provider runs in
that sandbox.

## How ComputeSDK's calls behave

- **Commands** run under `bash -c`, for 60 seconds unless `timeout` says
  otherwise (up to 24 hours). One that runs past its timeout returns exit code
  124 with its output so far. `background: true` starts a Runtime process and
  returns immediately.
- **Streaming.** `onStdout` and `onStderr` receive output through Runtime's API
  as the command writes it, so ComputeSDK needs no port inside the sandbox.
- **Files** use Runtime's file calls, not shell commands.
- **`getUrl`** shares the port as a private
  [preview](./javascript#share-a-port) and returns a link that carries its
  token. The link works unchanged in a browser, `fetch`, `curl` or a
  WebSocket client, until the token expires.
- **`destroy`** stops the sandbox. `getById` returns `null` for a stopped one,
  and a paused one wakes when used.
- **Snapshots** keep files, memory and running processes; `create`, `list` and
  `delete` work, and `snapshotId` starts a sandbox from one.
- **`envs` from create** are held by the provider object that created the
  sandbox. A sandbox reached through `getById` or `list` does not have them;
  pass `env` to `runCommand` there.

## What was verified

On 25 September 2026, the provider was built in a clone of ComputeSDK's
repository (commit `d52afb5`) against `withruntime` 0.5.1 from npm. There, its
CommonJS and ESM builds, type declarations, typecheck and lint passed. 28 unit
tests passed with the Runtime SDK mocked. ComputeSDK's shared provider suite
passed against ComputeSDK's own mock sandbox. Both builds loaded `withruntime`
and called a local stand-in for Runtime's API.

On 11 October 2026 the published `@computesdk/runtime` 0.1.4 ran against
Runtime's API: create, a command, streamed output, a file written and read, a
timeout's exit code 124, a background command, `list`, `getById` and `destroy`.


---

<!-- https://withruntime.com/docs/daytona-alternative -->

# Runtime vs Daytona

Runtime gives every agent sandbox its own microVM kernel. For an agent that mostly waits on a model, it costs **77% less than Daytona**.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $2.76 on Daytona**. At 100,000 runs a month, that is $63.89 against
$276.00, **$212 a month saved**. Your Daytona code keeps working. Change one import.

Comparing more than two providers? [Daytona alternatives](/compare/daytona-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Daytona bills every vCPU for as long as the
  sandbox runs. Runtime measures the CPU your code actually uses. Time spent
  waiting on a model costs only a small floor, a twentieth of a vCPU.
- **It pauses itself when idle.** After 300 seconds with no request, command, connection,
  traffic or CPU use, a Runtime sandbox pauses. While paused, it pays only paused storage,
  $0.08 per GB (10⁹ bytes) a month. The next request wakes it. Its processes keep running.
- **An uptime promise that pays itself.** Paid accounts get
  99% API uptime each month. A month below that returns 10% of that
  month's charges as credit. No claim is needed ([Uptime Promise](/legal/sla)).
- **Lower rates on both meters.** $0.025 per vCPU-hour, against Daytona's
  $0.0504, and $0.0075 per GiB-hour of memory, against $0.0162. Even with every
  CPU busy the whole time, the example job costs $1.33 on Runtime and $2.76 on
  Daytona.
- **A microVM every time.** Every Runtime sandbox is a Firecracker microVM with
  its own kernel, and every one can pause with its memory. Daytona's default
  sandbox is a container. Pausing with memory needs its VM class.
- **Disk included while running.** Daytona charges for disk past 5 GiB whether
  the sandbox runs or not. Runtime's disk is part of a running sandbox.
- **A one-line switch.** `withruntime/daytona` runs code written for Daytona's
  SDK, in JavaScript and Python: sessions, files, git, snapshots built from
  Daytona's `Image`, and the code interpreter. Credit you add within 30 days of signing up is matched, up to $1,000 in total.
- **Teams at no extra charge.** Single sign-on over SAML or OIDC (Okta,
  Microsoft Entra ID, Google Workspace), SCIM, roles and an audit log come with
  every account ([single sign-on](./single-sign-on)). Daytona's single sign-on is OIDC,
  on its Enterprise plan.
- **Custom domains built in.** A paid account serves a sandbox port at your own
  hostname, with HTTPS, from one command ([custom domains](./networking#custom-domains)).
  On Daytona, a preview under your own domain needs a preview proxy you deploy
  and run yourself.
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Give an agent a read-only key or a daily spending
  limit per key. Cap any sandbox's total cost with `maxTotalCostMicros`. Every write takes an
  idempotency key, and the SDKs retry with it. A lost response never creates
  a second sandbox.

**Also included:** a code interpreter, network allow and deny lists, secrets the
sandbox never sees, custom images, volumes backed up daily, snapshots and forks
with memory, private previews, a Linux desktop, metrics, webhooks, OpenTelemetry
export, S3, R2 and GCS bucket mounts, and identity
tokens for AWS and Google Cloud. Paid accounts add TCP ports, dedicated outbound
addresses and WireGuard private networks. See [products](./products).

## At a glance

Daytona's figures come from its public pricing and documentation, checked
25 October 2026.

|                  | Runtime                                                                                   | Daytona                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Isolation        | Firecracker microVM for every sandbox                                                     | Containers by default; VM sandboxes as a separate class                   |
| CPU billing      | $0.025 per vCPU-hour of measured CPU, with a small floor                            | $0.0504 per allocated vCPU-hour                              |
| Memory billing   | $0.0075 per reserved GiB-hour                                                     | $0.0162 per GiB-hour                                      |
| Disk             | Included while running; paused storage $0.08 per GB (10⁹ bytes) a month | First 5 GiB free, then $0.000108 per GiB-hour, stopped or not |
| Plan fee         | None; prepaid credit from $10                                                   | None published                                                            |
| Free start       | 100 free hours of a 1 GB machine in the first 30 days, no card                                        | $200 of compute                                        |
| Pause and resume | Files and memory, every sandbox                                                           | Files and memory on VM sandboxes                                          |
| Snapshots, forks | Copies of a running sandbox, with memory and processes                                    | Memory snapshots on VM sandboxes                                          |
| Agent sign-in    | Browser approval; no key in the agent's config                                            | API key                                                                   |
| Port URLs        | Private with a token by default                                                           | Private to your organization unless the sandbox is public                 |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most of its time
waiting for a model.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
         Total                                        $0.64

Daytona  CPU    1,000 × 60 s / 3,600 × 2 × $0.0504 = $1.68
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0162 = $1.08
         Total                                        $2.76
```

- **Saving:** 77%, or $2.12 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $276.00 on Daytona.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on
  Runtime against $2.76 on Daytona. At this size, Runtime is cheaper however busy the
  sandbox is.

Disk, network, taxes and free credits are excluded from both.
`runtime compare --from daytona` prices your own usage the same way. It prices
sandboxes the free usage paid for at the standard rates, so free usage never
counts as a saving. On Runtime, inbound traffic is free. Each account's
first 100 GiB out a month is free, then $0.02 per GB (10⁹ bytes). See [pricing](./pricing)
for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Daytona calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### Change one import

Runtime's SDK runs code written for Daytona's SDK. Change the import and set
`RUNTIME_API_KEY`, or run `npx withruntime login` once:

```ts no-run
import { Daytona } from "withruntime/daytona"; // was: from "@daytona/sdk"
```

```python no-run
from withruntime.daytona import Daytona  # was: from daytona import Daytona
```

Sandboxes get Daytona's defaults: 1 vCPU, 1 GiB of memory and a 3 GiB disk,
pausing after 15 minutes without calls. `stop()` pauses a sandbox with its
files and its memory, and `start()` carries on. Sandboxes use the free usage first, then prepaid credit.

PTY sessions, computer use, a `user` from your image, an `autoStopInterval`
over an hour (or `0`), and list filters and sorting work as on Daytona. A call
Runtime handles differently, such as GPUs or other regions, throws
`NotSupportedError` before anything happens. It names what to use instead.
`DAYTONA.md` in the package lists every mapping.

### Or port the calls

The calls map one to one. Daytona:

```js
import { Daytona } from "@daytonaio/sdk";
const daytona = new Daytona();
const sandbox = await daytona.create();
const response = await sandbox.process.executeCommand("python3 -c 'print(sum([125, 250, 375]))'");
await sandbox.delete();
```

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

## When Daytona may fit better

- **GPUs and Windows.** Daytona offers GPU sandboxes and Windows machines.
  Runtime runs Linux on CPUs.
- **Regions.** Daytona runs in the US and the EU. Runtime runs in one US
  region.

## Sources

Checked 23 September 2026; single sign-on and custom domains checked
27 September 2026; port URLs checked 3 November 2026.

- [Daytona pricing](https://www.daytona.io/pricing)
- [Daytona organization SSO](https://www.daytona.io/docs/en/sso)
- [Daytona custom preview proxy](https://www.daytona.io/docs/en/custom-preview-proxy)
- [Daytona sandboxes](https://www.daytona.io/docs/en/sandboxes)
- [Daytona on microVMs, pause and fork](https://www.daytona.io/dotfiles/vms-pause-and-fork)
- [Daytona preview links](https://www.daytona.io/docs/en/preview)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/e2b-alternative -->

# Runtime vs E2B

Runtime runs agent code in Firecracker microVMs, like E2B. It costs **77% less** for an agent that spends most of its time waiting on a model.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $2.76 on E2B**. At 100,000 runs a month that is $63.89 against
$276.00, **$212 a month saved**. Your E2B code keeps working. Change one import.

Comparing more than two? [E2B alternatives](/compare/e2b-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** E2B bills every vCPU for as long as the
  sandbox runs. Runtime measures the CPU your code actually uses. Time spent
  waiting on a model costs only a small floor, a twentieth of a vCPU.
- **Waiting costs storage, not compute.** A Runtime sandbox left idle for 300 seconds pauses by
  itself and keeps its memory. It then pays $0.08 per GB (10⁹ bytes) a month
  until a request wakes it.
- **A written uptime promise.** 99% API uptime a month for paid accounts,
  measured from outside. 10% of a short month's charges comes back as credit
  automatically ([Uptime Promise](/legal/sla)).
- **Lower rates on both meters.** $0.025 per vCPU-hour against E2B's $0.0504,
  and $0.0075 per GiB-hour of memory against $0.0162. Even with every CPU busy
  the whole time, the example job costs $1.33 on Runtime and $2.76 on E2B.
- **No plan fee for long sessions.** E2B caps a session at 1 hour on Hobby and
  needs the $150-a-month Pro plan for 24. A Runtime sandbox has no time limit.
  It runs while it works. It needs no plan. You add prepaid credit from $10.
- **A one-line switch.** `withruntime/e2b` runs code written for E2B's SDK, in
  JavaScript and Python, including the code interpreter. Credit you add within 30 days of signing up is matched, up to $1,000 in total.
- **Teams at no extra charge.** Single sign-on over SAML or OIDC (Okta,
  Microsoft Entra ID, Google Workspace), SCIM, roles and an audit log come with
  every account ([single sign-on](./single-sign-on)). E2B lists SSO, SCIM and roles as
  planned for its Enterprise plan.
- **OpenTelemetry export on every account.** Runtime pushes events as logs, and
  CPU and memory as metrics, to any OTLP endpoint at no charge
  ([observability](./observability#opentelemetry-export)). E2B sends OTLP
  metrics and logs on its Enterprise plan.
- **Custom domains built in.** A paid account serves a sandbox port at your own
  hostname, with HTTPS, from one command ([custom domains](./networking#custom-domains)).
  E2B's custom domain guide has you run your own proxy on a virtual machine.
- **Secrets stay outside the sandbox.** Code inside sees a placeholder. The
  real key is added at the egress proxy, only on HTTPS to the hosts you allow
  ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Give an agent a read-only key or a daily spending
  limit per key. Cap any sandbox's whole cost with `maxTotalCostMicros`. Every write takes an
  idempotency key, and the SDKs retry with it. A lost response never creates
  a second sandbox.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, snapshots and forks with memory, private
previews, a Linux desktop, metrics, webhooks, S3, R2 and GCS bucket mounts and identity tokens for AWS and Google Cloud. Paid
accounts add TCP ports, dedicated outbound addresses and WireGuard private
networks. See [products](./products).

## At a glance

E2B's figures come from its public pricing and documentation, checked
25 October 2026.

|                  | Runtime                                                                     | E2B                                                      |
| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------------------- |
| Isolation        | Firecracker microVM, own kernel                                             | Firecracker microVM, own kernel                          |
| CPU billing      | $0.025 per vCPU-hour of measured CPU, with a small floor              | $0.0504 per allocated vCPU-hour                 |
| Memory billing   | $0.0075 per reserved GiB-hour                                       | $0.0162 per GiB-hour                         |
| Plan fee         | None; prepaid credit from $10                                     | Hobby $0; Pro $150 a month   |
| Free start       | 100 free hours of a 1 GB machine in the first 30 days, no card                          | $100 of usage credit on Hobby             |
| Session length   | No time limit: runs while it works, pauses itself after 300 seconds idle | 1 hour on Hobby, 24 hours on Pro                         |
| Pause and resume | Files, memory and running processes                                         | Files, memory and running processes                      |
| Interfaces       | API, CLI, MCP server, JavaScript, Python, Go, Ruby and Java SDKs            | API, CLI, MCP server, JavaScript and Python SDKs         |
| Agent sign-in    | Browser approval; no key in the agent's config                              | API key                                                  |
| Port URLs        | Private with a token by default                                             | Public to anyone with the URL unless you turn on a token |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most of its
time waiting for a model.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
         Total                                        $0.64

E2B      CPU    1,000 × 60 s / 3,600 × 2 × $0.0504 = $1.68
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0162 = $1.08
         Total                                        $2.76
```

- **Saving:** 77%, or $2.12 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $276.00 on E2B.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on
  Runtime against $2.76 on E2B. At this size, Runtime is cheaper however busy the
  sandbox is.

Plan fees, storage, network, taxes and free credits are left out of both.
`runtime compare --from e2b` prices your own usage the same way. Sandboxes the
free usage paid for count at the standard rates, so free usage never
counts as a saving. On Runtime, inbound traffic is free. Each account's
first 100 GiB out a month is free. After that, outbound traffic costs
$0.02 per GB (10⁹ bytes). See [pricing](./pricing)
for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the E2B calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### Change one import

Runtime's SDK runs code written for E2B's SDK, as this page describes from
version 0.12.0 (Python 0.12.0). Change the import and set `RUNTIME_API_KEY`:

```ts no-run
import { Sandbox } from "withruntime/e2b"; // was: from "e2b"
```

```python no-run
from withruntime.e2b import Sandbox  # was: from e2b import Sandbox
```

`withruntime/e2b/code-interpreter` and `withruntime.e2b.code_interpreter`
replace E2B's code interpreter packages. Sandboxes get E2B's defaults: 2 vCPU
and 512 MiB. Runtime's server stores the `timeoutMs` you give, up to 24 hours.
When it runs out, the sandbox is deleted, as E2B kills it. `kill()`
also deletes it. With no timeout, E2B's 300 seconds ends in a pause instead.
The pause keeps memory and files at $0.08 per GB (10⁹ bytes) a
month while the account has credit. So call `kill()` when the work is done.
Unlike E2B's, sandboxes pause after 300 seconds with nothing happening and
wake on the next call. E2B code still sees them running.
`runtime: { create: { idlePauseSeconds: 0 } }` keeps them running. Sandboxes use the free usage first, then prepaid credit.
There is nothing to choose.

`commands.run` returns the command's whole output. As E2B's does, it throws
`CommandExitError` (Python `CommandExitException`) on a non-zero exit. It throws
`TimeoutError` (Python `TimeoutException`) past its timeout. Your existing
error handling keeps working. If any output was lost before it was read, the
result's `truncated` is set, and a warning says so.

A call Runtime handles differently, such as E2B templates, workload identity or
ending a sandbox earlier than its time limit, throws `NotSupportedError` before
anything happens. It names what to use instead. `E2B.md` in the package lists
every mapping.

### Or port the calls

The calls map one to one for most integrations.

E2B:

```js
import { Sandbox } from "e2b";
const sbx = await Sandbox.create();
const result = await sbx.commands.run("python3 -c 'print(sum([125, 250, 375]))'");
await sbx.kill();
```

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

E2B's `commands.run` throws `CommandExitError` on a non-zero exit. Runtime's
`exec` returns the result with `exitCode` (and `timedOut: true` on a timeout).
With `{ check: true }`, as above, it throws `CommandError` instead.

## When E2B may fit better

- **Self-hosting.** E2B publishes its runtime under Apache-2.0, so you can run
  it on your own servers. Runtime is a hosted service.

## Sources

Checked 23 September 2026; single sign-on, OpenTelemetry and custom domains
checked 27 September 2026; port URLs checked 3 November 2026.

- [E2B pricing](https://e2b.dev/pricing)
- [E2B Enterprise](https://e2b.dev/enterprise)
- [E2B custom domain](https://docs.e2b.dev/sandbox/custom-domain)
- [E2B sandbox persistence](https://docs.e2b.dev/sandbox/persistence)
- [E2B security](https://e2b.dev/security)
- [E2B public URLs](https://docs.e2b.dev/network/public-url)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/editors -->

# SSH and editors

Log in to a sandbox over SSH, open it in VS Code or a JetBrains IDE, and reach
any port in it from your own machine.

All of it goes through Runtime's API, authenticated with your key, over one
WebSocket per connection. The sandbox opens no port to the internet, and a key
that may run commands in a sandbox is the only thing that can connect.

## Log in

```bash no-run
runtime sandboxes ssh <id>                  # a shell
runtime sandboxes ssh <id> -- make test     # one command; exits with its code
```

`<id>` is the sandbox's id or its name. The first time, the CLI makes an SSH key
for this machine in `~/.config/runtime-cloud/ssh`. It sends only the public
half, into the one login it opens. You log in as `runtime`, the user commands
run as, with the same environment, the proxy settings and `sudo`.

A sandbox whose image has no SSH server, such as a custom image, gets one:
`runtime sandboxes ssh` installs `openssh-server` once and says so first.

## Open it in VS Code, Cursor or Windsurf

```bash no-run
runtime sandboxes code <id>                         # VS Code, at /workspace
runtime sandboxes code <id> --editor cursor         # Cursor
runtime sandboxes code <id> --editor windsurf --path /srv/app
```

One command opens the sandbox's folder in your editor over SSH. It makes sure
the sandbox has an SSH server, adds the `*.runtime` entry below to your SSH
config the first time, and starts the editor on the sandbox. Without the
editor's `code`, `cursor` or `windsurf` command on your PATH, it opens the
editor's link instead; `--print` only prints that link, to open on another
machine that has the entry. The editor needs its Remote - SSH extension, and
its first connection installs the editor's server in the sandbox, which needs
HTTPS out to the editor's download site. A paused sandbox wakes when the editor
connects.

## VS Code, JetBrains and plain ssh

Run this once on your machine:

```bash no-run
runtime sandboxes ssh config --install
```

It writes a `Host *.runtime` entry and includes it from `~/.ssh/config`, so
every sandbox is the host `<id>.runtime`, or `<name>.runtime`, to anything that
uses OpenSSH:

- **ssh, scp and rsync:** `ssh web.runtime`, `scp app.tar web.runtime:`.
- **VS Code, Cursor and Windsurf:** install the Remote - SSH extension, run
  **Remote-SSH: Connect to Host**, and enter `<id>.runtime`, or use
  `runtime sandboxes code` above.
- **JetBrains Gateway:** add an SSH connection to host `<id>.runtime`, user
  `runtime`, authenticating with the OpenSSH config and agent.

`runtime sandboxes ssh config` without `--install` prints the entry to paste yourself.
The entry skips host key checks on purpose. Each login gets a fresh host key.
The connection already goes to the sandbox you named, through Runtime's
authenticated API.

## Forward ports

```bash no-run
runtime sandboxes port-forward <id> 5432              # localhost:5432 here is 5432 in the sandbox
runtime sandboxes port-forward <id> 3000 15432:5432   # several at once, local:remote
```

Any TCP port works, not only HTTP: a database, Redis, a debugger, a dev server
that uses WebSockets. The server in the sandbox can listen on `127.0.0.1`, `::1`
or every address. Start it with `runtime sandboxes spawn <id> -- <command>` (or
`sbx.spawn()`), which keeps it running. A process started by `exec` ends with
its command. The forward listens on `127.0.0.1` unless you pass `--address`,
runs until Ctrl-C, and says so when nothing listens on the port.

From code, the SDKs do the same:

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.spawn("python3 -m http.server 8000");
const forward = await sbx.forwardPort(8000, { localPort: 0 });
console.log(`http://127.0.0.1:${forward.localPort}/`);
await forward.close();
```

```python check
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.spawn("python3 -m http.server 8000")
    with sbx.forward_port(8000, local_port=0) as forward:
        print(f"http://127.0.0.1:{forward.local_port}/")
```

`sbx.tunnel()` in JavaScript opens one connection at a time instead:
`tunnel.connect(5432)` and `tunnel.ssh(publicKey)` each give a stream. It
reaches this one sandbox from your code. It is not the WireGuard tunnel that
joins your own network to your sandboxes
([private networks](./networking#private-networks)).

## Limits

- Connecting to a paused sandbox wakes it, as any command does. An open
  connection keeps it running. A sandbox is never idle while one is open. With
  no time limit, it runs as long as the session does, while credit lasts. A
  sandbox created with `timeoutSeconds` still ends the connection at its limit.
  Extend it for a long session.
- An organization has at most 16 SSH logins and port forwards open at the same time. It
  gets two more for each sandbox it holds that is not stopped, up to 292. One
  port forward carries at most 64 connections at the same time. Each lasts at most 24
  hours. Open it again to go on.
- Port 10800 is the sandbox's own outbound proxy and is not forwarded.


---

<!-- https://withruntime.com/docs/egress -->

# Outbound traffic

For anyone who runs a website, an API or a mail server and sees traffic from
Runtime: where it comes from, what Runtime never lets out, and who to write to.

## Runtime's addresses

Sandboxes send from the addresses listed at
[withruntime.com/egress.json](https://withruntime.com/egress.json), IPv4 and
IPv6. The list changes when a server joins or leaves, so read it rather than
copy it once; `updatedAt` is `null`, so compare the lists themselves. If the list cannot be read in
full, the request returns 503 with a `Retry-After` header and no partial list;
keep the list you have and retry.

```bash no-run
curl -s https://withruntime.com/egress.json
# {"ipv4":["203.0.113.10", ...],"ipv6":["2001:db8::10", ...],"updatedAt":null}
```

An account can hold its own address, which no other account sends from
([Dedicated outbound addresses](/docs/networking#dedicated-outbound-addresses)).
To admit one customer and nobody else, ask them for theirs.

## Shared addresses and per-address limits

Each server's sandboxes send from that server's shared addresses, an account
always from the same one of them. A service that limits callers by address
when they bring no key counts every account on that address together.

GitHub's API is the common case. Calls without a token are capped at 60 an
hour per address. This affects `gh` without login, installers and release
downloads through `api.github.com`, and package resolvers that read GitHub.
They return `API rate limit exceeded for <address>` once anyone on that address
has used the hour's 60. A token gives your account its own limit (5,000 an hour).
Store it as a secret that the network adds to every request to GitHub's API,
so tools need no change:

```bash no-run
printf %s "$GITHUB_TOKEN" | runtime secrets set GITHUB_TOKEN --host api.github.com --header Authorization --format "token {value}"
```

A fine-grained token with read access to public repositories is enough. For
`gh`, the placeholder in `GITHUB_TOKEN` works unchanged
([secrets](/docs/security#secrets-sandboxes-never-see)). An account that needs an address no
other account shares can hold a
[dedicated outbound address](/docs/networking#dedicated-outbound-addresses).

An account whose sandboxes reach sites the way a scraper does sends from
addresses kept for scrapers instead of the shared ones, so a site that blocks
scrapers does not block the other accounts on the same server. Those addresses
are in the same list, and a sandbox keeps its internet whichever it sends from.

## Connections to one site

A sandbox opens up to 20 new connections a second to one site, after a burst
of 200, and an account's sandboxes on one server up to 100 a second together,
after a burst of 1,000. A site is its registered name: `www.example.com` and
`api.example.com` count together. The addresses a connection reaches count
too, by network (a /24, or a /64), at two and a half times those figures, so a
site's addresses asked for by number share its count. On HTTPS, a connection
whose TLS hello names another site than the one it asked for counts for that
site as well. Only new connections count, never bytes, so a download or a
stream over a connection already open is never slowed.

Package registries, code hosts, container registries, storage APIs (S3, R2,
Google Cloud Storage), model hubs, AI APIs and Runtime's own sites have their
own far higher figures: 200 a second for a sandbox and 2,000 for an account on
one server. An install, a clone or a download from many sandboxes at the same time
never reaches them. A site hosted on a provider's servers (an S3 website,
CloudFront, GitHub Pages) counts as a site of its own.

Past a count, the connection is refused with `429 Too Many Requests`,
`Retry-After: 1` and the header `X-Runtime-Egress: rate-limited:destination-sandbox`
(or `-org` for the account's), with a sentence naming the site. Reuse
connections (HTTP keep-alive, one client per process) or wait and retry. If
your work needs more to one site, write to support@withruntime.com.

## Sites that block by address

Some sites respond to an address that sends them too much traffic with a CAPTCHA
or a block, for everyone on that address: Google, Bing, DuckDuckGo, Yahoo,
Yandex, Baidu, Amazon, LinkedIn, Instagram, Facebook, X, TikTok, Zillow,
Indeed, Walmart, eBay, Booking.com and Airbnb. Your sandboxes on a server
share its outbound addresses with other customers, so each address a server
sends from for more than one account opens at most 150 new connections an
hour to each of these sites, after a burst of 50, for all accounts together,
and at most 100 an hour, after a burst of 30, for any one account. Past its
limit on its usual address, an account's connections leave from the server's
address for heavy traffic when it has one, under the same limits there.
Otherwise they are refused with `429 Too Many Requests`, the header
`X-Runtime-Egress: rate-limited:guarded-site` and `Retry-After: 36` (the
account's limit) or `Retry-After: 24` (the address's). An account that sends
from the addresses kept for scrapers reaches these sites only from those,
under the same limits: on a server that has none, its connections to them are
refused the same way, with `Retry-After: 600`, and its new sandboxes go first
to servers that have one. Reuse connections (HTTP keep-alive) to do more
within the limits. A
[dedicated outbound address](./networking#dedicated-outbound-addresses) is
yours alone and never counted.

## Signed requests

An account can have its sandboxes sign their HTTP requests as Runtime's,
with [Web Bot Auth](https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/)
(RFC 9421 HTTP message signatures). A site, or Cloudflare, Akamai or Vercel in
front of it, can then tell an agent on Runtime from anonymous traffic on a
hosting network. It is off until the account turns it on.

- **Signature-Agent** is `"https://withruntime.com"`. Runtime's keys are at
  [withruntime.com/.well-known/http-message-signatures-directory](https://withruntime.com/.well-known/http-message-signatures-directory).
- **Each signature** covers the site's authority and the Signature-Agent
  header, and lasts 5 minutes.
- **Only from a running sandbox** of an account that turned it on. Runtime
  never gives the key to a sandbox.

## What never leaves a sandbox

- **Mail.** Ports 25, 465 and 587 are closed to every sandbox. Support opens
  them for an account only on request, after review.
- **Scans.** A sandbox that tries many ports or many addresses the way only a
  scanner does has its network turned off.
- **Private addresses.** Private, internal and link-local addresses are
  refused, whoever asks.
- **Floods.** Each sandbox has limits on connections opened a second, to any
  site and to one site, on upload speed and on bytes a day; each account has
  limits on top.

Every outbound connection is recorded against the sandbox and the account that
made it, so a report with an address and a time finds its sender.

## Report abuse

Write to **abuse@withruntime.com** with the address or URL involved, the date,
time and time zone, and any logs you have. We find the sandbox, cut its network
and act on the account.


---

<!-- https://withruntime.com/docs/feedback-and-support -->

# Send feedback and get support

Runtime improves fast because agents tell us what they run into.

Every report goes straight into our next work items. You are told when what
you asked for ships. Report problems as they happen, without waiting to be asked:

- an error that looks like ours;
- a limit or missing feature;
- a workaround you needed;
- unclear docs;
- something slower or harder than it should be;
- something another provider does better.

Small things count. We merge duplicates. Never include
credentials, private files or user data. Tell the user in one line what you reported.

## Send feedback

Report generously. Good reasons to file:

- **Bug**: something returned an error or behaved differently from the docs.
- **Feature request** (`missing_feature`): something you need does not
  exist, such as a region, a larger size, a language SDK or a product. In the
  account, **Request a feature** on the **Support** page opens the form on
  this kind.
- **Competitor gap**: another provider does something better or more simply.
  Name it.
- **Migration blocker**: something specific stops a workload from switching here.
  Name the provider you are moving from.
- **Docs**: a page is wrong, unclear or missing.
- **Pricing**, **praise** or **other**.

How to write one:

- Kinds are `bug`, `missing_feature`, `competitor_gap`, `migration_blocker`,
  `docs`, `pricing`, `praise` and `other`.
- Keep the summary to one actionable sentence of at most 200 characters. Put
  the detail, up to 8,000 characters, in the body.
- Include the resource ID and the request ID when an error prompted the report.
  Every error carries a request ID.

From MCP, call `runtime_feedback` with `"action": "submit"`. From the CLI:

```bash no-run
npx withruntime feedback --kind migration_blocker --competitor E2B \
  "No GPU sandboxes, so our model evaluations cannot move"
```

Over HTTP, `POST /v1/feedback` with the same fields. From code:

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

const runtime = new Runtime();
await runtime.feedback.submit({
  kind: "missing_feature",
  summary: "A way to mount an S3 bucket in a sandbox",
  detail: "We copy 20 GB in at the start of every job.",
});
console.log((await runtime.feedback.list()).data);
```

### What happens to a report

1. **Received** the moment the call returns.
2. **Sorted** within the hour. A triage job sorts new reports into items
   and merges duplicates. It only merges into an item that is still open. Until
   then, a report shows `sorted: false` and `item: null`. It is received and waiting, not lost.
3. **Shipped:** everyone who asked for it gets one email per run. The email lists
   everything of theirs that shipped. It goes to the address given with the
   report, else to the person who filed it, else to the organization's owners.
   The link at the bottom stops these emails for that address without signing
   in. The status stays in the account.

`npx withruntime feedback --list`, `runtime_feedback` with `list` and
`GET /v1/feedback` show what your organization reported, whether it has been
sorted, and whether it shipped. The **Support** page in the account shows the same.
The support agent can also look them up for you.

Never put API keys, passwords or private file contents in a report.

An account that has never added credit can file up to 5 reports a day through
the API, MCP, CLI or SDKs. The sixth returns `429 rate_limited` until midnight
UTC. Accounts that have added credit are not limited. The support agent sends
an organization 40 messages a day before it adds credit, and 500 after.

## Get support

**Runtime's support agent replies in the same call, with your account in view.**
It reads your organization's resources, operations and errors, usage, billing,
notices and job logs, together with these docs. It can reproduce a problem in
its own sandbox. A person reviews anything it escalates. A read-only key lets it see only what that key can see: no job logs, keys, members or
sandbox contents. It proposes no actions with a read-only key.

From MCP, call `runtime_support` with `"action": "message"` and your question. Keep the
returned `conversationId` for follow-ups. If the reply is still being worked
on, the status is `working`. Call it with `read` and the conversation
ID until the status changes. From the CLI:

```bash no-run
npx withruntime support "Sandbox 0b8f3c52-… has been starting for ten minutes"
npx withruntime support read <conversationId>
```

People can use the Help button on withruntime.com, or **Support** in the
account menu.

### Actions need your approval

The support agent never changes your account by itself. When a fix needs an
action, such as stopping, pausing, waking or resuming a sandbox, changing pause
retention or a lifetime policy, or looking inside a sandbox, it proposes the
action. It returns an action ID and an input hash. Nothing runs until you
approve that exact action:

- MCP: `runtime_support`, action `message`, with `conversationId`, `approveActionId` and
  `approveInputHash`, or `denyActionId`.
- CLI: `npx withruntime support approve <actionId> <inputHash> --conversation <id>` or
  `npx withruntime support deny <actionId> --conversation <id>`.
- HTTP: `POST /v1/support/messages` with the same fields.
- Web: the Approve button on the action card.

Typing "yes" is not an approval. An approved action then passes an independent
safety check before it runs. It runs with your own authority, so an agent can
approve actions only on the resources it owns. The action appears in your
organization's audit log.

### Stopping Runtime's emails

Runtime sends no newsletter. Each optional email ends with a link that stops
that kind for you. You can also choose them in an account at
[withruntime.com/account/emails](https://withruntime.com/account/emails) (see
[Emails](./teams#emails)). Email support from an address and ask to stop our
emails. The support agent tells you which of Runtime's emails reach that
address and how to stop each. It only looks. Anyone can put any address on an
email, so stopping takes the email's own link or your signed-in settings.

### What goes to a person

Refunds, credits, disputed charges, security reports, suspected leaked keys,
data loss, outages, abuse reports and legal questions always go to a person. So
does any request for a person, a bug you report from your account, and a
question the support agent cannot finish in one reply. The support agent says so,
and a person replies in the same conversation. If you suspect a key has leaked, revoke it at
[withruntime.com/account/keys](https://withruntime.com/account/keys) first, then
report it.

Support conversations are processed by an AI model through a third-party model
gateway. The providers are listed on the [subprocessors page](/legal/subprocessors).


---

<!-- https://withruntime.com/docs/fly-alternative -->

# Runtime vs Fly.io

Runtime runs agent code in Firecracker microVMs, like Fly.io. It costs **73% less than Sprites** for an agent that mostly waits on a model.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime, $2.40 on Fly Sprites and $1.53 on a Fly Machine**. At 100,000 runs a
month that is $63.89 against $240.14 on Sprites, **$176 a month saved**, or
against $152.78 on Machines, $89 saved.

Comparing more than two? [Fly.io alternatives for agent sandboxes](/compare/fly-io-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **Lower rates.** Measured CPU costs $0.025 a vCPU-hour, 35% below Sprites' $0.0385. Reserved memory costs $0.0075 per GiB-hour, 66% below Sprites' $0.021875 per GB-hour of memory in use.
- **Idle time bills only storage.** A Runtime sandbox pauses itself after
  300 seconds with nothing happening in it. It keeps its memory and processes.
  While paused, it pays $0.08 per GB (10⁹ bytes) of saved state
  a month.
- **An uptime promise that pays itself.** Paid accounts are promised
  99% API uptime each month. A month below it returns 10% of that
  month's charges as credit. No claim is needed ([Uptime Promise](/legal/sla)).
- **You pay for the CPU you use.** A Machine bills its whole size for every
  second it is started, busy or not. Runtime bills measured CPU, so time spent
  waiting on a model costs only a small floor, a twentieth of a vCPU.
- **Memory survives a pause, for as long as you choose.** A paused Runtime
  sandbox keeps its processes while you have credit. A
  Sprite drops its memory when it goes cold, at a time you do not choose. A
  Machine's root disk is temporary.
- **Sized to the job.** You set vCPUs and memory for each sandbox and are billed
  for no more. A Sprite's memory is managed by Fly and is not a fixed figure to
  plan against.
- **Keys the sandbox never sees.** Store an API key once. The sandbox holds a
  placeholder. Runtime's proxy adds the value only to HTTPS requests to the
  hosts you name. A prompt injection has nothing to leak ([security](./security)).
- **Your credit matched.** Credit you add within 30 days of signing up is matched, up to $1,000 in total
  ([welcome match](./pricing#welcome-match)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Safe retries.** Every write takes an idempotency key, and the SDKs retry
  with it automatically. A lost response never creates a second sandbox.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, snapshots and forks with memory, private
previews, a Linux desktop, metrics, webhooks, OpenTelemetry export, S3, R2 and
GCS bucket mounts, identity tokens for AWS and
Google Cloud and free single sign-on. Paid accounts add custom domains, TCP
ports, dedicated outbound addresses and WireGuard private networks. See
[products](./products).

## At a glance

This compares Runtime with Fly.io's two ways to run agent code: Sprites, its
sandboxes for agents, and Machines, its general-purpose VMs. Fly.io's figures
come from its public pricing and documentation, checked 25 October 2026, with
Machines at the rates of its Ashburn (`iad`) region.

|                | Runtime                                                          | Fly Sprites                                               | Fly Machines                                                                           |
| -------------- | ---------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Isolation      | Firecracker microVM, own kernel                                  | Firecracker microVM                                       | Firecracker microVM                                                                    |
| CPU billing    | $0.025 per vCPU-hour of measured CPU, with a small floor   | $0.0385 per CPU-hour of measured CPU     | By size while started; 2 performance vCPUs and 4 GB $0.0916704 an hour |
| Memory billing | $0.0075 per reserved GiB-hour                            | $0.021875 per GB-hour of memory in use  | Included in the size; more at $6 per GB a month        |
| Size           | Up to 16 vCPUs and 64 GiB paid, chosen apart   | Memory managed by Fly, 100 GB disk                        | Up to 16 performance vCPUs and 128 GB                                                  |
| Plan fee       | None; prepaid credit from $10                          | None required; optional monthly plans                     | None; pay as you go                                                                    |
| Free start     | 100 free hours of a 1 GB machine in the first 30 days, no card               | $30 of trial credit               | Not stated on the pricing page                                                         |
| When idle      | Pause keeps files and memory; kept while you have credit         | Pauses itself; memory kept at first, the disk kept always | Root disk is temporary; volumes keep files; suspend, 2 GB or less                      |
| Interfaces     | API, CLI, MCP server, JavaScript, Python, Go, Ruby and Java SDKs | API, CLI, MCP server; JavaScript, Python, Go, Elixir SDKs | Machines API and flyctl                                                                |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most of its
time waiting for a model. The Sprite is assumed to use all 4 GB for the whole
minute. The Machine is a `performance-2x` with 4 GB.

```
Runtime   CPU    1,000 × 20 s / 3,600 × $0.025        = $0.14
          Memory 1,000 × 60 s / 3,600 × 4 × $0.0075   = $0.50
          Total                                          $0.64

Sprites   CPU    1,000 × 20 s / 3,600 × $0.0385         = $0.21
          Memory 1,000 × 90 s / 3,600 × 4 × $0.021875  = $2.19
          Total                                          $2.40

Machines  Size   1,000 × 60 s / 3,600 × $0.0916704       = $1.53
```

- **Saving:** 73% against Sprites ($1.76 per 1,000 runs) and 58% against
  Machines ($0.89 per 1,000 runs).
- **Per month:** at 100,000 runs, $63.89 on Runtime against $240.14 on Sprites
  and $152.78 on Machines.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime,
  $3.47 on Sprites and $1.53 on Machines.

A Sprite bills the memory it actually uses. So a job that uses 1 GB pays $0.76
in total. Every figure here includes the 30 seconds or so a Sprite stays awake and billed after its run. A Machine's performance vCPUs are whole cores kept for
it. Runtime's default shared CPU is not. Runtime's `cpu: "reserved"` keeps
every vCPU for you too.

A `shared-cpu-2x` Machine with 4 GB costs about $0.50 for the same runs. Its
shared vCPUs are guaranteed 6.25% of a core each and start with a small burst
allowance, so a new one would not fit 20 CPU-seconds into the minute. Storage,
network, plan fees, taxes and free credits are left out of all three. On
Runtime, inbound traffic is free. Each account's first 100 GiB out a month
is free. After that, outbound traffic costs $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Fly.io calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### From Sprites

```js
import { SpritesClient } from "@fly/sprites";
const client = new SpritesClient(process.env.SPRITE_TOKEN);
const sprite = await client.createSprite("my-sprite");
const result = await sprite.execFile("python3", ["-c", "print(sum([125, 250, 375]))"]);
console.log(result.stdout);
await sprite.delete();
```

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec(["python3", "/workspace/invoice.py"], { check: true })).stdout);
} finally {
  await box.stop();
}
```

### From Machines

Code that calls the Machines API keeps its calls. Only the address changes.
Run Runtime's Machines API server next to your code:

```sh no-run
npx withruntime fly-api   # answers on http://127.0.0.1:4280 as your Runtime login
```

Then point your client at it. Leave the rest of your code as it is:

```sh no-run
export FLY_API_HOSTNAME=http://127.0.0.1:4280     # Fly's curl examples
export FLY_FLAPS_BASE_URL=http://127.0.0.1:4280   # fly-go, Fly's Go client
```

On 18 October 2026 we ran the 22 curl examples on Fly's
[Machines API pages](https://fly.io/docs/machines/api/machines-resource/)
exactly as written, and fly-go 0.11.6 unchanged, against Runtime this way. A
Node service can serve the calls itself. `machinesApi()` from
`withruntime/fly` is a fetch handler. Your Fly token is never sent anywhere.

flyctl and fly-go can also call the Runtime API directly, with no local
server. Each Machine is then a Runtime Container with one copy. Set all three
of flyctl's API addresses, so that no request is sent to Fly:

```sh no-run
export FLY_FLAPS_BASE_URL=https://api.withruntime.com
export FLY_API_BASE_URL=https://api.withruntime.com
export FLY_UIEX_BASE_URL=https://api.withruntime.com
export FLY_API_TOKEN=rtcloud_...   # a Runtime API key
fly machine run nginx:1.27 -a web --detach
```

`fly machine run`, `list`, `stop`, `start` and `destroy` work unchanged. Other
HTTP clients use `https://api.withruntime.com/compat/fly` as their base URL.

With `npx withruntime fly-api`, each Machine is a Runtime sandbox, started from its image and built once.
`init`, `env`, `files`, `metadata`, leases and the restart policy work. The
image's command is its main process. Suspend keeps the main process running.
Stop keeps the disk. Fly resets a stopped Machine's root disk. Start runs the
main process again. `services`, `mounts`, `checks` and regions other than `iad`
are refused, naming Runtime's alternative. The full map is in
[migration](./migrate).

## When Fly.io may fit better

- **Regions.** Machines run in 17 regions. Runtime runs in one US region.
- **Very cheap sleep.** A sleeping Sprite's disk costs $0.02 per GB-month,
  its cold storage rate ([Fly.io pricing](https://fly.io/pricing/), read 4 October 2026).
  Runtime's paused storage, which also keeps memory, costs $0.08 per GB (10⁹ bytes) a month.
- **A wider platform today.** Machines, volumes and Managed Postgres sit in the
  same account.

## Sources

Prices checked 25 October 2026; Machine suspend rechecked 26 October 2026.

- [Fly.io pricing](https://fly.io/pricing/) for Machines and Sprites
- [Sprites](https://fly.io/sprites/) and its pricing questions
- [Sprites documentation](https://docs.sprites.dev/) and
  [lifecycle and persistence](https://docs.sprites.dev/concepts/lifecycle/)
- [Machine CPU performance](https://fly.io/docs/machines/cpu-performance/)
- [Machine suspend and resume](https://docs.fly.io/reference/suspend-resume/)
- [Fly Volumes](https://fly.io/docs/volumes/overview/)
- [Fly.io regions](https://fly.io/docs/reference/regions/)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/frameworks -->

# Use Runtime with your AI framework

Keep your framework's model and agent loop, and run the code it writes in a Runtime sandbox.

Every integration below is ready to install. Each one runs in its framework's own
agent loop. Each was tested against real sandboxes. Each keeps your model, prompts and
application as they are.

| Framework                                             | Language           | What you add                                                             |
| ----------------------------------------------------- | ------------------ | ------------------------------------------------------------------------ |
| [OpenAI Agents SDK](#openai-agents-sdk)               | Python, TypeScript | A sandbox client for `SandboxAgent`, or four function tools              |
| [Vercel AI SDK](#vercel-ai-sdk)                       | TypeScript         | `runtimeTools(sbx)` from `withruntime/ai`                                |
| [Claude Agent SDK](#claude-agent-sdk)                 | TypeScript         | `runtimeMcpServer(sbx)` from `withruntime/claude-agent-sdk`              |
| [LangChain and LangGraph](#langchain)                 | Python             | `sandbox_tools(sbx)` as LangChain tools                                  |
| [Deep Agents](#deep-agents)                           | Python             | `RuntimeSandbox(sbx)` as the agent's backend                             |
| [Mastra](#mastra)                                     | TypeScript         | `runtimeTools(sbx)`, which Mastra agents take as they are                |
| [CrewAI](#crewai)                                     | Python             | `sandbox_tools(sbx)` wrapped with CrewAI's `tool`                        |
| [Google ADK](#google-adk)                             | Python             | `sandbox_tools(sbx)` as the agent's tools                                |
| [LlamaIndex](#llamaindex)                             | Python             | `sandbox_tools(sbx)` as `FunctionTool`s                                  |
| [Pydantic AI](#pydantic-ai)                           | Python             | `sandbox_tools(sbx)` as the agent's tools                                |
| [Any other framework](#any-other-framework)           | Python, TypeScript | `withruntime.tools` or `withruntime/tools`: a name, a schema, a function |
| [Claude Code, Codex, Cursor and more](#coding-agents) | Any                | Runtime's MCP server: `npx -y withruntime mcp`                           |

Six integrations have a guide of their own:

| Guide                                               | Language   | What it does                                                                                   |
| --------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
| [Harbor and Terminal-Bench](./harbor)               | Python     | `RuntimeEnvironment` runs each trial in its own microVM, from the task's Dockerfile            |
| [Inspect AI](./inspect)                             | Python     | A sandbox named `runtime` runs each sample from its Dockerfile or `compose.yaml`               |
| [LangChain, LangGraph and Deep Agents](./langchain) | Python     | `langchain-withruntime`: a Deep Agents backend, and the four tools for LangChain and LangGraph |
| [Vercel AI SDK harness agents](./vercel-ai-sdk)     | TypeScript | `createRuntimeSandbox()` runs Claude Code, Codex, OpenCode or Pi under `HarnessAgent`          |
| [ComputeSDK](./computesdk)                          | TypeScript | `@computesdk/runtime`, a provider that runs your `compute.sandbox` code unchanged              |
| [Claude Managed Agents](./claude-managed-agents)    | Any        | Runtime's remote MCP server gives a Managed Agent sandboxes beside its own session container   |

**The four tools** are the same in every framework: `runtime_exec` runs a
command, `runtime_read_file` and `runtime_write_file` move text, and
`runtime_list_files` lists a directory. Relative paths are under `/workspace`,
and output is capped so one noisy command cannot flood the model's context.

- Your application creates the sandbox, binds the tools to it and deletes it when
  the work ends. The model chooses commands and paths, never the sandbox or the
  account.
- A framework's own local shell and file tools keep running on your machine;
  switch those off when the sandbox tools replace them.
- Check exit codes, not only that a call succeeded.

## OpenAI Agents SDK

`RuntimeCloudSandboxClient` runs a `SandboxAgent` in a Runtime sandbox: its
shell with PTY sessions and stdin, its file edits and image views, and its
manifest. The agent definition does not change. The
[OpenAI Agents SDK guide](./openai-agents-sdk) covers every option.

```python check
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from withruntime.openai_agents import RuntimeCloudSandboxClient, RuntimeCloudSandboxClientOptions

agent = SandboxAgent(name="Coder", instructions="Fix the failing test, then run the suite.")
run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=RuntimeCloudSandboxClient(),
        options=RuntimeCloudSandboxClientOptions(),
    )
)
result = Runner.run_sync(agent, "The tests are in tests/.", run_config=run_config)
print(result.final_output)
```

Install with `pip install "withruntime[openai-agents]"`. In TypeScript:

```ts
import { run } from "@openai/agents";
import { SandboxAgent } from "@openai/agents/sandbox";
import { RuntimeCloudSandboxClient } from "withruntime/openai-agents";

export async function fixTests() {
  const agent = new SandboxAgent({ name: "Coder", instructions: "Fix the failing test." });
  const client = new RuntimeCloudSandboxClient();
  const result = await run(agent, "The tests are in tests/.", { sandbox: { client } });
  return result.finalOutput;
}
```

For an ordinary `Agent`, `runtimeFunctionTools(sbx)` (TypeScript) or
`[function_tool(f) for f in sandbox_tools(sbx)]` (Python) gives it the four tools.

## Vercel AI SDK

`runtimeTools(sbx)` returns the four tools as AI SDK tools, for `generateText`,
`streamText` and agents.

```ts
import { generateText, stepCountIs, type LanguageModel } from "ai";
import { Sandbox } from "withruntime";
import { runtimeTools } from "withruntime/ai";

export async function solve(model: LanguageModel, prompt: string) {
  await using sbx = await Sandbox.create();
  const { text } = await generateText({
    model,
    tools: runtimeTools(sbx),
    stopWhen: stepCountIs(20),
    prompt,
  });
  return text;
}
```

It needs the `ai` package, version 5 or later. To run a whole harness agent in
the sandbox instead, see the [Vercel AI SDK guide](./vercel-ai-sdk).

## Claude Agent SDK

`runtimeMcpServer(sbx)` is an in-process MCP server with the four tools.
`RUNTIME_TOOL_NAMES` lists them for `allowedTools`.

```ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import { Sandbox } from "withruntime";
import { RUNTIME_TOOL_NAMES, runtimeMcpServer } from "withruntime/claude-agent-sdk";

export async function solve(prompt: string) {
  await using sbx = await Sandbox.create();
  let answer = "";
  for await (const message of query({
    prompt,
    options: {
      mcpServers: { runtime: runtimeMcpServer(sbx) },
      allowedTools: RUNTIME_TOOL_NAMES,
      disallowedTools: ["Bash", "Read", "Write", "Edit"],
    },
  })) {
    if (message.type === "result" && message.subtype === "success") answer = message.result;
  }
  return answer;
}
```

`disallowedTools` keeps the agent's work off your machine. It needs `zod` beside
the SDK. An agent that should create and manage sandboxes itself can connect
Runtime's own MCP server instead, as in [coding agents](#coding-agents).

## LangChain

`sandbox_tools(sbx)` returns the four tools as plain Python functions with type
hints and docstrings, which LangChain's `tool` turns into LangChain tools. They
work in `create_agent`, a LangGraph `ToolNode` and anywhere else LangChain
takes tools.

```python check
from langchain.agents import create_agent
from langchain_core.tools import tool
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def solve(model, task: str) -> str:
    with Sandbox.create() as sbx:
        agent = create_agent(model, tools=[tool(f) for f in sandbox_tools(sbx)])
        result = agent.invoke({"messages": [{"role": "user", "content": task}]})
        return result["messages"][-1].content
```

The [LangChain guide](./langchain) covers `langchain-withruntime`, the package
LangChain lists.

## Deep Agents

`RuntimeSandbox(sbx)` is a Deep Agents sandbox backend: the agent's `execute`,
`ls`, `read_file`, `write_file`, `edit_file`, `glob` and `grep` all run in the
sandbox.

```python check
from deepagents import create_deep_agent
from withruntime import Sandbox
from withruntime.deepagents import RuntimeSandbox


def solve(task: str) -> str:
    with Sandbox.create() as sbx:
        agent = create_deep_agent(backend=RuntimeSandbox(sbx))
        result = agent.invoke({"messages": [{"role": "user", "content": task}]})
        return result["messages"][-1].content
```

Install with `pip install "withruntime[deepagents]"`.

## Mastra

Mastra agents take AI SDK tools as they are, so `runtimeTools(sbx)` from
`withruntime/ai` is the whole integration:
`new Agent({ id: "coder", name: "Coder", instructions, model, tools: runtimeTools(sbx) })`.

## CrewAI

```python check
from crewai import Agent, Crew, Task
from crewai.tools import tool
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def fix_tests() -> str:
    with Sandbox.create() as sbx:
        engineer = Agent(
            role="Engineer",
            goal="Make the test suite pass",
            backstory="You work in a Linux sandbox.",
            tools=[tool(f) for f in sandbox_tools(sbx)],
        )
        task = Task(description="Run the tests and fix what fails.", expected_output="A summary", agent=engineer)
        return str(Crew(agents=[engineer], tasks=[task]).kickoff())
```

## Google ADK

ADK wraps plain functions as tools, so the four tools go straight in.

```python check
from google.adk.agents import Agent
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def coder(model: str, sbx: Sandbox) -> Agent:
    return Agent(
        name="coder",
        model=model,
        instruction="Run code in the sandbox to answer.",
        tools=sandbox_tools(sbx),
    )
```

## LlamaIndex

```python check
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def coder(llm, sbx: Sandbox) -> FunctionAgent:
    return FunctionAgent(tools=[FunctionTool.from_defaults(fn=f) for f in sandbox_tools(sbx)], llm=llm)
```

## Pydantic AI

```python check
from pydantic_ai import Agent
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def solve(model, task: str) -> str:
    with Sandbox.create() as sbx:
        return Agent(model, tools=sandbox_tools(sbx)).run_sync(task).output
```

## Any other framework

`sandbox_tools(sbx)` gives any framework that takes typed, documented
functions the four tools. Pass an `AsyncSandbox` and they are coroutines. Try
them without a model:

```python
from withruntime import Sandbox
from withruntime.tools import sandbox_tools

with Sandbox.create() as sbx:
    run, read, write, ls = sandbox_tools(sbx)
    print(write("hello.py", "print(sum([125, 250, 375]))\n"))
    print(run("python3 hello.py"))
    print(ls("."))
```

In TypeScript, `withruntime/tools` gives each tool as a name, a description, a
JSON Schema and a function, ready for any tool format:

```ts
import { Sandbox } from "withruntime";
import { sandboxTools } from "withruntime/tools";

await using sbx = await Sandbox.create();
for (const t of sandboxTools(sbx)) console.log(t.name, Object.keys(t.inputSchema.properties));
const [exec] = sandboxTools(sbx);
console.log(await exec.execute({ command: "python3 -c 'print(sum([125, 250, 375]))'" }));
```

## Coding agents

Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI and any other MCP
client connect to Runtime's own MCP server, which offers every Runtime product
as tools. The first call shows a link and a code to approve in the browser;
there is no key to copy. [MCP](./mcp) covers the tools and the remote endpoint.

```bash no-run
claude mcp add --scope user runtime -- npx -y withruntime mcp
codex mcp add runtime -- npx -y withruntime mcp
gemini mcp add --scope user runtime npx -y withruntime mcp
```

Cursor (`.cursor/mcp.json`) and Windsurf (`~/.codeium/windsurf/mcp_config.json`)
take the same file:

```json
{
  "mcpServers": {
    "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] }
  }
}
```

VS Code takes it in `.vscode/mcp.json`:

```json
{
  "servers": {
    "runtime": { "type": "stdio", "command": "npx", "args": ["-y", "withruntime", "mcp"] }
  }
}
```

## What was verified

- Every sample on this page is typechecked or compiled against the current SDK
  on every build, and the samples that need no model run.
- On 23 September 2026 each integration ran in its framework's own agent loop
  against real sandboxes without credit, driven by scripted models so no model was paid
  for: OpenAI Agents SDK 0.22.3 (Python) and 0.18.0 (TypeScript), AI SDK
  7.0.87, Claude Agent SDK 0.3.277, LangChain 1.4, LangGraph 1.2, Deep Agents
  0.7.18, Mastra 1.69.0, Pydantic AI 2.48, Google ADK 2.9, LlamaIndex 0.14 and
  CrewAI 1.15. The OpenAI sandbox client also passed PTY sessions with stdin,
  manifests, users, exposed ports, tar and snapshot persistence, pause and
  resume.
- `claude mcp list`, `codex mcp list` and `cursor-agent mcp list-tools` each
  reached the MCP server from the configuration above.

Official references checked 25 October 2026:
[OpenAI Agents SDK sandbox clients](https://openai.github.io/openai-agents-python/sandbox/clients/),
[Vercel tools](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling),
[Claude Agent SDK custom tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools),
[LangChain tools](https://docs.langchain.com/oss/python/langchain/tools),
[Mastra tools](https://mastra.ai/docs/agents/using-tools).


---

<!-- https://withruntime.com/docs/freestyle-alternative -->

# Runtime vs Freestyle

Runtime runs agent code in its own microVMs, like Freestyle's VMs. For an agent that mostly waits on a model, it costs **72% less**. You do not need to buy a plan to run more sandboxes at the same time.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $2.25 on Freestyle**. At 100,000 runs a month, that is $63.89
against $224.99, **$161 a month saved**.

Comparing more than two providers? [Freestyle alternatives](/compare/freestyle-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Freestyle bills the vCPUs, memory and disk
  allocated to a VM for as long as it is allocated. Its pricing page says a
  reserved core is yours whether or not the guest is busy. Runtime measures the
  CPU your code actually uses. Time spent waiting on a model costs only a
  small floor, a twentieth of a vCPU.
- **It pauses itself when idle.** After 300 seconds with no request, command, connection,
  traffic or CPU use, a Runtime sandbox pauses. While paused, it pays only paused storage,
  $0.08 per GB (10⁹ bytes) a month. The next request wakes it. Its processes keep running.
- **A written uptime promise.** Paid accounts get 99% API uptime a month,
  measured from outside. If a month falls short, 10% of that month's charges
  is returned as credit automatically ([Uptime Promise](/legal/sla)).
- **Lower rates on both meters.** $0.025 per vCPU-hour, against $0.04032, and $0.0075 per GiB-hour of memory, against $0.0129. With both CPUs busy the whole
  time, the example job costs $1.33 on Runtime and $2.25 on Freestyle.
- **Scale without a plan.** Freestyle runs 10 VMs at the same time on its free plan, 40
  on the $50-a-month Hobby plan, and 400 on the $500-a-month Pro plan. A paid
  Runtime account runs 100 concurrent sandboxes, with no plan fee. It has prepaid credit from $10, and support raises the
  limit when you ask.
- **Bigger sandboxes without Pro.** A paid Runtime sandbox takes up to 16 vCPUs
  and 64 GiB. On Freestyle, 64 GiB needs the Pro plan. Hobby stops at 8 vCPUs
  and 16 GiB.
- **Teams at no extra charge.** Single sign-on over SAML or OIDC (Okta,
  Microsoft Entra ID, Google Workspace), SCIM, roles and an audit log come with
  every account ([single sign-on](./single-sign-on)).
- **Secrets stay outside the sandbox.** Code inside sees a placeholder. The
  real key is added at the egress proxy, only on HTTPS to the hosts you allow
  ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Read-only keys, a daily spending limit per key and
  `maxTotalCostMicros` on each sandbox keep an agent inside its budget. Every
  write takes an idempotency key.
- **Python and JavaScript.** Runtime has SDKs for both, a CLI and an MCP server.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, snapshots and forks with memory, private
previews, a Linux desktop, metrics, webhooks, OpenTelemetry export, S3, R2 and
GCS bucket mounts, and identity tokens for AWS and
Google Cloud. Paid accounts add custom domains, TCP ports, dedicated outbound
addresses and WireGuard private networks. See [products](./products).

## At a glance

Freestyle's figures come from its public pricing page and VM documentation.
Last checked 25 October 2026.

|                      | Runtime                                                        | Freestyle                                                                                        |
| -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Isolation            | Firecracker microVM, own kernel                                | Full Linux virtual machines                                                                      |
| CPU billing          | $0.025 per vCPU-hour of measured CPU, with a small floor | $0.04032 per allocated vCPU-hour                                                   |
| Memory billing       | $0.0075 per reserved GiB-hour                          | $0.0129 per allocated GiB-hour                                                 |
| Disk while it runs   | Included                                                       | $0.000086 per allocated GiB-hour                                                   |
| Sizes                | Up to 16 vCPUs and 64 GiB paid, chosen apart | 4 vCPUs and 8 GiB free; 8 and 16 Hobby; 32 and 64 Pro                                            |
| Concurrent sandboxes | 100 paid, no plan                               | 10 free, 40 Hobby, 400 Pro                                                                       |
| Plan fee             | None; prepaid credit from $10                        | Free $0; Hobby $50 and Pro $500 a month, counted to usage |
| Free start           | 100 free hours of a 1 GB machine in the first 30 days, no card             | 200 vCPU-hours and 400 GiB-hours of memory a month                                               |
| Pause                | Files, memory and processes, kept while you have credit        | Hibernate with memory, billed as storage while paused                                            |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most of its time
waiting for a model. Freestyle's VM keeps its default 32 GiB disk.

```
Runtime    CPU    1,000 × 20 s / 3,600 × $0.025              = $0.14
           Memory 1,000 × 60 s / 3,600 × 4 × $0.0075         = $0.50
           Total                                                $0.64

Freestyle  CPU    1,000 × 60 s / 3,600 × 2 × $0.04032        = $1.34
           Memory 1,000 × 60 s / 3,600 × 4 × $0.0129         = $0.86
           Disk   1,000 × 60 s / 3,600 × 32 × $0.000086      = $0.05
           Total                                                $2.25
```

- **Saving:** 72%, or $1.61 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $224.99 on
  Freestyle, before any plan fee.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $2.25 on Freestyle. At this size, Runtime is cheaper however busy the
  sandbox is.

Plan fees, free allowances, data transfer, paused storage and taxes are excluded
from both. On Runtime, inbound traffic is free. Each account's first 100 GiB
out a month is free, then $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's
terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Freestyle calls on a branch, tests them on the free usage, and
tells you what you save each month. Your old code stays on the main branch until
you merge.

A Freestyle snapshot you start VMs from maps to a Runtime
[snapshot](./javascript#snapshots-and-forks) or a [custom image](./images). A
VM kept for weeks maps to a paused sandbox. It is kept while you have credit, or
for a fixed number of days:

```ts check
import { Sandbox } from "withruntime";

const box = await Sandbox.create({ timeoutSeconds: 3600 });
await box.exec("pip install --quiet requests");
await box.pause(); // memory, processes and files are kept
await box.setRetention(90); // a fixed 90 days instead
await box.wake(); // later: it carries on where it stopped
await box.stop();
```

A Freestyle VM runs commands as root. A Runtime sandbox runs them as the user
`runtime`, who has passwordless `sudo`. To run everything as root,
with no `sudo` in front of each command, pass `user: "root"`:

```ts check
import { Sandbox } from "withruntime";

await using box = await Sandbox.create();
await box.exec("apt-get install -y jq", { user: "root" });
await box.spawn("nginx -g 'daemon off;'", { user: "root" });
```

## When Freestyle may fit better

- **More than 16 vCPUs in one VM.** Freestyle's Pro plan goes to 32 vCPUs.
- **Forking without a pause.** Freestyle clones a running VM without pausing
  it. A Runtime fork pauses the source for the capture and has it running
  again when the call returns.
- **The fastest start.** Freestyle states VMs provision with a p99 under
  400 ms.

## Sources

Checked 26 October 2026.

- [Freestyle pricing](https://www.freestyle.sh/pricing)
- [Freestyle VM pricing and limits](https://www.freestyle.sh/docs/vms/pricing-and-limits)
- [Freestyle VMs](https://www.freestyle.sh/docs/vms)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/go -->

# Go SDK

One Go client for every Runtime Cloud product, with a `context.Context` on every call.

The module is `withruntime.com/go`, imported as package `withruntime`. It needs
Go 1.23 or later and uses only the standard library.

```bash no-run
go get withruntime.com/go
```

**The client finds its key by itself.** It uses `RUNTIME_API_KEY` when that is
set. Otherwise, it uses the connection this machine saved. Any `npx withruntime`
command sets up that connection, with one browser approval.

On a server, store a key from https://withruntime.com/account/keys in
`RUNTIME_API_KEY`, from your secret manager. Never put it in source code, a URL
or a command-line argument. With no key anywhere, `withruntime.New` returns an
error. Its code is `missing_api_key`, and its hint says how to get one.

## Hello, sandbox

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, &withruntime.CreateOptions{})
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	if err := sbx.Files.Write(ctx, "/workspace/invoice.py", []byte("print(sum([125, 250, 375]))\n")); err != nil {
		log.Fatal(err)
	}
	result, err := sbx.Exec(ctx, "python3 /workspace/invoice.py", &withruntime.ExecOptions{Check: true})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(result.Stdout)
}
```

`Create` returns once the sandbox is running. `opts` may be `nil`. With no
options, you get the free usage while it lasts, the default region, and 2 vCPU,
4 GiB of memory and a 4 GiB disk. The sandbox runs while it works and pauses
itself when idle, with no time limit. `TimeoutSeconds` sets one, from 60 to
86,400. `EndsAt` is nil while none applies. The free usage is spent first, then
prepaid credit. `Funding` is accepted and ignored. Every field is optional:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, &withruntime.CreateOptions{
		Name:           "tests-42",
		Labels:         map[string]string{"team": "search", "job": "42"},
		VCPU:           2,
		MemoryMiB:      4096,
		DiskMiB:        8192,
		TimeoutSeconds: 900,
		OnLeaseEnd:     "stop",
		Network: &withruntime.Network{
			Internet: true,
			Allow:    []string{"proxy.golang.org", "*.githubusercontent.com"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)
	fmt.Println(sbx.ID(), sbx.Info().Funding, sbx.Info().ExpiresAt)
}
```

A field newer than the SDK goes in `Extra`. The SDK merges `Extra` into the request.

## Run commands

`Exec` runs a string under `bash -c`. `ExecArgv` runs a program directly, with no
shell. Use it for untrusted arguments.

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	if _, err := sbx.Exec(ctx, "mkdir -p app && echo 'print(1 + 1)' > app/main.py", nil); err != nil {
		log.Fatal(err)
	}
	run, err := sbx.ExecArgv(ctx, []string{"python3", "main.py"}, &withruntime.ExecOptions{
		Cwd:     "/workspace/app",
		Env:     map[string]string{"API_TOKEN": os.Getenv("API_TOKEN")},
		Timeout: 2 * time.Minute,
	})
	if err != nil {
		log.Fatal(err)
	}
	if *run.ExitCode != 0 {
		fmt.Println(run.Stderr)
	}
	fmt.Print(run.Stdout)
}
```

- `Env` is how secrets reach a command. It is never echoed back, and journals
  record a hash, not the value. Never put a secret in the command line itself.
- `Stdin` gives the command input, then closes it.
- `User: "root"` runs the command as root, with no `sudo` in front, keeping its
  `Env` and `PATH`; `HOME` is `/root`. `SpawnOptions` and `TerminalOptions`
  take it too, and `ProcessInfo.User` says which a process runs as.
- The default timeout is 60 seconds; the maximum is 24 hours. A timeout is a
  result (`TimedOut` is true, with the output so far), not an error.
- `Check: true` returns a `*withruntime.CommandError`, with the exit code and
  output, on a non-zero exit or a timeout.
- A result holds all of `Stdout` and `Stderr`, up to 256 MiB of each; with
  `OnStdout` or `OnStderr` there is no limit.
  `StdoutBytes` and `StderrBytes` give the bytes each stream wrote.
  `MaxOutputBytes` keeps at most that many bytes of each stream;
  `StdoutTruncated`, `StderrTruncated` and `Truncated` are then true for a
  stream that was cut. With `OnStdout` or `OnStderr`, or a `Timeout` over
  60 seconds, the command streams instead.

Stream output as it happens with callbacks, or range over the events:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	_, err = sbx.Exec(ctx, "for i in 1 2 3; do echo line $i; sleep 1; done", &withruntime.ExecOptions{
		OnStdout: func(text string) { fmt.Print(text) },
	})
	if err != nil {
		log.Fatal(err)
	}
	for event, err := range sbx.ExecStream(ctx, "node --version", nil) {
		if err != nil {
			log.Fatal(err)
		}
		switch event.Type {
		case "stdout":
			fmt.Print(event.Data)
		case "exit":
			fmt.Println("exit", *event.ExitCode)
		}
	}
}
```

A long stream resumes by itself when the server ends it, so no output is
dropped. The sandbox keeps the latest 1 MiB of a command's output. A reader that
falls further behind gets a `truncated` event.

## Background processes

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	server, err := sbx.Spawn(ctx, "python3 -m http.server 8000", &withruntime.SpawnOptions{Cwd: "/workspace"})
	if err != nil {
		log.Fatal(err)
	}
	repl, err := sbx.SpawnArgv(ctx, []string{"python3", "-i", "-q"}, &withruntime.SpawnOptions{PipeStdin: true})
	if err != nil {
		log.Fatal(err)
	}
	if err := repl.Write(ctx, []byte("print(21 * 2)\n"), true); err != nil {
		log.Fatal(err)
	}
	done, err := repl.Wait(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(done.Stdout)

	processes, err := sbx.Processes(ctx)
	if err != nil {
		log.Fatal(err)
	}
	for _, process := range processes {
		fmt.Println(process.ID, process.State, process.Command)
	}
	if err := server.Kill(ctx, "SIGTERM"); err != nil {
		log.Fatal(err)
	}
}
```

`process.Output(ctx, 0)` yields every event from the start until the process
exits. A process outlives your connection. Get it back with
`sbx.Process(ctx, id)`. `Write` tracks input offsets, so a retried write is never
typed twice.

## Files

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	if err := sbx.Files.Write(ctx, "/workspace/data/input.csv", []byte("a,b\n1,2\n")); err != nil {
		log.Fatal(err)
	}
	text, err := sbx.Files.ReadText(ctx, "/workspace/data/input.csv")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(text)
	entries, err := sbx.Files.List(ctx, "/workspace", &withruntime.FileListOptions{Depth: 2})
	if err != nil {
		log.Fatal(err)
	}
	for _, entry := range entries {
		fmt.Println(entry.Type, entry.Size, entry.Path)
	}
	if err := sbx.Files.Mkdir(ctx, "/workspace/out", true); err != nil {
		log.Fatal(err)
	}
	if err := sbx.Files.Rename(ctx, "/workspace/data/input.csv", "/workspace/out/input.csv", false); err != nil {
		log.Fatal(err)
	}
	if err := sbx.Files.Upload(ctx, "./testdata", "/workspace/project"); err != nil {
		log.Fatal(err)
	}
	if err := sbx.Files.Download(ctx, "/workspace/out", "./out"); err != nil {
		log.Fatal(err)
	}
}
```

`Write` makes parent directories and replaces the file atomically. A file over
1 MiB goes in parallel chunks, checked by SHA-256. `Stat` returns `nil` for a
path that does not exist. `Upload` and `Download` move a whole directory as one
gzipped tar archive. They use the API's folder routes, which pack and unpack it
with `tar` inside the sandbox ([files in the API guide](./api#files)). A large
one uploads in parts. A downloaded folder is unpacked as it arrives. It lands
in place only once it has all arrived. A download cut short fails with
`download_incomplete` and writes nothing.

### Links

A link is a secret URL that anyone can open, with no API key. A GET downloads
the file. Range works, so videos play and downloads resume. A PUT with the raw
body uploads the file atomically. A link expires in 1 hour by default, and at
most 7 days. `RevokeLinks` ends every link made for the sandbox. Revoking the
key that made a link also ends its links.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	down, err := sbx.Files.DownloadURL(ctx, "/workspace/report.csv", &withruntime.DownloadURLOptions{
		Filename:         "report.csv",
		ExpiresInSeconds: 600,
	})
	if err != nil {
		log.Fatal(err)
	}
	up, err := sbx.Files.UploadURL(ctx, "/workspace/incoming.bin", &withruntime.UploadURLOptions{MaxBytes: 10 << 20})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(down.URL, down.ExpiresAt, up.URL)
	if _, err := sbx.Files.RevokeLinks(ctx); err != nil {
		log.Fatal(err)
	}
}
```

## Pause, wake, extend, fork and snapshot

```go
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, &withruntime.CreateOptions{})
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	if err := sbx.Pause(ctx, nil); err != nil { // memory and files are kept; compute billing stops
		log.Fatal(err)
	}
	again, err := client.Sandboxes.Get(ctx, sbx.ID())
	if err != nil {
		log.Fatal(err)
	}
	if err := again.Wake(ctx, 20*time.Minute, nil); err != nil {
		log.Fatal(err)
	}
	if err := again.Extend(ctx, 10*time.Minute, nil); err != nil {
		log.Fatal(err)
	}

	copies, err := again.Fork(ctx, &withruntime.ForkOptions{Count: 2})
	if err != nil {
		log.Fatal(err)
	}
	for _, copied := range copies {
		fmt.Println("fork", copied.ID(), copied.State())
		_ = copied.Stop(ctx, nil)
	}
	snapshot, err := again.Snapshot(ctx, &withruntime.SnapshotOptions{Name: "ready", RetentionDays: 7})
	if err != nil {
		log.Fatal(err)
	}
	fromSnapshot, err := client.Sandboxes.Create(ctx, &withruntime.CreateOptions{Snapshot: snapshot.ID})
	if err != nil {
		log.Fatal(err)
	}
	_ = fromSnapshot.Stop(ctx, nil)
	if err := client.Snapshots.Delete(ctx, snapshot.ID); err != nil {
		log.Fatal(err)
	}
}
```

A fork copies a sandbox as it is now, with its files, memory and running
processes. It runs on its server while there is room, and on another server when
it is full. See [JavaScript](./javascript) for what forks and snapshots keep and
how they are billed. If a copy fails, the error's
`Details["startedSandboxIds"]` names the copies that did start.

## Share a port

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	if _, err := sbx.Spawn(ctx, "python3 -m http.server 3000", nil); err != nil {
		log.Fatal(err)
	}
	preview, err := sbx.Previews.Create(ctx, 3000, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(preview.URL, *preview.Token) // send the token as x-runtime-preview-token
}
```

A preview is private by default. `Visibility: "public"` shares it with anyone
who has the address. Addresses are under `runtimehost.com`.

## Sandboxes by name, and keeping one running

`Sandboxes.GetOrCreate(ctx, name, opts)` returns the sandbox with that name. It
wakes the sandbox if paused, and restarts it if stopped and persistent. Otherwise
it creates one with `opts`. `Info().Reused` says which. A sandbox with no time
limit runs while it works, with nothing to renew. `Persistent: true` keeps a paid
sandbox running until you stop it, idle or not, while credit lasts. `KeepAlive`
moves a time limit on from your process, keeping ten minutes ahead, until `Stop`
or `StopKeepAlive`. On a sandbox with no limit, it only watches.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	dev, err := client.Sandboxes.GetOrCreate(ctx, "dev", &withruntime.CreateOptions{IdlePauseSeconds: 900})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(dev.ID(), dev.Info().Reused)

	dev.KeepAlive(ctx, nil)
	defer dev.StopKeepAlive()
}
```

## An interactive terminal

`sbx.Terminal` opens a shell over a WebSocket. It is an `io.ReadWriteCloser`:
write what you type, read what it prints.

```go
package main

import (
	"context"
	"io"
	"log"
	"os"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	term, err := sbx.Terminal(ctx, &withruntime.TerminalOptions{Cols: 120, Rows: 40})
	if err != nil {
		log.Fatal(err)
	}
	defer term.Close()
	if _, err := term.Write([]byte("uname -a; exit\n")); err != nil {
		log.Fatal(err)
	}
	if _, err := io.Copy(os.Stdout, term); err != nil {
		log.Fatal(err)
	}
}
```

## Images, volumes and snapshots

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	image, err := client.Images.Build(ctx, withruntime.CreateImageOptions{
		Name:   "data",
		Recipe: &withruntime.ImageRecipe{Pip: []string{"pandas"}, Apt: []string{"jq"}},
	}, func(line withruntime.ImageLogLine) { fmt.Println(line.Text) })
	if err != nil {
		log.Fatal(err)
	}
	volume, err := client.Volumes.Create(ctx, withruntime.CreateVolumeOptions{SizeMiB: 10240, Name: "cache"})
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, &withruntime.CreateOptions{
		Image:   image.ID,
		Volumes: []withruntime.VolumeMount{{VolumeID: volume.ID, Path: "/data"}},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)
	result, err := sbx.Exec(ctx, "python3 -c 'import pandas; print(pandas.__version__)'", nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(result.Stdout)
}
```

`Images.Build` waits until the image is ready. If the build fails, it returns
an `*Error` whose code is `image_failed`. `Images.Create` queues the build and
returns. A Dockerfile build takes `Dockerfile` and `ContextDir`. `ContextDir` is
the folder `docker build` would read, with its `.dockerignore`. Only the parts
of the folder that the server does not have yet are uploaded. `Images.Resolve`,
`Tag`, `Untag`, `Versions`, `FollowLogs` and `Images.Registries.Set` cover private
images and other image tasks. See [custom images](./images). A volume lives on
one server. Daily backups are enabled by default. `BackedUp` becomes true after
a backup has been copied off the host and checked. A sandbox with volumes
cannot be snapshotted.

## Code interpreter, network rules and secrets

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer sbx.Stop(context.Background(), nil)

	if _, err := sbx.Interpreter.Run(ctx, "import math\nx = math.pi", nil); err != nil {
		log.Fatal(err)
	}
	cell, err := sbx.Interpreter.Run(ctx, "round(x * 2, 3)", nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(cell.Results[0].Data["text/plain"])

	policy, err := sbx.Network.Set(ctx, withruntime.Network{Internet: true, Allow: []string{"pypi.org", "*.pythonhosted.org"}})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(policy.Enforced, policy.Allow)

	secret, err := client.Secrets.Set(ctx, "OPENAI_API_KEY", withruntime.SetSecretOptions{
		Value: "sk-...",
		Hosts: []string{"api.openai.com"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(secret.Placeholder) // what sandboxes see in $OPENAI_API_KEY
}
```

`sbx.Desktop` drives a Linux desktop in the sandbox (`Start`, `Open`, `Click`,
`Type`, `Press`, `Screenshot`), as in [JavaScript](./javascript).

## Metrics, events and webhooks

```go
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	hook, err := client.Webhooks.Create(ctx, withruntime.CreateWebhookOptions{URL: "https://example.com/hooks/runtime"})
	if err != nil {
		log.Fatal(err)
	}
	secret := hook.Secret // shown once; keep it
	http.HandleFunc("/hooks/runtime", func(w http.ResponseWriter, r *http.Request) {
		body, _ := io.ReadAll(r.Body)
		event, err := withruntime.VerifyWebhook(body, r.Header.Get("Runtime-Signature"), []string{secret}, 0)
		if err != nil {
			http.Error(w, "bad signature", http.StatusUnauthorized)
			return
		}
		fmt.Println(event.Type)
		w.WriteHeader(http.StatusNoContent)
	})
	for event, err := range client.Events.All(ctx, &withruntime.EventListOptions{Type: "sandbox.stopped"}) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(event.CreatedAt, event.Type)
	}
}
```

`sbx.Metrics(ctx, "15m")` returns the sandbox's measured CPU and memory, and
`client.Otel.Create` pushes events and metrics to an OpenTelemetry endpoint.
See [metrics and webhooks](./observability).

## An endpoint newer than the SDK

`client.Request` calls any API path with the client's key, retries,
idempotency keys and errors:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	var page map[string]any
	if err := client.Request(context.Background(), "GET", "/v1/volumes", nil, &page); err != nil {
		log.Fatal(err)
	}
	fmt.Println(page["data"])
}
```

## Find sandboxes again

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	filter := &withruntime.ListOptions{Labels: map[string]string{"team": "search"}, State: []string{"running"}}
	for sbx, err := range client.Sandboxes.All(ctx, filter) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(sbx.ID(), sbx.State())
	}
}
```

`Sandboxes.List` returns one page (`Data`, `HasMore`, `Next`); `All` walks every
page.

## Errors and retries

```go
package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	_, err = client.Sandboxes.Get(ctx, "00000000-0000-4000-8000-000000000000")
	var failure *withruntime.Error
	switch {
	case errors.Is(err, withruntime.ErrNotFound):
		fmt.Println("no such sandbox")
	case errors.As(err, &failure):
		fmt.Println(failure.Code, failure.Hint, failure.RequestID)
	}
}
```

Every error is a `*withruntime.Error` with `Code`, `Message`, `Hint`,
`RequestID`, `Status` and `Details`. `errors.Is` matches it against
`ErrAuthentication`, `ErrPermissionDenied`, `ErrNotFound`, `ErrConflict`,
`ErrInvalidRequest`, `ErrRateLimited`, `ErrServiceUnavailable` and
`ErrConnection`. These are the same classes as in the JavaScript and Python SDKs.
`no_capacity` matches `ErrServiceUnavailable`. `no_credit_running_limit`, and a
`quota_exceeded` on what runs concurrently, match `ErrRateLimited`. A `quota_exceeded`
on what is kept matches `ErrConflict`.

Every write carries an idempotency key. The SDK makes it for you and keeps it
across the client's own retries. Transport failures, and every response that
says `retryable: true`, are retried after its `Retry-After`. Retries stop at the
maximum number of retries. They use the same key, so a retry never makes two
sandboxes or runs a command twice. A wait over 60 seconds is not slept on. The
error is returned immediately, with `retryAfterMs`. A response that ran nothing
(`guest_busy`, `busy`, `rate_limited`, `sandbox_starting`) is sent again until
the call's deadline.
Without a deadline, it is sent again for five minutes, past the maximum.
`Retryable()` says whether trying the same call again may work.

**A create, wake or restart waits for room.** When all four slots without credit are taken (`no_credit_running_limit`), the
account is at its limit (`quota_exceeded`), or the region is full
(`no_capacity`), `Sandboxes.Create` waits. It sends the same request again, for
up to two minutes. A burst of CI jobs past the limit queues instead of failing.
Set `withruntime.WithWaitForCapacity` on the client, or `WaitForCapacity` on one
create, wake or restart. Zero fails immediately. A sandbox stays on its server.
So a wake or restart refused with `no_capacity` is sent again with the same
idempotency key until room frees. A fork waits the same way when no server has
room for a copy; set `WaitForCapacity` on its `ForkOptions` to change the wait.

## Read-only keys and daily limits

An owner, admin or developer can make a read-only key and set a daily spending
limit on a key, on the
[API keys](https://withruntime.com/account/keys) page. `client.Limits.Get(ctx)`
reads both. Past the limit, a create, wake or extension returns an error whose
code is `spending_limit_reached`. It is not retried. See
[security](./security).

## Configuration

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"withruntime.com/go"
)

func main() {
	client, err := withruntime.New(
		withruntime.WithAPIKey(os.Getenv("MY_RUNTIME_KEY")),
		withruntime.WithTimeout(2*time.Minute),
		withruntime.WithMaxRetries(4),
		withruntime.WithWaitForCapacity(10*time.Minute),
	)
	if err != nil {
		log.Fatal(err)
	}
	me, err := client.Me(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(me.OrgID)
}
```

- `RUNTIME_API_URL` points the client at another API origin, as
  `WithBaseURL` does.
- Code inside a Runtime sandbox calls Runtime's API at `http://runtime.internal`
  ([Runtime's API from inside a sandbox](./sandbox-environment#runtime-s-api-from-inside-a-sandbox)).
- The client is safe for concurrent use. Make one and share it: it keeps its
  connections open and holds at most 32 calls in flight
  (`WithMaxConnections`).
- It honours `HTTPS_PROXY` and `NO_PROXY`. `WithHTTPClient` supplies your own
  `*http.Client`.
- Money is integer microdollars: 1,000,000 is one US dollar. `client.Usage(ctx)`
  returns the account's balance as exact decimal strings.
- `client.UsageExport(ctx, withruntime.UsageExportOptions{Since: ..., Until: ..., Cursor: ...})`
  reads one page of settled usage over a UTC range, with its server CSV.
  Follow `NextCursor` until it is nil. `FinalThrough` is the time before which
  no more charges will settle. A row's `Final` is true once its resource is
  deleted and can be charged nothing more
  ([export settled usage](./api#export-settled-usage)).

## Domains, public ports and private networking

`client.Domains`, `Ports`, `Addresses` and `Tunnel` are account products.
Domains and public ports name the sandbox they serve. `Tunnel` manages a
WireGuard network; `sbx.OpenTunnel` and `sbx.PortForward` open authenticated TCP
connections from your process into one sandbox.

When you use `OpenTunnel` directly, read responses while you write requests.
Each stream keeps at most 1 MiB of unread response data. If its reader falls
behind that limit, reads return `tunnel_receive_overflow` after the buffered
data. Other streams keep working. `PortForward` drains both directions for you.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Get(ctx, "11111111-2222-4333-8444-555555555555")
	if err != nil {
		log.Fatal(err)
	}
	domain, err := client.Domains.Add(ctx, withruntime.AddDomainOptions{
		Hostname: "app.example.com", SandboxID: sbx.ID(), Port: 3000,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(domain.Records) // Publish these at your DNS provider, then call Domains.Verify.
	address, err := client.IPs.Reserve(ctx, 4)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(address.Address, address.Funded, address.FundedUntil)
	forward, err := sbx.PortForward(ctx, 5432, "127.0.0.1:0")
	if err != nil {
		log.Fatal(err)
	}
	defer forward.Close()
	fmt.Println(forward.Addr()) // Connect your local database client here.
}
```

`Ports.Open` returns `Connect`, the public address and port. `Networks.WireGuard.Create`
creates the account's WireGuard network. `AddPeer` and `RotatePeer` return a
configuration that holds a generated private key, shown once. Save `Config` even
when `ConfigReady` is false. It is a draft. Fill in its gateway public key from
`Networks.WireGuard.Get` before use. A request for a generated key is never
retried automatically. To keep the private key entirely on your machine, supply `PublicKey`.

Dedicated addresses and WireGuard networks expose `Funded`, `FundedUntil`,
`RateMicros` and `RateUnit`. When credit runs out, traffic stops. The
reservation is kept until you release it. `SSO.Get` reads sign-on and directory
status, and the website address where an owner manages it.

## Backup and restore volumes

`Volumes.Backup` requests a checked copy off the host. `Backups` lists copies.
`GetBackup` and `DeleteBackup` read or remove one. `SetBackupPolicy` changes
daily backups or retention. It can also back up the volume on a schedule of its
own:
`SetBackupPolicyOptions{Schedule: &withruntime.BackupSchedule{EveryMinutes: 60},
Keep: &withruntime.BackupKeep{Hourly: 24, Daily: 7}}` (or `Cron: "30 2 * * 1-5"`,
in UTC). `NoSchedule: true` goes back to daily. Restore makes a new volume from
a ready backup.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	backup, err := client.Volumes.Backup(ctx, "11111111-2222-4333-8444-555555555555", nil)
	if err != nil {
		log.Fatal(err)
	}
	if backup.State != "ready" {
		fmt.Println("Backup is still running; poll Volumes.GetBackup:", backup.ID)
		return
	}
	volume, err := client.Volumes.Restore(ctx, backup.ID, &withruntime.CreateVolumeOptions{Name: "restored"})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(volume.ID, volume.State, volume.RestoredFrom)
}
```

## Permissions and file watching

Pass `FileWriteOptions` to set permissions with the content. A pointer keeps
mode `000` distinct from the default. Current guest images require only
`write_file`. Older images require `exec` for the SDK's chmod fallback.
`Files.Chmod` sets an existing file's permissions through the same exec grant.
A supplied write key identifies the whole upload. Each mutation phase has its
own stable key. A repeat of a completed upload returns without sending its
chunks again.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	sbx, err := client.Sandboxes.Get(ctx, "11111111-2222-4333-8444-555555555555")
	if err != nil {
		log.Fatal(err)
	}
	mode := uint32(0o755)
	if err := sbx.Files.Write(ctx, "/workspace/run.sh", []byte("#!/bin/sh\necho ready\n"), &withruntime.FileWriteOptions{Mode: &mode}); err != nil {
		log.Fatal(err)
	}
	watch, err := sbx.Files.Watch(ctx, "/workspace", &withruntime.WatchOptions{Recursive: true, Exclude: []string{"node_modules"}})
	if err != nil {
		log.Fatal(err)
	}
	defer watch.Stop(context.Background())
	for batch, err := range watch.Events(ctx) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(batch.Kind, batch.Events, batch.Reason, watch.Cursor())
	}
}
```

`Events` reconnects on a continuation and keeps its cursor. A pause ends
iteration without stopping the guest watch. After waking the sandbox, call
`Events` again. `overflow` and `lost` notices mean you should rescan. Breaking
iteration closes its HTTP response. `Stop` also stops the guest watch.
`Files.Watches.List` and `Read` let you find watches and poll instead.

## Bucket mounts and recordings

`sbx.Mounts.Add` mounts a customer bucket, using the name of a Runtime secret.
`List` and `Remove` manage mounts. The sandbox never receives the bucket key.
`sbx.Desktop.Recordings` has `Start`, `Get`, `List`, `Stop`, `Download` and
`Delete`. Downloaded bytes are MP4.

## CI/CD (beta)

`client.CI` reads CI/CD. It checks every push and pull request of a connected
GitHub repository in sandboxes. `CI.Repositories` has `Connect`, `List` and
`Disconnect`. Only a full key can connect one. `CI.Checks.List` and `Get`,
`CI.Jobs.Get` (with the tail of the job's log), and `CI.Tests.List` read what
ran. `CI.Releases.List` reads a release's steps as they were taken. Times are
milliseconds since the epoch. Lists page like the others. An account outside the
beta gets `product_in_beta` (403).

```go check
package main

import (
	"context"
	"fmt"
	"log"

	"withruntime.com/go"
)

func main() {
	ctx := context.Background()
	client, err := withruntime.New()
	if err != nil {
		log.Fatal(err)
	}
	repository, err := client.CI.Repositories.Connect(ctx, "acme/web", nil)
	if err != nil {
		log.Fatal(err)
	}
	for check, err := range client.CI.Checks.All(ctx, &withruntime.CICheckListOptions{RepositoryID: repository.ID, State: []string{"failed"}}) {
		if err != nil {
			log.Fatal(err)
		}
		detail, err := client.CI.Checks.Get(ctx, check.ID)
		if err != nil {
			log.Fatal(err)
		}
		for _, job := range detail.Jobs {
			if job.State == "failed" {
				failed, err := client.CI.Jobs.Get(ctx, job.ID)
				if err != nil {
					log.Fatal(err)
				}
				fmt.Println(job.Name, failed.Log) // job.SandboxIDs may still be paused, to wake and look into.
			}
		}
	}
}
```


---

<!-- https://withruntime.com/docs/harbor -->

# Runtime for Harbor and Terminal-Bench

Run Harbor trials, Terminal-Bench 2.0 among them, each in its own Runtime microVM, with the task and the agent unchanged.

`RuntimeEnvironment` is a Harbor environment, like its Docker, E2B or Modal
environments. Harbor loads it by import path, so it works with the Harbor you
already have. Each trial gets a Firecracker microVM with its own kernel, built
from the task's own `Dockerfile` or `docker_image`, and you pay for the CPU it
uses rather than the CPUs it holds.

## Install

```bash no-run
pip install "withruntime[harbor]"
```

Harbor needs Python 3.12 or newer. The key comes from `RUNTIME_API_KEY`, or from
`npx withruntime login` on this machine, as in the rest of the SDK.

## Run a benchmark

Pass the environment's import path to `-e`, and its options with `--ek`:

```bash no-run
harbor run -t hello-world/hello-world -a oracle -e withruntime.harbor:RuntimeEnvironment
harbor run -d terminal-bench@2.0 -a oracle -e withruntime.harbor:RuntimeEnvironment --n-concurrent 8
```

The `oracle` agent runs each task's reference solution against its tests, so it
checks the environment without calling a model. Swap in your own agent and
model with `-a` and `-m`.

In a job config, or from Python:

```python check
import asyncio

from harbor.job import Job
from harbor.models.job.config import JobConfig
from harbor.models.trial.config import AgentConfig, EnvironmentConfig, TaskConfig


async def main():
    job = await Job.create(
        JobConfig(
            environment=EnvironmentConfig(
                import_path="withruntime.harbor:RuntimeEnvironment",
            ),
            agents=[AgentConfig(name="oracle")],
            tasks=[TaskConfig(name="hello-world/hello-world")],
        )
    )
    await job.run()


asyncio.run(main())
```

## Options

Every option is optional.

| `--ek`     | What it does                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| `funding`  | Accepted and ignored: the free usage is spent first, then prepaid credit                                                  |
| `region`   | The region to run in; left out, the default                                                                               |
| `image`    | A Runtime image (id, name or `name:tag`) to start every trial from, instead of building the task's                        |
| `build`    | Build limits, such as `build='{"disk_mib": 16384}'`: `vcpu`, `memory_mib`, `disk_mib`, `max_image_mib`, `timeout_seconds` |
| `labels`   | Your own labels on each sandbox and image                                                                                 |
| `base_url` | Another API address; `RUNTIME_API_URL` does the same                                                                      |

## What runs in the sandbox

| Harbor                                   | Runtime                                                                                                                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment/Dockerfile`, `docker_image` | A [custom image](./images), built once and kept as `harbor-<task>` with a tag from a hash of the environment. Reruns start from it; `--force-build` builds it again             |
| `cpus`, `memory_mb`, `storage_mb`        | `vcpu`, `memory_mib`, `disk_mib`. A sandbox without credit is at most 2 vCPU, 4 GiB and 10 GiB of disk; a larger request without credit runs at that size, with a warning       |
| Commands                                 | `bash -c` (`sh -c` in an image without bash), in the task's `workdir` or the Dockerfile's `WORKDIR`, with the task's and the agent's environment. Output streams, however large |
| Users                                    | Root by default, as in Docker, and any named user, through `sudo`                                                                                                               |
| Files                                    | Uploads and downloads of any size, anywhere in the machine, as root                                                                                                             |
| Network policies                         | `no-network`, and allow-lists of hostnames, `*.domain` wildcards, IPv4 addresses and IPv4 CIDR ranges, changed while the trial runs                                             |
| Long trials                              | The sandbox runs while the trial works, however long it takes                                                                                                                   |

**Root and `sudo`.** Commands in a Runtime sandbox run as the sandbox user,
uid 1000, and Harbor runs them as root. The environment runs root commands
through the sandbox user's passwordless `sudo`, which Runtime's base image
has. Runtime adds it to every image it builds, including images built from a
public image. An image built before 25 September 2026 may lack it. Rebuilding
adds it. The environment checks when the trial starts. If `sudo` is missing, it
stops the trial and shows this line to add to the task's `Dockerfile`:

```dockerfile
RUN apt-get update && apt-get install -y sudo && echo '#1000 ALL=(ALL:ALL) NOPASSWD: ALL' > /etc/sudoers.d/runtime
```

**Not supported:** Docker Compose tasks with sidecar services, GPUs, Windows
tasks, IPv6 allow-list entries, and Harbor's stream mode, which Harbor offers
only to its built-in environments.

## Limits to plan for

- The trial runs four sandboxes at the same time, so keep `--n-concurrent` at 4 or
  below without credit. A paid account runs more; see [pricing](./pricing#how-many-at-once).
- Each task is its own image. Builds run one at a time until your account holds
  credit, then four. An account without credit keeps its first three images free;
  after that they are billed as stored images
  ([pricing](./pricing#snapshots-images-and-volumes)). `runtime images ls` lists
  them and `runtime images rm` removes them.
- Harbor stops each sandbox when its trial ends.

## What was verified

On 25 September 2026 the environment ran under Harbor 0.23.0 against a fake
Runtime API whose sandbox is a folder on the test machine: Harbor loading it by
import path, building an image once and reusing it, `--force-build`, root and
uid 1000 commands through a real `sudo`, the Dockerfile's `WORKDIR`, task and
per-command variables, streamed output, a 40 KB command with 80 variables,
timeouts, directory and file transfers, the refusal when `sudo` is missing, the
trial's sizes, network policies and cleanup. On the same fake, a whole
`harbor run -a oracle` of Harbor's hello-world example task, with its verifier
changed to check the file without installing packages on the test machine,
scored 1.


---

<!-- https://withruntime.com/docs/identity-tokens -->

# Identity tokens

Code in a sandbox can prove which sandbox it is, without a stored key. Runtime
signs a short-lived OpenID Connect token that names the sandbox, its
organization and its image. Your AWS or Google Cloud account trusts Runtime
once. Then it lets a sandbox assume a role with the token. Your own API can accept
it too. It works like GitHub Actions' OIDC tokens. It is free.

## Get a token

Inside a sandbox, with no API key:

```bash no-run
runtime sandboxes identity-token --audience sts.amazonaws.com
```

```ts check
import { Sandbox } from "withruntime";

const { token, subject } = await Sandbox.identityToken({ audience: "sts.amazonaws.com" });
console.log(subject, token.length);
```

```python check
from withruntime import Sandbox

token = Sandbox.identity_token("sts.amazonaws.com")
print(len(token))
```

Or use curl, the way GitHub Actions does. Commands in a running sandbox
have these two variables. A [scheduled job](./jobs)'s run has them in its
command's environment too, so a job can get tokens the same ways:

```bash no-run
curl -H "Authorization: Bearer $RUNTIME_ID_TOKEN_REQUEST_TOKEN" \
  "$RUNTIME_ID_TOKEN_REQUEST_URL?audience=sts.amazonaws.com"
```

- `audience` is required. It names who the token is for. Use `sts.amazonaws.com` for
  AWS, your workload identity provider's name for Google Cloud, or your API's
  name.
- A token lasts 10 minutes. To set a different lifetime, pass 60 to 3600 seconds in `lifetimeSeconds`
  (`--lifetime` in the CLI). Get a fresh token when it runs out.
- The options can also go in a JSON body (`Content-Type: application/json`)
  of at most 4 KiB. A body that has not arrived within 5 seconds returns
  408 `request_timeout`. Nothing was issued, so send it again.
- `RUNTIME_ID_TOKEN_REQUEST_TOKEN` is the sandbox's own proof of who it is. It
  can get tokens only for this sandbox, and only while it is running. It stops
  working when the sandbox stops or pauses. Treat it like a password anyway. Anyone who
  copies it can get tokens as this sandbox until then.
- The request token changes with each renewal of the sandbox's lease. A fork's
  programs keep the source's token. A program that runs a long time, or was
  copied, reads the current one again from
  `http://runtime.internal/v1/environment` (JSON, with both variables). The
  JavaScript and Python SDKs do this for you when a token they hold is refused,
  or when the process has no variables at all.
- A program that has neither variable reads them the same way. This applies to a
  program started before they were set, or to a sandbox kept from older guest software. The host
  returns a result for every running sandbox, whatever its image or age. This needs
  nothing installed but curl:

```bash no-run
token=$(curl -s http://runtime.internal/v1/environment |
  sed -n 's/.*"RUNTIME_ID_TOKEN_REQUEST_TOKEN": *"\([^"]*\)".*/\1/p')
curl -H "Authorization: Bearer $token" \
  "http://runtime.internal/v1/identity/token?audience=sts.amazonaws.com"
```

- Use the supplied `RUNTIME_ID_TOKEN_REQUEST_URL`. It points to Runtime's
  internal token relay, which accepts only this sandbox's current request
  token. You do not need to allow access to the host's public address.

## What a token says

| Claim          | Example                                                |
| -------------- | ------------------------------------------------------ |
| `iss`          | `https://withruntime.com/oidc`                         |
| `sub`          | `org:<org-id>:image:<image>:sandbox:<sandbox-id>`      |
| `aud`          | The audience you asked for                             |
| `org_id`       | Your organization's id (`runtime whoami` shows it)     |
| `sandbox_id`   | The sandbox's id                                       |
| `sandbox_name` | Its name, if it has one                                |
| `image`        | The image's name, its id if it has no name, or `base`  |
| `image_id`     | The image's id, for a sandbox made from one            |
| `image_digest` | `sha256:...` of the image, for a sandbox made from one |
| `funding`      | `paid` or `trial`                                      |
| `region`       | Where the sandbox runs                                 |
| `exp`, `iat`   | When it expires and when it was issued                 |

A scheduled job's run also says which job it is:

| Claim              | What it is                                                   |
| ------------------ | ------------------------------------------------------------ |
| `job_id`           | The job's id                                                 |
| `job_name`         | Its name                                                     |
| `job_version`      | Its version, which grows with each change                    |
| `job_run_id`       | This run                                                     |
| `job_made_by`      | The agent or person that made it                             |
| `job_made_by_kind` | `agent` or `person`                                          |
| `job_vouched_by`   | The owner or admin who vouched for it, while it is unchanged |

A copy of an App also says which App it is. The copy's own id changes
at every deploy, restart and scale-up, so these claims name the App instead:

| Claim         | What it is                    |
| ------------- | ----------------------------- |
| `app_id`      | The App's id                  |
| `app_name`    | Its name, if it has one       |
| `app_version` | The id of the version it runs |

An owner or admin vouches for a job on its page in the console, signed in. No
API key can vouch. Only runs that start after the vouch carry the name. Any change
to the job's command, schedule or size clears the vouch, even if the job is
later put back as it was, until someone vouches again. A job that uses secrets cannot be vouched
for. The vouch also covers the egress secrets and upstream proxy its runs can
get: a change to a secret with no scope, to a label or App scope, to a
secret's policy, or to the proxy clears it until someone vouches again. A
scope that lists sandbox IDs never clears it, since a run is a new sandbox no
list names; a run whose own sandbox ID is added to one carries no name. If anything other than the job
reached a run's sandbox (a command or file call, a preview, a port or
domain, a snapshot, or an attached volume), that run's tokens name no job at
all, since what runs there may not be the job's. The next run starts fresh. A token that names a voucher lives five minutes at most, whatever you ask for. So an API that does something only a person should allow can accept a
job's call only when `job_vouched_by` is there, as Runtime's own billing jobs
do.

`sub` is built for trust policies. `org:<org-id>:*` matches every sandbox of
your organization. `org:<org-id>:image:api-worker:*` matches only those made from
the image `api-worker`. No part of it can contain a colon.

Tokens are signed with RS256. The discovery document is at
`https://withruntime.com/oidc/.well-known/openid-configuration`, and the keys are at
`https://withruntime.com/oidc/jwks`. Runtime publishes a new key an hour before
it signs with it. It keeps an old key published for two hours after it stops,
so a verifier that caches the keys never misses one.

## AWS

1. In IAM, add an **OpenID Connect** identity provider: provider URL
   `https://withruntime.com/oidc`, audience `sts.amazonaws.com`.
2. Create a role with this trust policy, with your account and organization
   ids:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/withruntime.com/oidc"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": { "withruntime.com/oidc:aud": "sts.amazonaws.com" },
        "StringLike": { "withruntime.com/oidc:sub": "org:<your-org-id>:*" }
      }
    }
  ]
}
```

3. In the sandbox, let the AWS CLI and SDKs pick it up:

```bash no-run
runtime sandboxes identity-token --audience sts.amazonaws.com --lifetime 3600 > /tmp/aws-token
export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/runtime-sandbox
export AWS_WEB_IDENTITY_TOKEN_FILE=/tmp/aws-token
aws sts get-caller-identity
```

For work that runs longer than an hour, write the file again before the token expires.

## Google Cloud

Create a workload identity pool and an OIDC provider that trusts Runtime.
Map the subject and the organization:

```bash no-run
gcloud iam workload-identity-pools create runtime --location=global
gcloud iam workload-identity-pools providers create-oidc runtime \
  --location=global --workload-identity-pool=runtime \
  --issuer-uri=https://withruntime.com/oidc \
  --attribute-mapping="google.subject=assertion.sub,attribute.org_id=assertion.org_id,attribute.image=assertion.image" \
  --attribute-condition="assertion.org_id == '<your-org-id>'"
```

Grant the pool's principals access (for example,
`roles/iam.workloadIdentityUser` on a service account). Then, in the sandbox, ask
for a token whose audience is the provider's full name,
`//iam.googleapis.com/projects/<number>/locations/global/workloadIdentityPools/runtime/providers/runtime`.
Exchange it with Google's STS, or point a credential configuration file at
a file that holds the token.

## Your own API

Verify the token with any OIDC library. Fetch the keys from
`https://withruntime.com/oidc/jwks`. Check the signature, that `iss` is
`https://withruntime.com/oidc`, that `aud` is your API's name, and that it has
not expired. Then trust `org_id`, `sandbox_id` and `image`.

```js
// With the jose library (npm install jose).
import { createRemoteJWKSet, jwtVerify } from "jose";

const keys = createRemoteJWKSet(new URL("https://withruntime.com/oidc/jwks"));
export async function sandboxOf(token) {
  const { payload } = await jwtVerify(token, keys, {
    issuer: "https://withruntime.com/oidc",
    audience: "https://api.example.com",
  });
  return { org: payload.org_id, sandbox: payload.sandbox_id };
}
```

## Limits

- Tokens are for running sandboxes, a job's runs included. Code outside a
  sandbox has nothing to ask with. No API key can get one: a key that
  leaked could then pass for any of your sandboxes. A paused sandbox asks once
  something wakes it, such as a command or a request to its preview.
- Microsoft Entra ID's federated credentials match an exact subject, and every
  sandbox's subject is different, so Azure is not supported yet. Tell us with
  `npx withruntime feedback "identity tokens: Azure"` if you need it.


---

<!-- https://withruntime.com/docs/images -->

# Custom images

Build an image once, with your code and dependencies. Then start every sandbox from it. You can build an image from any Dockerfile. You can also build one from any public or private container image, or from a short recipe of packages. Each build of a name becomes its next version. Tags such as `latest` and `prod` point at versions. An image can also say what a sandbox from it runs, and when that sandbox is ready.

## Build from a Dockerfile

Point the SDK or the CLI at a folder with a Dockerfile. The folder is the build context, as with `docker build`. Every file that its `.dockerignore` leaves in is packed. Only the parts that changed since your last build are uploaded.

```bash no-run
runtime images build . -t web:v1
runtime sandboxes create --image web:v1
```

For a Dockerfile somewhere else, use `-f`. The path is read from where you run the command, as with `docker build`. A path inside the folder works too. In a monorepo, the repository is the context. The command passes the app's Dockerfile with `-f`:

```bash no-run
runtime images build . -f apps/web/Dockerfile -t web:v1
```

```ts check
import { readFile } from "node:fs/promises";
import { Runtime } from "withruntime";

const runtime = new Runtime();
const image = await runtime.images.build(
  { name: "web", dockerfile: await readFile("Dockerfile", "utf8"), contextDir: "." },
  { onLog: (line) => console.log(line.text) },
);
await using sbx = await runtime.sandboxes.create({ image: "web" });
console.log(image.version, sbx.id);
```

```python check
from withruntime import Runtime

runtime = Runtime()
with open("Dockerfile") as handle:
    image = runtime.images.build(name="web", dockerfile=handle.read(), context_dir=".",
                                 on_log=lambda line: print(line["text"]))
sandbox = runtime.sandboxes.create(image="web")
```

A Dockerfile can use:

- Multi-stage builds. `FROM <stage>`, `COPY --from=<stage>` and `COPY --from=<image>` all work. Only the stages that the image needs are built. `--target` (the SDKs' `target`) builds a named stage instead of the last one.
- `ARG` before and after `FROM`, build arguments, and the platform arguments (`TARGETARCH` is `amd64`).
- Heredocs: `RUN <<EOF`, `RUN python3 <<EOF`, a script with its own `#!`, and `COPY <<EOF /path`.
- `ADD` from an `http` or `https` URL. It is checked when you give `--checksum=sha256:...`. `ADD` also takes a local `.tar`, `.tar.gz`, `.tgz`, `.tar.bz2` or `.tar.xz` archive, and unpacks it.
- `FROM scratch`, any public image, a private image (see below), or `FROM runtime` for Runtime's own base image with Python, Node, Bun and the usual tools.
- `COPY --chown`, and `COPY --chmod`. `--chmod` takes octal, such as `755`, or symbolic, such as `a+x` or `u+x,go-w`, for files from the build context. Also `WORKDIR`, `ENV`, `USER`, `SHELL`, and `RUN --mount=type=cache`. The cache mount is not used. The step runs without the cache mount. As on Docker, an `ENV` beats an `ARG` of the same name. An `ARG` with no value and no build argument stays unset. As in Docker, root owns what `COPY` and `ADD` write, unless `--chown` names an owner. The directories a `WORKDIR` creates belong to the `USER` in effect at that time. So `USER node`, `WORKDIR /app`, `COPY . .` and `RUN npm ci` build.
- `CMD`, `ENTRYPOINT` and `HEALTHCHECK` become the image's start and ready commands (see below).
- A stage that starts `FROM` an image starts where that image says, as on Docker. It starts in the image's `WORKDIR`, as its `USER`, with its `CMD` and `ENTRYPOINT`. For example, `FROM golang` and then `COPY main.go .` puts the file in `/go`. A base the API cannot read starts at `/`, as root, with no start command. The build's notes say so. A base the API cannot read is one on a private registry, or one that does not respond within 5 seconds.

A few forms are refused. The refusal message says what to do instead. These are `RUN --mount=type=secret`, `type=ssh` and `type=bind`, `ONBUILD`, `ADD` from a git repository, and `COPY --exclude`. Only the last stage can start `FROM runtime`. Start earlier stages from a public image, such as `ubuntu:24.04`.

The build runs in its own Firecracker virtual machine. It has the same web access as a sandbox. `USER` applies to the build's `RUN` steps. Commands in a sandbox run as the sandbox user, uid 1000, with passwordless `sudo`, as in the base image. An image with its own `sudo` keeps it. An image without one gets Runtime's. A command that names no directory starts in the last `WORKDIR`, as on Docker and E2B. If there is no `WORKDIR`, it starts in `/workspace`. The image's start and ready commands (`CMD`, `ENTRYPOINT`, `HEALTHCHECK`) start the same way. The build gives that directory, and everything in it, to the sandbox user. So commands can write where they start. A system directory such as `/usr` or `/tmp` stays root's. The build log says so. A file the image
puts in `/tmp` is there when a sandbox starts, as on Docker. Until 9 October 2026, a sandbox from an image on Runtime's base started with `/tmp` empty. An image built earlier with a `WORKDIR` outside `/workspace` starts commands in `/workspace`. It does so until it is built again.

Names resolve through Runtime's resolver in every image. The image's own `/etc/resolv.conf` is replaced. This happens in each `RUN` step and in the sandbox, as Docker replaces it when a container runs. An image built before 30 September 2026 from a Debian or Ubuntu base, such as `python:3.12-slim`, may fail to look up names. Build it again.

## Build from an image or a recipe

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

const runtime = new Runtime();
await runtime.images.build({ name: "py", image: "python:3.12-slim" });
await runtime.images.build({ name: "data", recipe: { pip: ["pandas"], apt: ["jq"] } });
```

A recipe takes `base` (`runtime` by default, or any image), `apt`, `pip`, `npm`, `commands`, `files`, `env` and `workdir`. The CLI builds one with `--pip`, `--apt` and `--npm`, and uses an image as it is with `--from`.

## Private registries

Store a credential for a registry once. Every build of your account then pulls from that registry with it. The secret is sealed to Runtime's servers as soon as it arrives. No call returns it. The API that stored it cannot read it back. A build opens it only to pull, inside its own build machine.

```bash no-run
echo "$GHCR_TOKEN" | runtime images registry set ghcr.io --username my-user
echo "$AWS_SECRET_ACCESS_KEY" | runtime images registry set 123456789012.dkr.ecr.us-east-1.amazonaws.com --access-key-id AKIA...
runtime images registry ls
```

| Registry                                                | Give                                                                                                                  |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Docker Hub (`docker.io`)                                | your user name and an access token                                                                                    |
| GitHub (`ghcr.io`)                                      | your user name and a token that can read packages                                                                     |
| Google (`gcr.io`, `*-docker.pkg.dev`)                   | `_json_key` and the service account key's JSON, or `oauth2accesstoken` and an access token                            |
| Amazon ECR (`<account>.dkr.ecr.<region>.amazonaws.com`) | an access key id and secret that may call `ecr:GetAuthorizationToken` and pull; each build asks ECR for a fresh token |
| Any other                                               | a user name and a token or password                                                                                   |

The same credentials cover `FROM`, `COPY --from=<image>` and a recipe's `base`.

A pull refused without credentials may mean the image does not exist. Docker Hub returns the same answer for a missing name as for a private one. So check the spelling before you store a credential. A tag the registry lacks fails the build, with the tag named. In the SDKs, use `runtime.images.registries.set(...)`, `.list()` and `.delete(...)`.

## Names, versions and tags

Every build of a name gets the next version number. When a build is ready, it takes the tags you gave it. If you gave none, it takes `latest`. A tag points at one version. It moves when another version takes it. A later version keeps a tag, even if an earlier build finishes after it.

Wherever an image is named, including `image` when you create a sandbox, you can use its id. You can also use `name` (its `latest` tag), `name:tag` or `name@version`.

A sandbox starts only from an image of your account. So build a public image first. Build it under its own name and tag. Then the same words name it:

```bash no-run
runtime images build --from python:3.12-slim -t python:3.12-slim
runtime sandboxes create --image python:3.12-slim
```

A reference that names nothing returns `image_not_found`. For a name you have built, the error lists the name's tags and versions in `details`. For a name you never built, it gives the build command above.

```bash no-run
runtime images build . -t web:v2 -t web:latest
runtime images versions web
runtime images tag web@2 prod
runtime images untag web@1 prod
runtime images rm web@1
```

Deleting a version also removes its tags. Sandboxes already started from it keep running. A version that an App still needs is not deleted. That includes the version it runs, the version it would roll back to, and a version it is deploying. Deleting it returns `image_in_use` (409), and the error names the App.

A name rebuilt on every change, such as a site deployed on each merge, keeps every version until you delete it. Each version counts toward your image disk. `--keep` deletes the older versions once the new build is ready. It keeps the newest that many, and any version an App still needs:

```bash no-run
runtime images build . -t web:"$(git rev-parse --short HEAD)" --keep 3
```

## Move a sandbox to a new version

A new build does not change sandboxes that already run an image. To move one to the new version and keep its files, switch its image:

```bash no-run
runtime sandboxes switch-image "${id}" web:v2 --keep-workspace
```

`sbx.switchImage("web:v2")` in JavaScript, `sbx.switch_image("web:v2")` in Python, and `POST /v1/sandboxes/{id}:switch-image` with `{"image": "web:v2"}` do the same ([API](./api#sandboxes)).

- **What it keeps:** its id and name, `/workspace` (your home, with its dotfiles and what `pip install` and `npm install -g` put there), its volumes, environment, labels, previews and ports.
- **What it loses:** its running processes, which start again with the new image's start command. It also loses everything else on its old disk: packages installed with `sudo` or apt, and changes to `/etc`. To keep everything, take a snapshot of the sandbox first.
- A running sandbox is paused for the switch. A paused one, or a stopped persistent one, is switched as it is. It is charged as a wake.
- If anything goes wrong, the switch is undone. The result is `switch_undone`. The sandbox is on its old image, with its files and memory as they were.
- A switch of a 512 MiB `/workspace` with 5,000 files takes about 9 seconds on its server. This is measured until the sandbox runs the new image. The sandbox boots twice, and the copy runs between the boots.
- The new image must be ready. It must be stored on the sandbox's server, or the switch fails with `image_on_another_host`. It must also fit the sandbox's disk. Copying `/workspace` may take up to 60 seconds. A larger `/workspace` is refused, and the switch is undone.

## Start and ready commands

An image can say what runs when a sandbox starts from it. It can also say when that sandbox counts as ready. A Dockerfile's `CMD` and `ENTRYPOINT` become the start command. Its `HEALTHCHECK` becomes the ready check. An image built from `image` alone starts what Docker runs. For example, `{image: "redis:7"}` starts `docker-entrypoint.sh redis-server` in `/data`. A shell or a language's prompt as `CMD` (`bash`, `python3`) starts nothing, because it would exit immediately. You can set or change both with `start`:

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

const runtime = new Runtime();
await runtime.images.build({
  name: "api",
  recipe: {
    pip: ["fastapi", "uvicorn"],
    files: [
      {
        path: "/workspace/main.py",
        content:
          'from fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/")\ndef home():\n    return {"ok": True}\n',
      },
    ],
  },
  start: {
    command: "uvicorn main:app --host 0.0.0.0 --port 8000",
    readyPort: 8000,
    readyTimeoutSeconds: 60,
  },
});
const sbx = await runtime.sandboxes.create({ image: "api" });
console.log(sbx.info.start); // { state: "ready", readyMs: ... }
```

The start command runs once per boot. It runs in the background, as the sandbox user, in the image's `WORKDIR` (or `start.cwd`). It runs at create. It runs again at each `:restart` and `:resize`. Those boot from the disk with no process left running. A wake from a pause keeps memory, so its process runs on. The create call returns when the ready check passes. The ready check passes when `readyPort` is being listened on, or when `readyCommand` exits 0. The response sets `start.state` to one of these values:

- `ready`: the ready check passed.
- `started`: there is no ready check, and the command is still running 150 ms after it began.
- `timeout`: the check did not pass within `readyTimeoutSeconds`. The default is 60, and the maximum is 300. The wait must fit within the SDKs' own five-minute call deadline.
- `exited`: the start command ended first. `start.exitCode` and `start.stderr` say why. `start.stderr` holds the last lines of error output.

`start: null` drops what the Dockerfile said.

Only the create response carries `start`. The sandbox object it returned keeps it through later reads. The API keeps no record of it, so a sandbox read with `sandboxes.get` or `list` has none.

## Fast starts

A few seconds after an image is ready, Runtime keeps a started copy of it at the default size. The default is 2 vCPU, 4 GiB of memory and a 4 GiB disk. A sandbox of that size created from the image starts from the copy instead of booting the image. A copy serves only its own size. So the first sandbox of another size boots the image. Runtime then keeps a started copy of that size too. That is up to two more sizes per image, each with up to 8 GiB of memory. A new build of an image starts with copies at those sizes already. Before its first sandbox, it gets a started copy of each size that your account's other images have on that server. Those copies count among its two. So a rebuilt image created at 1 vCPU and 512 MiB starts from a copy from its first create there. An image larger than the default 4 GiB disk gets its started copy at the default vCPU and memory. That copy uses the smallest of 8, 16, 32 or 64 GiB of disk that holds the image. A create from an image of up to 8 GiB that names no `diskMiB` gets the 8 GiB disk. That is within the 10 GiB a running sandbox's disk includes. It starts from that copy. From a larger image, the create is refused with `disk_too_small`. The error names the `diskMiB` to ask for. A `diskMiB` you name is kept.

A start that finds no copy boots the image. Measured on 8 October 2026, that took about 2 s from create to running for a 4.4 GiB image. A copy took 0.3 s. Each server keeps its own copies. So the first create of a size on a server that has none boots. A pilot's servers keep one at the pilot's size from the start. Each copy belongs to your account alone. It goes when the image is deleted. It is neither charged nor counted toward your image disk quota. A server keeps an image's started copies while sandboxes are created from it there. Once none has been used for 2 days, and the image has been on that server at least as long, the copies go. The next sandbox of it on that server boots the image. The copies are kept again from then on.

## Faster rebuilds

A build keeps up to three checkpoints of its filesystem. The first is where its image stage starts. That is after the base image is pulled, or after the earlier stage it is built `FROM`. The other two are the latest points after a command that more steps follow. A later build of your account that starts the same way begins at the latest matching checkpoint. It does not start from the beginning:

- Every Dockerfile, recipe or image on the same base, such as `python:3.12-slim`, skips the pull once one build on it has run.
- Changing your code reruns only the steps after the `COPY` that brings it in.
- Builds of different `--target` stages that are built `FROM` the same stage share the checkpoint after that stage, so it is not built again.
- An earlier stage that the image only reads with `COPY --from` is built again whenever a step that reads it runs. Its result is not kept.

A build that fails keeps its checkpoints too. That makes the fix quick. Change the failing step and build again. The build starts after the last command that ran before the failure. If nothing had run, it starts after the pull. It does not start from the beginning. Only the steps from there on run again. A failed build's checkpoints go when a build of your account that started after the failure finishes. This applies whether that build succeeds or fails. A build that fails keeps its own checkpoints in their place. The build log says what a failed build kept. It says where the next build will start, and which image's checkpoint a build started from. The `cache` field on the image says what it keeps.

Checkpoints stay on the server with the image that made them. They go when that image is deleted. They count toward your image disk quota, but they are not charged. When a new build would go over that quota, the oldest checkpoints from failed builds are released first. So they never stop a build.

A base named by its tag, such as `FROM python:3.12-slim` or `:latest`, is looked up when the build is created. It is pinned to the digest that the tag names at that time, as `docker buildx build` does. A tag that has moved since an earlier build is a different base. So the build pulls it again, and reuses no step built on the old base. A base on a private registry cannot be looked up this way. Neither can a base that does not respond within 5 seconds. Such a base keeps its tag. The build's notes say so. A checkpoint after its pull holds it as it was then. To pin such a base, use `@sha256:<digest>`. Or pass `cache: false` (`--no-cache`). That pulls the base again, builds every step from scratch, and keeps no checkpoints.

An identical build of your account is copied immediately instead of built. It must have the same plan, the same files, and the same builder version. This does not apply if the build passes `cache: false`. If the identical image is larger than the new build's `maxImageMiB`, the build fails immediately with a message that names the size to set; nothing is copied.

## Build machine

Each build runs in its own virtual machine. Its size is set apart from the sandboxes that will use the image. Its scratch disk holds the build context and every earlier stage. So a large multi-stage build can need more than the default 4 GiB. To set the scratch disk and the rest of the build machine, use `build`:

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

const runtime = new Runtime();
await runtime.images.build({
  name: "ml",
  recipe: { pip: ["torch"] },
  build: { vcpu: 4, memoryMiB: 8192, diskMiB: 16_384, maxImageMiB: 12_288 },
});
```

In Python, it is `build={"vcpu": 4, "memory_mib": 8192, "disk_mib": 16384}`. Over HTTP, use `build.diskMiB` in the body of `POST /v1/images`. The ranges are under [Limits](#limits). An odd `memoryMiB` is rounded up to the next even number, as a sandbox's is. The scratch disk must fit the builder image. Requests smaller than the builder image are refused before a build is queued. In the CLI, `--disk-mib`, `--max-image-mib` and `--timeout` set the scratch disk, the image size and the build time.

## Build logs

`images.build` streams the log to `onLog` (`on_log`) as it is written. The CLI prints it while it builds. `runtime images logs <image> --follow` streams it again. Over HTTP, `GET /v1/images/{id}/logs?follow=true` returns one JSON event per line. It returns each `line`, then `done` with the image.

In your account, [Images](https://withruntime.com/account/images) lists each image. Its page shows every version with its tags, and the build log. The log follows a build while it runs. **Build image** accepts a Dockerfile with a small inline context, a registry image, or a package recipe. From an image's detail page, you can start a sandbox, add or remove tags, or delete the selected version. Spending and deletion ask for confirmation. They use the permissions already granted to the console's agent.

A build that fails in one of your steps ends with that step's output in the log. When the server that builds the image is busy, the build waits up to five minutes for room to start its build machine. The log says it is waiting. That wait counts toward the build time. A build can also fail on our side. This happens when its build machine did not start, or the server failed. Its error says so, and does not blame your Dockerfile. We are alerted. Build again in a few minutes.

## Limits

| Limit                | Value                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Concurrent builds    | 1 until your account holds credit, then 4                                                                                                         |
| Build machine        | 1 to 8 vCPUs (2 by default), 1 to 16 GiB of memory (4 GiB), 4 GiB to 32 GiB of scratch disk (4 GiB) |
| Build time           | 60 seconds to 1 hour (30 minutes by default), counting starting the build machine and saving the image                                            |
| Image size           | 512 MiB to 20 GiB (8 GiB by default); at least 3,072 MiB from Runtime's base, which is that size before any step                 |
| Build context        | 100 MiB compressed, 20,000 files, 2 GiB unpacked                                                                                                  |
| Context upload       | 1 MiB chunks, kept 24 hours after last use; 200 MiB held and 1 GiB uploaded a day per account                                                     |
| Inline `files`       | 256 files and 1 MiB in all                                                                                                                        |
| Dockerfile           | 256 KiB, 200 steps across all stages, 16 earlier stages                                                                                           |
| Registry credentials | 20 per account                                                                                                                                    |

## Pricing

A stored image is charged on its whole file. Storage quotas follow the same allocation ([pricing](./pricing#snapshots-images-and-volumes)). Building an image is free with credit. Without credit, a build counts toward the free usage, only for the time it builds. It is at most 2 vCPU and 4 GiB, 20 minutes and 10 builds a day. A build that fails through a fault of ours, such as a build machine that does not start, uses none of the free usage. The [free usage](./included-usage) stores your first three images free for as long as you keep them, even after you add credit, outside the monthly allowance for saved copies. This applies even after you add credit. It sits outside the monthly allowance for saved copies. `storedBytes` on an image is not what it is charged on: `sizeBytes` is.


---

<!-- https://withruntime.com/docs/included-usage -->

# Free usage

Every account gets free usage, with no card, after a verified sign-in. It is
100 free hours of a 1 GB machine ([by region](#free-usage-by-region)). An account that has never paid gets the machine time
**once, across its first 30 days**. After that it gets none until it adds credit. An
account that has paid (bought credit) gets it **every calendar month**. Saved
copies and disks are monthly for every account:

| Product                                   | Free usage            |
| ----------------------------------------- | --------------------- |
| Machine memory                            | 100 GiB-hours       |
| Machine active CPU                        | 25 vCPU-hours          |
| Saved copies (snapshots, images, backups) | 10 GB |
| Disks (volumes)                           | 5 GB        |

- For an account that has paid, it renews on the 1st of each month, 00:00 UTC.
  What is left at the end of a month does not carry over. For an account that
  has never paid, the machine time ends 30 days after the account was opened
  (`freeUntil` in `GET /v1/usage`), whatever is left. It comes back every
  month once the account has paid. Credit Runtime gave, such as the welcome
  match, does not count as paying.
- It is used first, before any credit, on every account, with credit or
  without. It is never charged. There is nothing to choose. A request's
  `funding` is accepted and ignored.
- An account given free hours before 5 October 2026 keeps what is left of
  them. It has the free usage as well.
- Model calls are not included.
- An account opened from a data-centre or VPN network (a cloud provider's
  address, or a VPN company's) gets its free usage once it adds credit,
  not before. Accounts are made in bulk from those networks. An account opened
  from a home, office or mobile network gets it at sign-in, as above.

## Free usage by region

In the countries below, free usage is 100 free hours of a 1 GB machine, as above. An
account opened with Google starts it with no card. An account opened by
email starts it once its owner adds a card under **Auto top-up** on
**Usage & billing**: your bank checks the card, and Runtime does not charge
it unless you turn auto top-up on. Each card starts free usage for one
account. In other regions, machine time starts when the account buys credit,
and buying credit unlocks the full free usage every month, in every region.
Saved copies and disks are the same everywhere.

Andorra, Australia, Austria, Belgium, Canada, Croatia, Cyprus, the Czech
Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong,
Iceland, Ireland, Israel, Italy, Japan, Korea, Latvia, Lithuania, Luxembourg,
Macao, Malta, the Netherlands, New Zealand, Norway, Portugal, Puerto Rico, San
Marino, Singapore, Slovakia, Slovenia, Spain, Sweden, Switzerland, Taiwan, the
United Kingdom and the United States.

The region is where the account was opened from; for an account opened before
29 October 2026, where its first visit to withruntime.com came from.

## Without credit

The limits below hold while the account holds no credit. Once it does, its
sandboxes have paid limits. They still use the free usage first
([after you add credit](#after-you-add-credit)).

- Up to **four sandboxes running at the same time**, each up to **2 vCPU
  and 4 GiB of memory**, with up to 10 GiB of disk (4 GiB by default). Paused
  sandboxes do not count toward the four.
- At most **8 vCPU and 16 GiB at the same time** across every sandbox and image build
  that is running.
- At most **5 sandboxes kept**, running, paused or stopped. A
  create past that is refused with `no_credit_kept_limit`. Delete one to make
  room. Waking, resuming or deleting a sandbox you already keep is never
  refused.
- At most **50 sandboxes made a day** (any 24 hours). Copies
  made by a fork count too. Past that limit, a create is refused with `no_credit_daily_limit`.
- At most **10 live API keys** in the account, whoever made
  them. A new key past that is refused with `no_credit_key_limit`. Revoke one
  to make room. A revoked or expired key frees its place. Every key you
  already hold keeps working. The short-lived keys Runtime makes by
  itself, for the console, its terminals, image builds and the other work it
  runs for you, are not counted. Once the account adds credit,
  there is no limit.
- No [scheduled job](./jobs) runs. It waits until the account holds credit.
- CPU is shared, never reserved. Its guaranteed floor (`cpuFloorMillis`)
  is at most 250 thousandths of a vCPU; the default is 50. A create that asks
  for more is refused with `no_credit_size_limit`, naming each field. So is
  a fork of such a sandbox.
- Sandboxes without credit download with no speed limit and upload at up to
  10 Mbit/s each. They move 1 GiB a day in all, in and
  out together. While a server's link is full, a paid sandbox gets
  four times a sandbox without credit's share of it.
- A sandbox without credit that keeps trying to reach internal or cloud
  metadata addresses has its network cut, and the account is suspended. So does
  a sandbox of an account that has never paid that connects to a mining pool,
  scans ports, or reaches very many different destinations in a few minutes, as
  a scan or a sweep does. One that
  holds its CPUs flat out for 30 minutes is slowed to half a core for the rest
  of its run.
- Previews of a sandbox without credit are private. A link carries its token.
  Public previews need a kept top-up: one paid and not refunded. Credit given
  alone does not open them ([pricing](./pricing#how-many-at-once)).
- A sandbox runs while it works. It pauses itself when idle, until the
  free usage runs out. Then it pauses, unless the account holds credit. In
  that case it carries on on credit. There is no time limit unless you set
  one with `timeoutSeconds` (60 to 86,400). One longer than the usage left is
  cut to it. Idle means nothing happening in it for `idlePauseSeconds`
  (300 seconds by default): no request, no command, terminal, SSH session or
  port forward open, no CPU use and no traffic. A browser tab left open on a
  preview does not count. Wake it to keep going.
- Your first three images and first 10 GiB of volumes are stored free, for as
  long as you keep them ([pricing](./pricing#snapshots-images-and-volumes)).
  That is apart from the table. The 5 GB of disks a month in the table
  pays for volumes past your first 10 GiB. A
  build uses the free usage: at most 2 vCPU and 4 GiB,
  20 minutes and 10 builds a day. Only the
  time it builds is used. A build that fails through a fault of ours uses none.
- A [scheduled job](./jobs) does not run without credit. It waits with
  `blockedReason` `credits` until the account holds credit. Once it does,
  each run is a sandbox like any other, and uses the free usage first.
- A sandbox without credit cannot reach cryptocurrency mining pools, on any
  port.
- A sandbox without credit reaches the internet on ports 80 and 443 only.
  Other ports, such as a database's or git over SSH, need a paid sandbox of an
  account with a kept top-up.

Over HTTP, a create is `POST /v1/sandboxes`. This body names the defaults. An
empty body is the same:

```json
{
  "vcpu": 2,
  "memoryMiB": 4096,
  "diskMiB": 4096,
  "cpu": "shared",
  "cpuFloorMillis": 50
}
```

## Tell your agent

Paste the setup prompt from [Get started](./start#give-your-agent-one-instruction).
The agent runs everything on the free usage. It switches any sandbox code the
project has on another provider, and tells you what you would save each month.

## Use it from code

**You do not have to ask for it.** `create()` uses the free usage while the
month has some left, sized to fit.

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

const runtime = new Runtime();
const sbx = await runtime.sandboxes.create({ vcpu: 1, memoryMiB: 2048 });
try {
  console.log(sbx.info.funding, sbx.info.endsAt);
} finally {
  await sbx.stop();
}
```

Use a region listed for your account. Leave `region` out for the default.

## See what is left

Read it with `npx withruntime usage`, or `GET /v1/usage`:

- `allowances` has one row per product: `pool`, `unit`, `quantity`, `used`,
  `reserved` (held for what runs now, given back unless used), `left` (the
  quantity less what is used; what is held is not taken off), `month`,
  `renewsAt` and `freeUntil` (when the free usage ends for an account that has
  never paid; null once it has paid).
- `trial` is the machine time a new sandbox without credit can still run, in
  milliseconds: `availableMs`, with `offer` (`monthly`, or `hours` for an
  account given free hours before 5 October 2026) and `renewsAt`. It counts
  what running sandboxes hold until they end. A create without credit is
  refused with `included_usage_used_up` exactly when `availableMs` is 0. The
  field keeps its older name, so code that reads it goes on working.
- `freeUsageHold` says why the account has no free machine time, or is null.
  `reason` is `hosting` (opened from a data-center or VPN network), `region`
  (opened outside the countries listed [above](#free-usage-by-region)),
  `card` (opened by email, with no card saved yet), `withheld` (under
  review), `no-source` or `unknown`. `message` says the same in a sentence,
  with what starts the free usage. While it is set, the account has no free
  machine time (`trial` is null or its `availableMs` is 0), and a refused
  create's `details.reason` is the same `reason`.
- `startupIncluded` lists what Runtime for Startups
  includes for an accepted startup, one row per product.
  `machine-cpu` and `machine-memory` have `period` `once`: `quantity`,
  `used`, `reserved` and `left`. They are used after the month's free usage and
  before credit, and never renewed. What is left ends at `expiresAt`, 12
  months after it was given. `saved-copies` and `disks` have `period`
  `month`: `quantity` GB added to each month's included storage until
  `expiresAt`, never used up, with `keptGB`, the GB kept now. Storage past it
  is charged at the published rates. `startupLimits` lists the concurrency limits
  that Runtime for Startups includes, `buildsAtOnce` and `sandboxesAtOnce`, until the same `expiresAt`.
  After it, null. The account is paid with no top-up until then. After that, it is paid once it holds credit it bought.

The old fields `pot` and `potLimits` still work for 30 days after this change ships, with a warning.

In the browser, [Usage & billing](https://withruntime.com/account/billing)
shows what each product used this month and what is left.

## When you reach a limit

| Code                         | What it means                                                                                                                                                                                                                           | What to do                                           |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `no_credit_running_limit`    | Four sandboxes without credit are running; `details.running` names them                                                                                                                                                                 | Stop or pause one; an SDK create waits for a slot    |
| `no_credit_total_limit`      | Running sandboxes and builds would pass 8 vCPU and 16 GiB; the message says what runs now                                                                                                                                             | Stop or pause one, or wait for a build to end        |
| `no_credit_kept_limit`       | The account keeps 5 sandboxes, running, paused or stopped, and a create would make another                                                                                                                             | Delete one, or add credit                            |
| `no_credit_daily_limit`      | 50 sandboxes made in the last 24 hours                                                                                                                                                                                 | Reuse a sandbox, retry later, or add credit          |
| `no_credit_key_limit`        | The account holds 10 live API keys, and a new key would make another                                                                                                                                                    | Revoke one, or add credit                            |
| `no_credit_domain_limit`     | Accounts on your company's email domain share eight running sandboxes without credit, all running                                                                                                                                       | Stop or pause one, or add credit                     |
| `no_credit_size_limit`       | The size asked for is larger than 2 vCPU, 4 GiB and 10 GiB of disk                                                                                                                                                                      | Omit the size fields for the default                 |
| `no_credit_build_limit`      | 10 builds started in the last 24 hours                                                                                                                                                                              | Reuse an image, or retry later                       |
| `no_credit_capacity_full`    | The room servers keep for accounts without credit is full right now                                                                                                                                                                     | Retry shortly; an SDK create waits                   |
| `included_usage_used_up`     | The free usage is used and the account holds no credit                                                                                                                                                                                  | Add credit, or wait for the 1st (UTC) if it has paid |
| `included_usage_unavailable` | The account has no free usage: it goes once to each verified email address, and the owner's is unverified or already has it on another account; or the account was opened from a data-centre or VPN network, where it comes with credit | Verify your email, or add credit                     |

Each of these responses says what was refused and the limit. Then, in its
`hint` and in `details.addCredit`, it gives the one way past it: the account's owner
adds credit. Credit added within 30 days of signing up is matched, up to $1,000 in total
([how refusals look](./api#responses-and-errors)). An agent tells its person
which limit it met. It never adds credit on its own. The exception is an account it
opened with a wallet and no person pays for. There, the hint tells it to add
credit itself ([pay with stablecoins](./pricing)).

These codes were named `trial_busy`, `trial_capacity`, `invalid_trial`,
`trial_domain_limit`, `trial_build_limit`, `trial_exhausted` and
`trial_unavailable` before 5 October 2026 ([changelog](./changelog)).

Requests sent at the same moment are admitted in no set order, so any one of
them may be the one refused. Shared mail providers such as gmail.com,
outlook.com and icloud.com have no domain limit. Temporary inbox services such
as Guerrilla Mail and Mailinator cannot open an account.

Free usage cannot be cashed out, refunded, carried over or gained by
signing in again.

## After you add credit

**Add credit and keep going.** An owner, admin or billing member adds prepaid
credit at [Usage & billing](https://withruntime.com/account/billing). The amount can be any amount from $10, with no subscription. Credit you add within 30 days of signing up is matched, up to $1,000 in total
([welcome match](./pricing#welcome-match)). There is nothing to switch. From
then on:

- new sandboxes are paid, with paid limits (larger sizes, any port, public
  previews, persistence, more at the same time). They still use the free usage
  first, then credit;
- a paused sandbox without credit wakes on credit;
- a running sandbox without credit carries on on credit when the free
  usage ends, without pausing.

- A paid sandbox runs the same way. While it works, until you stop it, it idles
  into a pause, or credit or a spending limit runs out. `persistent` keeps one
  running with no idle pause. A stop keeps a sandbox's disk until you delete
  it.
- A paid account runs 100 sandboxes at the same time from its first
  top-up. Paused ones are not counted. More are available on request
  ([pricing](./pricing#how-many-at-once)).
- Refer a company and you both get up to $1,000, then 10% of what it
  spends for 12 months ([referrals](./referrals)).

For what a sandbox may reach, see [security](./security).


---

<!-- https://withruntime.com/docs/inspect -->

# Runtime for Inspect AI

Run each Inspect sample's tools in its own Runtime microVM, from the Dockerfile or compose file your eval already has.

Installing the package registers a sandbox named `runtime` with Inspect, next to
its `docker` and `local` sandboxes. Every sample gets a Firecracker microVM with
its own kernel, built from the same Dockerfile or single-service
`compose.yaml` the Docker sandbox takes, and you pay for the CPU it uses rather
than the CPUs it holds.

## Install

```bash no-run
pip install "withruntime[inspect-ai]"
```

The key comes from `RUNTIME_API_KEY`, or from `npx withruntime login` on this
machine, as in the rest of the SDK. Nothing needs importing: the package's entry point
tells Inspect about `runtime`.

## Use it

```python check
from inspect_ai import Task, task
from inspect_ai.dataset import Sample
from inspect_ai.scorer import includes
from inspect_ai.solver import generate, use_tools
from inspect_ai.tool import bash


@task
def kernel():
    return Task(
        dataset=[Sample(input="Which Linux kernel version is running? Answer with the version.", target="6.")],
        solver=[use_tools(bash()), generate()],
        scorer=includes(),
        sandbox="runtime",
    )
```

`sandbox="runtime"` runs Runtime's base image: Ubuntu with Python, Node.js, git
and the usual tools ([what is installed](./sandbox-environment)). To use your
own image, name the file as you would for Docker, or switch an existing eval
from the command line:

```bash no-run
inspect eval task.py --sandbox runtime
inspect eval task.py --sandbox runtime:compose.yaml
```

```python check
from inspect_ai import Task
from withruntime.inspect_ai import RuntimeSandboxEnvironmentConfig

from_dockerfile = Task(sandbox=("runtime", "Dockerfile"))
from_compose = Task(sandbox=("runtime", "compose.yaml"))
configured = Task(
    sandbox=("runtime", RuntimeSandboxEnvironmentConfig(image="python:3.12-slim", memory_mib=2048))
)
```

A Dockerfile or a compose service's `build` or `image` is built once as a
[custom image](./images), named `inspect-<name>` with a tag from a hash of the
Dockerfile and its build context, and every sample starts from it. It is built
again only when those files change.

## Options

`RuntimeSandboxEnvironmentConfig` takes these, all optional. A compose file can
set them under `x-runtime` on the service.

| Field                            | What it does                                                                                                                     |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `image`                          | A container image such as `python:3.12-slim`, built once as a Runtime image                                                      |
| `dockerfile`                     | A Dockerfile's path; its folder is the build context                                                                             |
| `runtime_images`                 | A Runtime image (id, name or `name:tag`), used as it is                                                                          |
| `funding`                        | Accepted and ignored: the free usage is spent first, then prepaid credit                                                         |
| `vcpu`, `memory_mib`, `disk_mib` | The sandbox's size. Without credit, at most 2 vCPU, 4 GiB and 10 GiB of disk; a larger request runs at that size, with a warning |
| `user`                           | Who commands and file operations run as when Inspect names no user: `root` by default                                            |
| `workdir`                        | Where relative paths and commands start: `/workspace` by default, or the Dockerfile's `WORKDIR`                                  |
| `env`                            | Variables for every command                                                                                                      |
| `network`                        | Network rules from the start, such as `{"internet": False}`                                                                      |
| `region`, `labels`, `build`      | The region, your own labels, and build limits such as `{"disk_mib": 16384}`                                                      |

From a compose service, `cpus` and `mem_limit` (or `deploy.resources.limits`)
set the size, `working_dir`, `environment` and `user` carry over, and
`network_mode: none` turns the network off.

## What runs in the sandbox

- **Commands** run as root unless Inspect names a user, as in the Docker
  sandbox. Commands in a Runtime sandbox run as the sandbox user, uid 1000,
  so root and named users go through its passwordless `sudo`, which Runtime's
  base image has. An image built from a public image needs it too. The sandbox
  checks when a sample starts. If it is missing, the sandbox stops and shows
  this line to add to the Dockerfile:

```dockerfile
RUN apt-get update && apt-get install -y sudo && echo '#1000 ALL=(ALL:ALL) NOPASSWD: ALL' > /etc/sudoers.d/runtime
```

- **Output** streams, so Inspect's own 10 MiB limit applies, and input of any
  size reaches the command.
- **Files** of any size, anywhere in the machine; Inspect's 100 MiB read limit
  applies.
- **Timeouts** raise `TimeoutError` and are retried as Inspect asks.
- **Long samples** keep their sandbox: it runs while the sample works, however
  long it takes.
- `inspect sandbox cleanup runtime` stops sandboxes an interrupted eval left,
  and `connection()` gives `runtime sandboxes ssh <id>` to open a shell in one.

**Not supported:** a compose file with more than one service, and the trio
async backend.

## Limits to plan for

- An account without credit runs four sandboxes at the same time, so the sandbox asks Inspect for
  4 at a time. On a paid account raise it with `--max-sandboxes`; see
  [pricing](./pricing#how-many-at-once).
- Builds run one at a time until your account holds credit, then four. An account without credit keeps its first three images free; after that they are billed as
  stored images ([pricing](./pricing#snapshots-images-and-volumes)).

## What was verified

On 25 September 2026 Inspect AI 0.3.268's own portable sandbox checks
(`inspect_ai.util._sandbox.self_check`) ran against this sandbox over a fake
Runtime API whose sandbox is a folder on the test machine, with commands run
through a real `sudo`. Every check passed except three that expect the default
user to be refused a file, which root is not, and one that adds a user account,
which was left out because it would have changed the test machine. The same
run covered building a Dockerfile once, a compose service's settings, the
refusal of several services, the output limit, a missing `sudo`, and cleanup,
and an `eval()` of a task with `sandbox="runtime"` on the same fake. In a fresh
install of the package, Inspect found `runtime` through its entry point.


---

<!-- https://withruntime.com/docs/java -->

# Java SDK

One Java client for every Runtime Cloud product.

`com.withruntime:withruntime` needs Java 17 or later and nothing beyond the
JDK: no HTTP library, no JSON library. It is a named module,
`com.withruntime`.

```xml
<dependency>
  <groupId>com.withruntime</groupId>
  <artifactId>withruntime</artifactId>
  <version>0.31.1</version>
</dependency>
```

With Gradle: `implementation("com.withruntime:withruntime:0.31.1")`.

**The client finds its key by itself.** It uses `RUNTIME_API_KEY` when that is
set, and otherwise the connection this machine saved (any `npx withruntime`
command connects it, with one browser approval).

On a server, put a key from https://withruntime.com/account/keys in
`RUNTIME_API_KEY`, stored in your secret manager. Never put it in source code, a
URL or a command-line argument. With no key anywhere, `RuntimeClient.create()`
throws `RuntimeCloudException.Authentication` whose code is `missing_api_key`
and whose hint says how to get one.

## Hello, sandbox

```java
import com.withruntime.*;

public class Hello {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try (Sandbox sbx = runtime.sandboxes().create(new CreateSandbox())) {
      sbx.files().write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
      CommandResult result = sbx.exec("python3 /workspace/invoice.py", new ExecOptions().check(true));
      System.out.print(result.stdout());
    }
  }
}
```

`create` returns once the sandbox is running. Closing the sandbox deletes it.
`new CreateSandbox().keep()` makes closing stop the sandbox instead, and keeps
its disk. `delete()` deletes a sandbox at any time. With no options, you get the
free usage while it lasts, the default region, and 2 vCPU, 4 GiB of memory and a
4 GiB disk. The sandbox runs while it works and pauses itself when idle. It has
no time limit unless you set one with `timeoutSeconds(seconds)` (60 to 86,400).
The free usage is spent first, then prepaid credit. `funding(...)` is accepted
and ignored. Every field is optional:

```java
import com.withruntime.*;

public class Sized {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    Sandbox sbx =
        runtime
            .sandboxes()
            .create(
                new CreateSandbox()
                    .name("tests-42")
                    .label("team", "search")
                    .vcpu(2)
                    .memoryMiB(4096)
                    .diskMiB(8192)
                    .timeoutSeconds(900)
                    .onLeaseEnd("stop")
                    .network(new NetworkRules().internet(true).allow("repo.maven.apache.org")));
    System.out.println(sbx.id() + " " + sbx.info().funding() + " " + sbx.info().endsAt());
    sbx.stop();
  }
}
```

A field newer than the SDK goes in with `.set("field", value)`.

## Run commands

`exec` runs a string under `bash -c`. `execArgv` runs a program directly, with
no shell. Use it for untrusted arguments.

```java
import com.withruntime.*;
import java.time.Duration;
import java.util.List;

public class Commands {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try (Sandbox sbx = runtime.sandboxes().create()) {
      sbx.exec("mkdir -p app && echo 'print(1 + 1)' > app/main.py");
      CommandResult run =
          sbx.execArgv(
              List.of("python3", "main.py"),
              new ExecOptions()
                  .cwd("/workspace/app")
                  .env("API_TOKEN", System.getenv("API_TOKEN"))
                  .timeout(Duration.ofMinutes(2)));
      if (run.exitCode() != 0) System.err.print(run.stderr());
      System.out.print(run.stdout());

      sbx.exec("for i in 1 2 3; do echo line $i; sleep 1; done", new ExecOptions().onStdout(System.out::print));
      try (EventStream<OutputEvent> events = sbx.execStream("node --version", new ExecOptions())) {
        for (OutputEvent event : events)
          if (event.type().equals("stdout")) System.out.print(event.data());
      }
    }
  }
}
```

- `env` passes secrets to a command. Runtime never echoes them back. Never put a
  secret in the command line.
- `stdin` gives the command input, then closes it.
- `.user("root")` runs the command as root, with no `sudo` in front, keeping
  its `env` and `PATH`; `HOME` is `/root`. `SpawnOptions` takes it too, and
  `ProcessInfo.user()` says which user a process runs as.
- The default timeout is 60 seconds; the maximum is 24 hours. A timeout is a
  result (`timedOut()` is true, with the output so far), not an exception.
- `check(true)` throws `RuntimeCloudException.Command`, with the exit code and
  output, on a non-zero exit or a timeout.
- A result holds all of the output, up to 256 MiB of each stream (no limit
  with `onStdout` or `onStderr`). `stdoutBytes()` and
  `stderrBytes()` give the bytes each stream wrote. `maxOutputBytes(n)` keeps at
  most `n` bytes of each stream; `truncated()` is then `true`. With `onStdout`,
  `onStderr`, or a timeout over a minute, the command streams. When the server
  ends a long stream, it resumes by itself. No output is dropped.

## Background processes

```java
import com.withruntime.*;

public class Processes {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try (Sandbox sbx = runtime.sandboxes().create()) {
      SandboxProcess server = sbx.spawn("python3 -m http.server 8000", new SpawnOptions().cwd("/workspace"));
      SandboxProcess repl = sbx.spawn("python3 -i -q", new SpawnOptions().pipeStdin());
      repl.write("print(21 * 2)\n", true);
      System.out.print(repl.waitFor().stdout());
      for (ProcessInfo process : sbx.processes()) System.out.println(process.id() + " " + process.state());
      server.kill("SIGTERM");
    }
  }
}
```

A process outlives your connection. Get it back with `sbx.process(id)`.
`write` tracks input offsets, so a retried write is never typed twice.

## Files

```java
import com.withruntime.*;
import java.nio.file.Path;

public class FilesExample {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try (Sandbox sbx = runtime.sandboxes().create()) {
      sbx.files().write("/workspace/data/input.csv", "a,b\n1,2\n");
      System.out.print(sbx.files().readText("/workspace/data/input.csv"));
      for (FileEntry entry : sbx.files().list("/workspace", 2, null))
        System.out.println(entry.type() + " " + entry.size() + " " + entry.path());
      sbx.files().mkdir("/workspace/out", true);
      sbx.files().rename("/workspace/data/input.csv", "/workspace/out/input.csv", false);
      sbx.files().upload(Path.of("src"), "/workspace/project/src");
      sbx.files().download("/workspace/out", Path.of("out"));
    }
  }
}
```

`write` creates parent directories and replaces the file atomically. A file over
1 MiB goes in parallel chunks, each checked by SHA-256. `stat` returns `null` for
a path that does not exist. `upload` and `download` move a whole directory as
one gzipped tar archive, through the API's folder routes. The sandbox packs and
unpacks it with `tar` ([files in the API guide](./api#files)). A large folder
uploads in parts. A downloaded folder is unpacked as it arrives. It lands in place
only after all of it has arrived. A download cut short fails with
`download_incomplete` and writes nothing.

## Pause, wake, fork and snapshot

```java
import com.withruntime.*;
import java.time.Duration;
import java.util.List;

public class Lifecycle {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try (Sandbox sbx = runtime.sandboxes().create(new CreateSandbox())) {
      sbx.pause(); // memory and files are kept; compute billing stops
      Sandbox again = runtime.sandboxes().get(sbx.id());
      again.wake(Duration.ofMinutes(20));
      again.extend(Duration.ofMinutes(10));

      List<Sandbox> copies = again.fork(new ForkOptions().count(2));
      for (Sandbox copy : copies) copy.stop();

      Snapshot snapshot = again.snapshot(new SnapshotOptions().name("ready").retentionDays(7));
      try (Sandbox fromSnapshot = runtime.sandboxes().create(new CreateSandbox().snapshot(snapshot.id()))) {
        System.out.println(fromSnapshot.id());
      }
      runtime.snapshots().delete(snapshot.id());
    }
  }
}
```

A fork copies a sandbox as it is now, with its files, memory and running
processes. It runs on its server while that server has room, and on another
server when it is full. See [JavaScript](./javascript) for what forks and
snapshots keep and how they are billed. If a copy fails, the exception's
`details().get("startedSandboxIds")` names the copies that did start.
`wake(Duration)` and `extend(Duration)` set and move a time limit, for a
sandbox that has one. On a sandbox without a time limit, `extend` changes
nothing. `sbx.keepAlive(every, margin, onError)` moves the time limit on from
your process until `stop()`. `runtime.sandboxes().getOrCreate(name, options)`
returns the sandbox with that name, woken or restarted, or creates it.

## Share a port

```java
import com.withruntime.*;

public class Share {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try (Sandbox sbx = runtime.sandboxes().create()) {
      sbx.spawn("python3 -m http.server 3000", new SpawnOptions());
      Preview preview = sbx.previews().create(3000);
      System.out.println(preview.url() + " " + preview.token()); // send the token as x-runtime-preview-token
    }
  }
}
```

A preview is private by default. `create(port, "public", null)` shares it with
anyone who has the address. Addresses are under `runtimehost.com`.

## Images, volumes, network rules and secrets

```java
import com.withruntime.*;
import java.util.List;
import java.util.Map;

public class Storage {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    Image image =
        runtime
            .images()
            .build(
                new CreateImage().name("data").recipe(Map.of("pip", List.of("pandas"), "apt", List.of("jq"))),
                line -> System.out.println(line.getString("text")));
    Volume volume = runtime.volumes().create(10240, "cache", null);
    try (Sandbox sbx = runtime.sandboxes().create(new CreateSandbox().image(image.id()).volume(volume.id(), "/data", null))) {
      System.out.print(sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'").stdout());
      JsonObject cell = sbx.interpreter().run("import math\nround(math.pi * 2, 3)");
      System.out.println(cell.getObjects("results").get(0).getObject("data").getString("text/plain"));
      sbx.network().set(new NetworkRules().internet(true).allow("pypi.org", "*.pythonhosted.org"));
    }
    JsonObject secret = runtime.secrets().set("OPENAI_API_KEY", "sk-...", List.of("api.openai.com"));
    System.out.println(secret.getString("placeholder")); // what sandboxes see in $OPENAI_API_KEY
  }
}
```

`images().build` waits until the image is ready. It throws with code
`image_failed` when the build fails. `images().create` queues the build and
returns. A Dockerfile build takes `dockerfile(text)` and `contextDir(path)`, the
folder `docker build` would read, with its `.dockerignore`. Only the parts the
server does not have yet are uploaded. See [custom images](./images). A volume
lives on one server. Its backups can restore a new volume onto another host.
`sbx.desktop()` drives a Linux desktop in the sandbox.

## Metrics, events and webhooks

```java
import com.withruntime.*;
import java.nio.charset.StandardCharsets;
import java.util.List;

public class Hooks {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    JsonObject hook = runtime.webhooks().create("https://example.com/hooks/runtime", null, null);
    String secret = hook.getString("secret"); // shown once; keep it

    // In your endpoint, with the raw body and the Runtime-Signature header:
    byte[] body = "{}".getBytes(StandardCharsets.UTF_8);
    String header = "t=0,v1=0";
    try {
      JsonObject event = Products.Webhooks.verify(body, header, List.of(secret));
      System.out.println(event.getString("type"));
    } catch (SecurityException forged) {
      System.out.println("refused: " + forged.getMessage());
    }
    for (JsonObject event : runtime.events().list(null, "sandbox.stopped"))
      System.out.println(event.getString("createdAt") + " " + event.getString("type"));
  }
}
```

`sbx.metrics("15m")` returns the sandbox's measured CPU and memory, and
`runtime.otel().create(...)` pushes events and metrics to an OpenTelemetry
endpoint. See [metrics and webhooks](./observability).

## Errors and retries

```java
import com.withruntime.*;

public class Errors {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    try {
      runtime.sandboxes().get("00000000-0000-4000-8000-000000000000");
    } catch (RuntimeCloudException.NotFound missing) {
      System.out.println("no such sandbox");
    } catch (RuntimeCloudException failure) {
      System.out.println(failure.code() + " " + failure.hint() + " " + failure.requestId());
    }
  }
}
```

Every exception is a `RuntimeCloudException` (unchecked) with `code()`,
`getMessage()`, `hint()`, `requestId()`, `status()` and `details()`. Its
subclasses are `Authentication`, `PermissionDenied`, `NotFound`, `Conflict`,
`InvalidRequest`, `RateLimited`, `ServiceUnavailable`, `Connection` and
`Command`. They are the same classes as in the JavaScript, Python and Go SDKs.
`no_capacity` is `ServiceUnavailable`. `no_credit_running_limit`, and a
`quota_exceeded` on what runs at the same time, are `RateLimited`. A
`quota_exceeded` on what is kept is `Conflict`.

Every write carries an idempotency key. The client makes it for you and keeps it
across its own retries. Transport failures, and every response that says
`retryable: true`, are retried after its `Retry-After`. Retries stop at the
maximum number of retries. Each retry uses the same key, so a retry never makes
two sandboxes or runs a command twice. A wait over 60 seconds is not slept on.
The error returns immediately, with `retryAfterMs`. A response that ran nothing
(`guest_busy`, `busy`, `rate_limited`, `sandbox_starting`) is sent again until
the call's deadline.
Without a deadline, it is sent again for five minutes, past the maximum.
`retryable()` says whether trying the same call again may work.

**A create, wake or restart waits for room.** When all four slots
without credit are taken (`no_credit_running_limit`), the account is at its limit
(`quota_exceeded`), or the region is full (`no_capacity`), `sandboxes().create`
waits and sends the same request again, for up to two minutes. Set
`waitForCapacity` on the client builder, or on one `CreateSandbox`, wake or
restart. Zero fails immediately. A sandbox stays on its server, so a wake or
restart refused with `no_capacity` is sent again with the same idempotency key
until room frees. A fork waits the same way when no server has room for a copy;
set `waitForCapacity` on its `ForkOptions` to change the wait.

An owner, admin or developer can make a read-only key and set a daily spending
limit on a key at [API keys](https://withruntime.com/account/keys).
`runtime.limits().get()` reads both. Past the limit, a create, wake or extension
throws with code `spending_limit_reached`, and it is not retried.

## Configuration

```java
import com.withruntime.*;
import java.time.Duration;

public class Configured {
  public static void main(String[] args) {
    RuntimeClient runtime =
        RuntimeClient.builder()
            .apiKey(System.getenv("MY_RUNTIME_KEY"))
            .timeout(Duration.ofMinutes(2))
            .maxRetries(4)
            .waitForCapacity(Duration.ofMinutes(10))
            .build();
    System.out.println(runtime.me().orgId());
    System.out.println(runtime.request("GET", "/v1/volumes", null, null)); // any endpoint, same rules
  }
}
```

- `RUNTIME_API_URL` points the client at another API origin, as `baseUrl`
  does.
- Code inside a Runtime sandbox calls Runtime's API at `http://runtime.internal`
  ([Runtime's API from inside a sandbox](./sandbox-environment#runtime-s-api-from-inside-a-sandbox)).
- The client is safe for concurrent use. Make one and share it. It keeps its
  connections open and holds at most 32 calls in flight (`maxConnections`).
- It honours `HTTPS_PROXY` and `NO_PROXY`. `httpClient` supplies your own
  `java.net.http.HttpClient`.
- Money is integer microdollars: 1,000,000 is one US dollar.
  `runtime.usage()` returns the account's balance exactly, as `BigInteger`.
- `runtime.usageExport(since, until, cursor, limit)` reads one page of settled
  usage over a UTC range, with its server CSV. Follow `nextCursor()` until it
  is null. `finalThrough()` is the time before which no more charges will
  settle. A row's `isFinal()` is true once its resource is deleted and can be
  charged nothing more ([export settled usage](./api#export-settled-usage)).

## Network products and backups

`runtime.domains()`, `ports()`, `addresses()` and `tunnel()` manage account
networking. Domains and ports name the sandbox they serve. `tunnel()` is the
account's WireGuard network. It is separate from a sandbox's TCP forwarding.
Responses keep the API's complete fields through `JsonObject`. Use `getLong`
for integer money, and `getInstant` for funding deadlines. When credit runs out,
an address or tunnel reservation stays until it is released. Traffic stops during
the unfunded time.

```java
import com.withruntime.*;
import java.util.List;

public class NetworkProductsExample {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    JsonObject domain = runtime.domains().add("app.example.org", args[0], 8080);
    System.out.println(domain.getObjects("records")); // Publish these DNS records, then verify.
    JsonObject address = runtime.ips().reserve(4);
    System.out.println(address.getString("address"));
    System.out.println(address.getLong("rateMicros"));
    runtime.networks().wireguard().create("10.66.0.0/24");
    JsonObject peer = runtime.networks().wireguard().addPeer("laptop", null, List.of());
    // Save peer.getString("config") privately, even when configReady is false.
    // Its private key is shown once; generated-key calls are not automatically retried.
    System.out.println(peer.getBoolean("configReady"));
    System.out.println(runtime.sso().get()); // Owner console manages SSO settings.
  }
}
```

`volumes().backup`, `backups`, `getBackup`, `deleteBackup`, `setBackupPolicy`
and `restore` manage backups. `setBackupSchedule(id, 60, null, Map.of("hourly",
24, "daily", 7))` backs the volume up every 60 minutes (or pass a UTC cron
instead of the minutes) and keeps backups by those counts.
`clearBackupSchedule(id, null)` goes back to daily. A restore creates a new
volume. It does not replace the original. A backup's `backedUp` field is true
once its copy has been checked off the source host. Writes after that backup are
not in it.

```java
import com.withruntime.*;

public class VolumeBackupExample {
  public static void main(String[] args) {
    RuntimeClient runtime = RuntimeClient.create();
    runtime.volumes().setBackupPolicy(args[0], true, 7);
    JsonObject backup = runtime.volumes().backup(args[0], "before-update");
    if ("ready".equals(backup.getString("state"))) {
      Volume restored = runtime.volumes().restore(backup.getString("id"), "restored");
      System.out.println(restored.id());
    }
  }
}
```

## File permissions and watching

`Files.WriteOptions.mode(0755)` sets permissions atomically on current guest
images. `0` means no permissions, rather than the default. Older images use
the `exec` permission for a chmod fallback. A supplied write idempotency key
covers the whole upload, including completed retries. `files().chmod` changes
an existing file's permissions.

A watch's `events()` follows its cursor across server handovers. Loss notices
(`overflow` or `lost`) mean the caller should rescan. Closing the event stream
stops reading. `watch.stop()` also stops the guest watch. A later `events()`
resumes after a pause or an earlier reader close. Only one reader uses a watch
at a time. `files().watches()` also lists watches, polls and stops them by ID.

```java
import com.withruntime.*;
import java.util.Map;

public class FileWatchExample {
  public static void main(String[] args) {
    Sandbox sandbox = RuntimeClient.create().sandboxes().get(args[0]);
    sandbox.files().write("/workspace/run.sh", "#!/bin/sh\necho ready\n",
        new Files.WriteOptions().mode(0755).idempotencyKey("install-run-script-v1"));
    FileWatch watch = sandbox.files().watch("/workspace", Map.of("recursive", true));
    try (EventStream<JsonObject> events = watch.events()) {
      for (JsonObject event : events) {
        System.out.println(event);
        if ("paused".equals(event.getString("k"))) break;
      }
    } finally {
      watch.stop();
    }
  }
}
```

## Terminals and TCP forwarding

A terminal carries binary input/output over an authenticated WebSocket.
Read output while writing input. Close it to release a blocked reader or
writer. Interrupting its reader also closes it. Its opening deadline follows
the client's timeout. Closing an attached terminal does not stop its existing
process. A new terminal's shell ends with the connection.

`openTunnel()` multiplexes loopback TCP streams. A stream's `closeWrite()`
sends input EOF and keeps reading the response. Each stream holds at most
1 MiB of unread response data. If a stream exceeds that bound, only that stream
fails with `tunnel_receive_overflow`, after delivering its buffered bytes.
`portForward()` copies both directions for each local connection. It closes
its listener and active connections together.

```java
import com.withruntime.*;
import java.net.InetSocketAddress;
import java.util.Map;

public class TerminalForwardExample {
  public static void main(String[] args) throws Exception {
    Sandbox sandbox = RuntimeClient.create().sandboxes().get(args[0]);
    try (Terminal terminal = sandbox.terminal(Map.of("command", "printf ready"))) {
      terminal.input().transferTo(System.out);
      System.out.println(terminal.exitCode());
    }
    try (PortForward forward = sandbox.portForward(5432, new InetSocketAddress("127.0.0.1", 0))) {
      System.out.println(forward.address()); // Connect your local database client here.
      System.in.read();
    }
  }
}
```

## Bucket mounts and recordings

`sbx.mounts().add(options)` takes provider, bucket, path and the name of a
Runtime secret, keeping the bucket key outside the sandbox. `list()` and
`remove(path)` manage its lifecycle.

`sbx.desktop().recordings()` has `start`, `get`, `list`, `stop`, `download`
and `delete`. Downloads return MP4 bytes. Recordings live on the sandbox's
own disk and count toward that disk's space.


---

<!-- https://withruntime.com/docs/javascript -->

# JavaScript and TypeScript SDK

One client for every Runtime Cloud product. It runs on Node 22.12 or later, and on Bun.

`withruntime` ships the `runtime` CLI. Its one dependency, `undici`, loads only when a proxy applies. If you run behind a proxy, see [troubleshooting](./troubleshooting). In a Cloudflare Worker, it needs `nodejs_compat` and a wrapped `fetch`. See [calling Runtime from a Worker](./cloudflare-sandbox-alternative#calling-runtime-from-a-worker).

```bash no-run
npm install withruntime
```

This guide describes `withruntime` 0.50.1. Run `npm ls withruntime` to see the version you have. If a method named here is missing from yours, you have an older version. Run `npm install withruntime@latest` to update it.

**The client finds its key by itself.** It uses `RUNTIME_API_KEY` when that variable is set. Otherwise, it uses the connection this machine saved. Any `npx withruntime` command creates that connection, with one browser approval.

On a server, put a key from https://withruntime.com/account/keys in `RUNTIME_API_KEY`. Load it from your secret manager. Never put it in source code, a URL, a browser bundle or a command-line argument. If no key is set anywhere, the first call fails with `missing_api_key`. The error says how to get one.

One plural word names each product. The CLI, the API and MCP use the same names. A name renamed on 6 October 2026 keeps working for 30 days after the rename ships. Each use prints the new name once on stderr. After 30 days, the old name fails with `name_retired`. The hint names the new one.

| Product                      | Old name                               |
| ---------------------------- | -------------------------------------- |
| `runtime.sandboxes`          | `runtime.sandbox`                      |
| `runtime.snapshots`          | `runtime.snapshot`                     |
| `runtime.images`             | `runtime.image`                        |
| `runtime.volumes`            | `runtime.volume`                       |
| `runtime.jobs`               | `runtime.job`                          |
| `runtime.domains`            | `runtime.domain`                       |
| `runtime.ports`              | `runtime.port`                         |
| `runtime.ips`                | `runtime.address`, `runtime.addresses` |
| `runtime.networks`           | `runtime.network`                      |
| `runtime.networks.wireguard` | `runtime.tunnel`                       |

Each product can also be imported alone. Use the same word, from `withruntime/<product>`: `sandboxes`, `snapshots`, `images`, `volumes`, `jobs`, `domains`, `ports`, `ips` and `networks`. Each import has one function. It takes the client's options and returns that product. It finds the key the same way.

```ts no-run
import { volumes } from "withruntime/volumes";

const volume = await volumes().create({ sizeMiB: 10_240, name: "cache" });
```

## Hello, sandbox

Write a file that totals three invoice amounts. Then run it. The total is 750.

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

await using sbx = await Sandbox.create();
await sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
const result = await sbx.exec("python3 /workspace/invoice.py");
console.log(result.exitCode, result.stdout); // 0, "750\n"
```

`Sandbox.create()` takes no required arguments. It returns once the sandbox is running. `await using` deletes the sandbox when the block ends, even after an error. To stop the sandbox instead and keep its disk, create it with `keep: true`. It needs Node 24, Bun, Deno or TypeScript. In plain JavaScript on Node 22, write `const sbx = ...` and call `await sbx.delete()` in a `finally` block.

With no arguments, you get the free usage while it lasts. You also get the default region, and 2 vCPU, 4 GiB of memory and a 4 GiB disk. The sandbox runs while it works. It pauses itself when idle. It has no time limit. A paid sandbox can have up to 16 vCPUs and 64 GiB. A sandbox without credit can have 2 vCPU and 4 GiB.

The free usage is spent first, then prepaid credit. You cannot choose between them. `funding` is accepted and ignored. Every field is optional:

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

const runtime = new Runtime(); // RUNTIME_API_KEY, or this machine's connection
const sbx = await runtime.sandboxes.create({
  name: "tests-42",
  labels: { team: "search", job: "42" },
  vcpu: 2,
  memoryMiB: 4096,
  diskMiB: 8192,
  timeoutSeconds: 900,
  onLeaseEnd: "stop",
  network: { internet: true, allow: ["pypi.org", "*.pythonhosted.org"] },
});
console.log(sbx.id, sbx.info.funding, sbx.info.endsAt);
await sbx.stop();
```

A sandbox needs no time limit. It runs while it works and pauses itself when idle. It keeps running until you stop it, or until credit or the [free usage](./included-usage) runs out. `timeoutSeconds` (60 to 86,400, 24 hours) sets a limit when you want one. The example above sets one. At the end, the sandbox pauses (the default) or stops, as `onLeaseEnd` says. This happens whether it is busy or not. `sbx.info.endsAt` is when it will stop or pause by itself. It is `null` when it never will. `sbx.extend(seconds)` moves the end later. `sbx.update({ timeoutSeconds, onTimeout })` sets a new end from now. It can be sooner or later. `0` removes the limit. `network` narrows what the sandbox can reach from its first start. See [the sandbox environment](./sandbox-environment).

`env` sets variables for the sandbox's whole life. They apply to every command, background process, terminal, SSH session and image start command in the sandbox. A command's own `env` takes precedence over them. Values are never shown again. `sbx.info` and every later response carry only `envNames`. `update({ env })` changes the variables. A value sets a variable, and `null` removes one. Changes apply to commands started after the update. The sandbox allows at most 32 variables and 32 KiB. Forks keep them ([API](./api#sandboxes)).

```ts check
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create({
  env: { QUEUE_URL: "https://queue.example.com", MODE: "worker" },
});
console.log(sbx.info.envNames); // ["MODE", "QUEUE_URL"]
await sbx.update({ env: { MODE: "drain", QUEUE_URL: null } });
await sbx.delete();
```

## Run commands

A string runs under `bash -c`. An array runs the program directly, with no shell. Use an array for untrusted arguments.

**A server, a watcher or anything that should keep running goes in [`spawn`](#background-processes), not `exec`.** Everything an `exec` starts ends when its command returns. That includes `nohup … &` and `setsid`. A result holds all of the command's output (see below).

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

await using sbx = await Sandbox.create();
await sbx.exec("mkdir -p app && echo 'print(1 + 1)' > app/main.py");
const run = await sbx.exec(["python3", "main.py"], {
  cwd: "/workspace/app",
  env: { API_TOKEN: process.env.API_TOKEN ?? "" },
  timeoutMs: 120_000,
});
if (run.exitCode !== 0) console.error(run.stderr);
```

- `env` is how secrets reach a command. It is never echoed back. Journals record a hash, not the value. Never put a secret in the command line itself.
- `user: "root"` runs the command as root, with no `sudo` in front. Its `env`, `PATH` and working directory stay the same. `HOME` is `/root`. The default, `"sandbox"`, is the user `runtime`. `spawn` and `terminal` take it too. A process says which user it runs as in `info.user`.
- `stdin` gives the command input, then closes it.
- The default timeout is 60 seconds. If the sandbox's time limit has less time left, the timeout is that time instead. When the output streams (`onStdout`, `onStderr` or `execStream`), the default is 24 hours. The maximum is 24 hours. A command with no `timeoutMs` is never refused for the time limit. A timeout is a result, not an exception. The result has `timedOut: true`, with the output so far.
- `check: true` throws `CommandError` on a non-zero exit, with the result on it.
- The sandbox's out-of-memory killer can end a command. When it does, the result has `outOfMemory` set. Its process has the same details: the code, processes killed, the sandbox's size, a message and a hint. With `check: true`, the call throws `CommandError` with the code `out_of_memory` ([when a program runs out of memory](./sandbox-environment#when-a-program-runs-out-of-memory)).
- A result holds all of `stdout` and `stderr`, up to 256 MiB of each; with `onStdout` or `onStderr` there is no limit. `stdoutBytes` and `stderrBytes` give the bytes each stream wrote. `maxOutputBytes: n` keeps at most `n` bytes of each stream, cut between UTF-8 characters; `stdoutTruncated`, `stderrTruncated` and `truncated` are then `true` for a stream that was cut. Otherwise they are `false`.

Stream output as it happens, with callbacks or by iterating the events:

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

await using sbx = await Sandbox.create();
await sbx.exec("for i in 1 2 3; do echo line $i; sleep 1; done", {
  onStdout: (text) => process.stdout.write(text),
  onStderr: (text) => process.stderr.write(text),
});
for await (const event of sbx.execStream("npm --version")) {
  if (event.type === "stdout") process.stdout.write(event.data);
  if (event.type === "exit") console.log("exit", event.exitCode);
}
```

A stream that runs past the server's limit resumes by itself from the right byte. So no output is lost or repeated. While you read a command's stream, the command waits for you. That way it does not lose output, from its first byte. The sandbox keeps the latest 1 MiB. If a reader is away for more than 10 seconds while more than 1 MiB comes out, the reader loses the oldest part. It gets a `truncated` event. The result has both truncation flags set to `true`.

From withruntime 0.7.0, a stream also resumes from the right byte. This happens when its connection drops after the command started. A streamed exec cancelled through `signal` sends its command SIGTERM. It then throws `cancelled`, with `details.processId`. A stream that cannot pick up again throws `connection_error`. That error names the process, which may still be running. `sbx.processes.get(processId)` reads or stops it.

## Background processes

`spawn` starts a server, a watcher or a REPL. It returns immediately. The process outlives your connection. Get it back later with `sbx.processes.get(id)`.

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

await using sbx = await Sandbox.create();
const server = await sbx.spawn("python3 -m http.server 8000", { cwd: "/workspace" });
console.log(server.id, server.state); // console.log(server) shows id, command, state, exitCode

const repl = await sbx.spawn(["python3", "-i", "-q"], { stdin: "pipe" });
await repl.write("print(sum([125, 250, 375]))\n");
await repl.write("exit()\n", { eof: true });
const done = await repl.wait();
console.log(done.stdout);

for (const p of await sbx.processes.list()) console.log(p.id, p.state, p.command);
await server.kill("SIGTERM");
```

`spawn(command, { request: { signal, timeoutMs, idempotencyKey } })` controls the HTTP request. It is separate from the process's execution timeout. The outer `timeoutMs` controls the guest process. `request.timeoutMs` controls the client's request and its retries.

`process.write()` tracks accepted input offsets. It keeps concurrent writes in order. When the process accepts only part of the input, later chunks match its capacity. When its input pipe is full, the SDK waits briefly and retries. It does not advance the offset while it waits. An empty EOF write closes input after earlier queued writes finish. Pass `signal` and `timeoutMs` in the same options object as `eof`. A caller-supplied `idempotencyKey` is refused before writing. Replaying a logical write after partial progress could duplicate input. Each request retry stays protected by its input offset and the SDK's per-request key. An explicit timeout covers the queue, every chunk and every backpressure wait together. A canceled queued write sends nothing. Process `get`, `list`, `kill` and `resize` also accept request options. They have the same cancellation and timeout controls.

`process.output()` yields every event from the start, or from a `cursor`. It does this until the process exits. The sandbox keeps each process's latest 1 MiB of output. So a reader that reconnects misses nothing. The exception is when more than 1 MiB came out while it was away. Then a `truncated` event says how many bytes are gone. `wait()` sets both truncation flags. A process that prints more than 1 MiB should write to a file.

## An interactive terminal

`terminal()` opens a real terminal over a WebSocket. What you write is typed into it. `onData` receives what the terminal prints, colours and all.

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

await using sbx = await Sandbox.create();
const term = await sbx.terminal({
  cols: 120,
  rows: 40,
  onData: (bytes) => process.stdout.write(bytes),
});
term.write("echo hello from the terminal\n");
term.resize(100, 30);
term.write("exit\n");
console.log("exit code", await term.exited);
```

`npx withruntime sandboxes shell <id>` does the same from your own terminal.

## Files

Paths are absolute. `/workspace` is the sandbox user's home. Any path the user can reach works. `sudo` reaches the rest.

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

await using sbx = await Sandbox.create();
await sbx.files.write("/workspace/data/input.csv", "a,b\n1,2\n");
const text = await sbx.files.readText("/workspace/data/input.csv");
const bytes = await sbx.files.read("/workspace/data/input.csv");
console.log(text.length === bytes.length);

console.log(await sbx.files.exists("/workspace/data/input.csv"));
console.log(await sbx.files.stat("/workspace/data/input.csv"));
for (const entry of await sbx.files.list("/workspace", { depth: 2 }))
  console.log(entry.type, entry.size, entry.path);
console.log(await sbx.files.glob("**/*.csv"));

await sbx.files.mkdir("/workspace/out");
await sbx.files.rename("/workspace/data/input.csv", "/workspace/out/input.csv");
await sbx.files.remove("/workspace/data", { recursive: true });
```

`write` creates parent directories and replaces the file atomically. Large files go in parallel, in 1 MiB chunks. Each chunk is checked by SHA-256. A transfer resumes after a dropped connection. Under `/workspace`, there is no size limit beyond the disk. Elsewhere, a file is written with the sandbox user's own rights. It can be at most 1 MiB. To write a larger file, write it to `/workspace`. Then move it with a command.

Copy whole directories in one call. They travel as one compressed archive.

```ts
import { mkdtemp, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Sandbox } from "withruntime";

const project = await mkdtemp(join(tmpdir(), "project-"));
await writeFile(join(project, "main.py"), "print('hi')\n");

await using sbx = await Sandbox.create();
await sbx.files.upload(project, "/workspace/project");
await sbx.exec("cd project && python3 main.py > result.txt");
await sbx.files.download("/workspace/project", join(project, "..", "project-out"));
```

`download(remote, local, { signal, timeoutMs })` applies one explicit deadline. The deadline covers metadata, transfer, gzip, extraction and retries. A file download publishes its temporary file only once it is complete. A directory download stages and verifies the archive before it merges. Cancellation stops later changes. Files already merged into an existing destination are kept.

An uploaded file keeps its permissions, so a script stays runnable. `write(path, data, { mode: 0o755 })` sets them. The default is 0o644 when left out.

`files.archive(path, { gzip, exclude, user })` returns a `Uint8Array` of a folder's tar bytes. The bytes are gzip-compressed by default. `exclude` takes plain relative paths, not globs. `files.unarchive(path, bytes, { gzip, user })` merges those bytes into a folder. It detects gzip when omitted. Both default to the sandbox user. Pass `user: "root"` explicitly for root-owned trees. This requires passwordless `sudo` inside the sandbox. For example:

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.files.write("/workspace/project/report.txt", "total: 750\n");
const archive = await sbx.files.archive("/workspace/project");
await sbx.files.unarchive("/workspace/restored", archive);
console.log(await sbx.files.readText("/workspace/restored/report.txt"));
```

A directory download keeps the links inside the directory. It throws `unsafe_archive` for any entry or link that would reach outside it. So nothing in a sandbox can write elsewhere on your machine. Before it publishes, the download also checks links against files already in the destination. Invalid checksums, malformed path metadata and incomplete tar end markers are refused. Do not treat a partial directory as a successful copy.

From `withruntime` 0.7.0, reads are checked. The API sends each file's length before its bytes. It also sends a small file's SHA-256. If a file arrives short, `read` reads it again. If it is still short, `read` throws `download_incomplete`. It does not return part of the file. For a file too big to hold in memory, use `readStream`. It hands you the bytes as they arrive (Daytona's `downloadFileStream`). It errors if they end short. `download` streams to disk through a partial file. The partial file is renamed into place only once it is whole:

```ts no-run
import { createWriteStream } from "node:fs";
import { Writable } from "node:stream";
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
const stream = await sbx.files.readStream("/workspace/dataset.tar");
await stream.pipeTo(Writable.toWeb(createWriteStream("dataset.tar")));
```

For single-file uploads on Node or Bun, `files.writeStream` accepts a local file path, a Blob, a byte iterator or a readable byte stream. It checks the complete size and digest before it starts the remote upload. A known local file or Blob needs no extra staging copy. An unknown-length source first writes one private temporary file. The temporary file is limited to the local disk space available at the start. Then the SDK reads that file for upload. This adds one extra write and read of the payload on your machine. Browser callers use `files.write` with byte data instead.

```ts no-run
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.files.writeStream("/workspace/dataset.tar", "./dataset.tar", {
  signal: AbortSignal.timeout(120_000),
  onProgress: ({ bytesSent }) => console.log(bytesSent),
});
```

Upload reads use bounded parallel chunks. The SDK does not buffer the whole file. Chunks from the source and transport buffers also use memory. When an upload is canceled or fails, the SDK closes the input streams it owns. It drains the active upload workers. It tries a remote abort, with a separate cleanup deadline. It removes the private stage. An input iterator that never finishes closing has a bounded cleanup wait.

`upload` and `download` of a directory move one tar archive through the API's folder routes. Those routes pack and unpack the archive with `tar` inside the sandbox. From a language with no SDK, the same routes take a plain PUT or GET ([files in the API guide](./api#files)). A downloaded folder is unpacked as it arrives. Its size is limited only by your disk. It lands in place only once all of it has arrived.

A sandbox holds at most 4 uploads and 4 downloads at once. Extra transfers wait for `transfer_limit` to clear. Each transfer frees its slot when it ends. A download left unread for a minute gives its slot to the next one.

### Watch files

`files.watch` delivers changes under a directory as they happen. It reports create, write, remove, rename (with `oldPath`) and chmod. It is E2B's `watchDir`, with more. It adds include and exclude globs. An excluded directory is not watched at all. It batches changes. Repeated writes to one file fold into one event with a `count`. A new directory is scanned as it appears. So files made in it before its watch took effect are reported too.

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
const watch = await sbx.files.watch("/workspace", (event) => console.log(event.type, event.path), {
  recursive: true,
  exclude: ["node_modules", ".git/**"],
  onNotice: (notice) => console.warn("rescan:", notice),
  onExit: (reason) => console.log("watch ended:", reason),
});
await sbx.exec("echo hi > /workspace/note.txt");
await watch.stop();
```

A sandbox runs at most four watches. Each watch ends after `timeoutMs`. The default is one hour. A flood of changes is capped at 5,000 events a second. Dropped events are reported through `onNotice`, as an `overflow` with how many were dropped. They are never dropped silently. Reading a watch never wakes a paused sandbox. Delivery stops with `onExit("paused")`. After the sandbox wakes, `watch.resume()` carries on from the same place. Nothing is lost.

To have changes pushed to you instead, start the watch for your account's [webhooks](./observability#events). Runtime reads the watch and sends `sandbox.files.changed` events. The events are signed and retried. Nothing of yours runs in the sandbox or reads here. The watch runs until stopped, unless you give `timeoutMs`. It never keeps a sandbox that pauses itself awake.

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
const watch = await sbx.files.watches.webhook("/workspace/app", { recursive: true, id: "sync" });
await sbx.files.watches.stop(watch.id);
```

## Pause, wake, extend

```ts check
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create({ timeoutSeconds: 600 }); // a ten-minute limit
await sbx.exec("echo state > /workspace/state.txt");
await sbx.pause(); // memory and files are kept; compute billing stops
// ... later, even from another process:
const again = await Sandbox.connect(sbx.id);
await again.wake({ timeoutSeconds: 1200 }); // a new limit, from the wake
await again.extend(600); // moves the limit ten minutes on
await again.stop();
```

A sandbox created without `timeoutSeconds` has no limit. So `wake()` needs no argument. `extend()` returns immediately and changes nothing.

A paused sandbox keeps its memory, its processes and its files. `pause()` returns once the sandbox's processors have stopped. That is when compute billing ends. The host then writes the sandbox's memory to disk. A wake or snapshot requested in the meantime waits for that write. Wake restores the sandbox on the same host. See [pricing](./pricing) for what a paused sandbox costs and how long it is kept.

A server keeps room for the memory of every sandbox it runs that can pause. When that room is short, a pause still succeeds. It can take up to about a minute while the server makes room. The server compresses saved memory images. It moves kept snapshots to other servers. It copies paused sandboxes to storage and shrinks them. If there is still no room, the sandbox is paused all the same. It is billed as paused. The server holds its memory and saves it once there is room. A wake in the meantime resumes the sandbox at once. Only a sandbox whose time is nearly up is not paused then. It is too near its end to save its memory later. For that sandbox, `pause()` fails with `no_capacity` (503, `retryable` true, `Retry-After: 60`). The sandbox keeps running with its memory and files. Pause again with a new call. That is a new request. A `pause()` that returns first, with the sandbox still `pausing`, has not failed. `GET /v1/sandboxes/{id}?waitFor=paused` (`sbx.refresh()` in a loop) shows `paused`. It shows `running` if the pause was not taken. A snapshot that the server has no room for is refused with `host_capacity` (503). Retry it later.

### Wake on request

A paused sandbox wakes by itself when a request needs it. Such requests include an `exec`, a file, process, terminal, desktop or code-interpreter call, or a visit to one of its shared ports. The call waits while the sandbox wakes. Then the call runs. A browser that visits a shared port sees a short "Waking up" page. The page reloads itself. The wake is billed like any wake. Billing starts from the moment the sandbox runs again. The sandbox runs while it works again. A sandbox with a time limit gets a fresh limit of its own `timeoutSeconds`. Or it keeps the limit it paused with, if that ends later.

Turn it off with `autoWake: false` at create. Or turn it off later with `sbx.update({ autoWake: false })`. A call to a paused sandbox that cannot wake then fails with `sandbox_paused`, until you call `wake()`.

A sandbox that paused for being idle also wakes when a process in it is due on a timer, such as a `sleep 600` loop ([timers](./sandbox-environment#timers-wake-an-idle-sandbox)). To keep request wakes and turn this off, use `wakeOnTimers: false` at create or `sbx.update({ wakeOnTimers: false })`.

### Pause when idle

A sandbox pauses itself after **300 seconds** of idle time. Idle means nothing happens in it. There is no request. No command or terminal is still running. No preview, port, SSH or tunnel connection is open. There is no network traffic. Its processes use under a fortieth of a vCPU. A background job that computes or downloads keeps it running. With automatic wake, the next request wakes it. So a sandbox that is used now and then costs running time only while it is used. Between uses, it costs only parked storage.

`idlePauseSeconds` sets the idle time. It takes 60 to 86,400 seconds, or 0 for never. A `persistent` sandbox has no idle pause unless you set one.

```ts check
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create({ idlePauseSeconds: 600 }); // ten idle minutes
await sbx.update({ idlePauseSeconds: 1800 }); // change it later; 0 turns it off
```

The pause lands within about five seconds of the idle time. A sandbox created before 27 September 2026 keeps the idle setting it had. For the old default, `sbx.info.idlePauseUnusedOnly` is `true`. That default paused only a sandbox that nothing had used.

### Keep a sandbox running

A sandbox with no time limit keeps running while it works, with nothing to renew. Two settings go further:

- **`persistent: true`** keeps a paid sandbox running until you stop it. It runs whether idle or not, for as long as the account has credit. Its disk is billed and kept, as for any sandbox. So after a stop, `sbx.restart()` starts it again. Set a ceiling with `maxTotalCostMicros`. `update({ persistent: false })` makes it an ordinary sandbox again. `delete()` removes it for good.
- **`keepAlive`** moves a time limit on, from your process, while the process runs. It applies to a sandbox created with `timeoutSeconds`. It keeps the limit ten minutes ahead. It checks once a minute. It stops when you call `stop()`, or when you call the function it returns. On a sandbox with no time limit, it only watches.

```ts check
import { Sandbox } from "withruntime";

// Runs while credit lasts; restart() brings it back after a stop.
const server = await Sandbox.create({
  persistent: true,
  maxTotalCostMicros: 50_000_000, // at most $50 over its life
});
await server.update({ persistent: false }); // back to an ordinary sandbox

// A one-hour limit, moved on while this process holds it.
const worker = await Sandbox.create({ timeoutSeconds: 3600, keepAlive: true });
const release = worker.keepAlive({ marginSeconds: 1800 }); // or later, with options
release();
await worker.stop();
```

## Sandboxes by name

A name is unique in the account while its sandbox can still run. That means the sandbox is running, paused, or stopped and persistent. A key in a [compartment](./security#compartments) uses its compartment's own names. `Sandbox.getOrCreate(name)` returns that sandbox. It wakes the sandbox if it is paused. It restarts the sandbox if it is stopped and persistent. If no sandbox has the name, it creates one with the options you pass. `sbx.info.reused` is `true` when it found one.

```ts check
import { Sandbox } from "withruntime";

const dev = await Sandbox.getOrCreate("dev", { idlePauseSeconds: 900 });
await dev.exec("git pull || true");
// The next process, or tomorrow, gets the same sandbox and its files.
```

A create with a name that another sandbox holds fails with `name_taken`. `error.details.sandboxId` names that sandbox, when your key can reach it. A sandbox that stops for good gives up its name. It keeps the name in its own record. To rename a sandbox, use `sbx.update({ name })`.

## Find sandboxes again

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

const runtime = new Runtime();
const page = await runtime.sandboxes.list({ labels: { team: "search" }, state: ["running"] });
for await (const sbx of page) console.log(sbx.id, sbx.info.name, sbx.state);
```

Every list in every product returns a page. `page.data` holds the items. `page.hasMore` says whether more pages exist. `await page.next()` gets the next page. `await page.toArray()` returns all items. `for await` walks every item on every page. Filter by `name`, `labels` and `state`. A stopped sandbox, whose disk is kept, is listed with the live ones. A sandbox whose disk is gone is listed only when you pass `includeStopped: true`.

`await runtime.sandboxes.stopAll({ labels: { team: "search" } })` stops every live sandbox that has all those labels. It stops eight at a time. It returns `{ stopped, failed }`. One failure does not stop the rest. The call needs at least one label. `await runtime.sandboxes.deleteAll({ labels: { team: "search" } })` deletes for good every sandbox with all those labels. Stopped sandboxes are deleted too. It works the same way, and returns `{ deleted, failed }`.

## Delete a sandbox

`await sbx.delete()`, or `runtime.sandboxes.delete(id)` without reading the sandbox first, removes a sandbox for good. It works in any state. It stops the sandbox. It deletes the sandbox's disk and paused memory. It revokes its previews and ports, frees its name, and removes it from every list. Its snapshots, usage and audit entries stay. Deleting it again returns the same `{ id, status: "deleted", deletedAt }`. Any other call to it then fails with `not_found`. Use `stop()` when you may want a persistent sandbox's disk back.

## Errors and retries

Every failure is a typed error. It has a `code`, a `message`, a `hint` that says what to do, and a `requestId` to quote to support.

```ts
import { NotFoundError, RuntimeError, Sandbox } from "withruntime";

try {
  await Sandbox.connect("00000000-0000-4000-8000-000000000000");
} catch (error) {
  if (error instanceof NotFoundError) console.log("no such sandbox");
  else if (error instanceof RuntimeError) console.log(error.code, error.hint, error.requestId);
  else throw error;
}
```

| Class                     | When                                                                                           |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `AuthenticationError`     | 401: the key is missing, wrong or revoked                                                      |
| `PermissionDeniedError`   | 403: the key or account may not do this                                                        |
| `NotFoundError`           | 404: no such resource in this account                                                          |
| `ConflictError`           | 409: the wrong state, or a count you hold at its limit; change it first                        |
| `InvalidRequestError`     | 400 and 422: `details` names every wrong field                                                 |
| `RateLimitError`          | 429: your own limit that clears over time (rate, concurrent work, a daily cap); `retryAfterMs` |
| `ServiceUnavailableError` | 5xx: capacity or a dependency; `retryable` says whether to send it again                       |
| `AccountBlockedError`     | 402 `account_blocked`: a payment is disputed or in review (from 0.7.0)                         |
| `ConnectionError`         | No answer at all                                                                               |
| `CommandError`            | `check: true` and the command did not exit 0                                                   |

Every write carries an idempotency key. The SDK makes it for you. Timeouts, dropped connections and every response that says `retryable: true` are retried. They are retried with the same key, after its `Retry-After`. So a retried create never makes two sandboxes, and a retried command never runs twice. A wait over 60 seconds is not slept on. The error is returned immediately, with `retryAfterMs`. An attempt whose response has not started after 125 seconds is sent again the same way. The API starts every response within 120 seconds. So the server it was sent to is gone. This happens, for example, when the controller fails over mid-call. A response that ran nothing (`guest_busy`, `busy`, `rate_limited`) is sent again. It is retried until the call's deadline. Without a deadline, it is retried for five minutes, past `maxRetries`. For methods that accept it, pass your own `idempotencyKey`. Then a retry is safe across process restarts. A transport timeout or connection error on a mutation carries `error.idempotencyKey`. That includes the key the SDK generated. Reuse it with identical input only on methods that accept a caller key. `process.write` protects each input chunk with its offset and an SDK request key instead. It refuses a caller key. Interrupted complete response bodies are retried with the same key. Streamed output is never replayed after it reaches your code.

`timeoutMs` covers credential lookup, waiting for a local connection, sending, reading the response and automatic retries. `timeoutMs: 0` turns off that deadline. An `AbortSignal` you pass still cancels the call.

**A create, wake or restart waits for room.** Suppose all four slots without credit are taken (`no_credit_running_limit`). Or the account is at its limit (`quota_exceeded`). Or the region is full (`no_capacity`). Then `sandboxes.create` waits. It sends the same request again, for up to two minutes. A burst of CI jobs past the limit queues instead of failing. A sandbox's `wake` and `restart` wait the same way when their own server is full (`no_capacity`). A sandbox stays on its server. So the wake is sent again with the same idempotency key until room frees up. A fork waits the same way when no server has room for a copy, and takes the same `waitForCapacityMs` option.

- When the wait runs out, the refusal is thrown as it came.
- The wait is added to `timeoutMs`. It is not taken from it.
- Set `waitForCapacityMs` on the client, or on one create, wake or restart. `0` fails immediately, as in `await sbx.wake({ waitForCapacityMs: 0 })`.
- From withruntime 0.7.0, `onCapacityWait(refusal, waitMs)` on one create is called before each wait. It tells a person why nothing has happened yet. The CLI prints the refusal once on standard error.

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

// A CI job that may queue for ten minutes behind the others.
const runtime = new Runtime({ waitForCapacityMs: 600_000 });
await using sbx = await runtime.sandboxes.create();
// One create that should fail at once instead.
await using now = await runtime.sandboxes.create({}, { waitForCapacityMs: 0 });
// One that says why it is waiting (withruntime 0.7.0).
await using told = await runtime.sandboxes.create(
  {},
  { onCapacityWait: (refusal) => console.error(`${refusal.message} Waiting.`) },
);
```

## Read-only keys and daily limits

An owner, admin or developer can make a read-only key, for monitoring and CI. They can also set a daily spending limit on a key that spends. Do both at [API keys](https://withruntime.com/account/keys). A key can read both settings. It cannot change either. `runtime.limits` needs withruntime 0.3.1 or later:

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

const runtime = new Runtime();
const { access, daily } = await runtime.limits.get();
console.log(access); // "full", "read" or "selected"
if (daily.remainingMicros !== null && BigInt(daily.remainingMicros) < 1_000_000n)
  console.log("less than $1 left in this 24-hour window");
```

Past the limit, a create, wake, extension or renewal fails. It throws a `RuntimeError` whose `code` is `spending_limit_reached` (HTTP 402). It is not retried. Stop and tell the person you work for. A read-only key that asks to change anything gets `PermissionDeniedError`. See [security](./security).

## Secrets your sandboxes never see

Store an API key once with `runtime.secrets`. Name the hosts it may go to. Every sandbox in the account then has an environment variable. The variable has the secret's name, or the name set by `env`. It holds a placeholder. The host's proxy swaps in the real value on HTTPS requests to those hosts. The value is sealed and never returned:

```ts check
import { Runtime } from "withruntime";
const runtime = new Runtime();
await runtime.secrets.set("GITHUB_TOKEN", {
  value: process.env.GITHUB_TOKEN ?? "",
  hosts: ["api.github.com"],
  header: "Authorization",
  format: "token {value}",
  rules: [{ methods: ["GET", "HEAD"], paths: ["/repos/acme/*"] }],
});
for (const secret of await runtime.secrets.list()) console.log(secret.name, secret.hosts);
const page = await runtime.secrets.list({ limit: 10, after: "GITHUB_TOKEN" }); // one page, by name
await runtime.secrets.delete("GITHUB_TOKEN");
```

With `header`, the proxy sets that header on every request to the hosts. `format` places the value in the header. With `rules`, on accounts with credit, only the requests a rule allows carry the value. A rule matches by method and path. A path is exact, or it ends in `/*`. Replacing a secret keeps its placeholder, so running sandboxes use the new value. See [security](./security#secrets-sandboxes-never-see) for the limits and for what is never rewritten.

With `env: "GITHUB_TOKEN"`, sandboxes see the placeholder in that variable. They do not see the secret's name. So secrets scoped with `only` to different sandboxes can share one variable. One example is a `GITHUB_TOKEN` for each repository. A store that would give one sandbox two of them is refused.

```ts check
import { Sandbox } from "withruntime";
await using sbx = await Sandbox.create({ secrets: ["ANTHROPIC_API_KEY"] });
console.log(sbx.info.secrets);
```

`secrets` limits a sandbox to the egress secrets you name. Only secrets that would otherwise reach it are counted. `[]` means none. Leaving it out means every one. The list is fixed for the sandbox's life. A `fork()` or a copy of a snapshot may only narrow it.

## Custom images

Build an image once with your dependencies. Then start every sandbox from it. Give exactly one source. It can be a `recipe` of packages. It can be an `image`, such as `python:3.12-slim`. Private registries work too. Or it can be a `dockerfile` with `contextDir`. That folder is the one `docker build` would read. Multi-stage builds, `COPY --from`, `ARG`, heredocs and `.dockerignore` all work. See [custom images](./images) for everything a build can do.

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

const runtime = new Runtime();
const image = await runtime.images.build(
  { name: "data", recipe: { pip: ["pandas"], apt: ["jq"] } },
  { onLog: (line) => console.log(line.text) },
);
await using sbx = await runtime.sandboxes.create({ image: "data" });
console.log(
  image.version,
  (await sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'")).stdout,
);
```

`build` streams the log to `onLog`. It waits until the image is ready. If the build fails, it throws the build's own error. `images.create` queues the build and returns immediately. Each build of a `name` becomes its next version. It takes the tag `latest`, or the `tags` you give. `image` on a create takes an id, `name`, `name:tag` or `name@version`. `start` sets what a sandbox from the image runs. It also sets when the create returns (`readyPort` or `readyCommand`). A Dockerfile's `CMD` and `HEALTHCHECK` fill it in.

`images.list()`, `images.versions(name)`, `images.resolve(ref)`, `images.tag(ref, tag)`, `images.untag(ref, tag)`, `images.logs(id)`, `images.followLogs(id, onLog)` and `images.delete(ref)` do the rest. `images.registries.set({ registry, username, password })` stores credentials for private images. A rebuild starts from the steps an earlier build shares. A stored image is charged on its whole file. This holds until copied-image accounting has been qualified and enabled. Where it is enabled, a verified identical copy in your account on the same server adds only its extra storage. The shared base and each verified extra allocation count once. They count while a ready copy still holds them. An extra allocation transfers only to proven descendants of the copy that added it ([pricing](./pricing#snapshots-images-and-volumes)). Building an image is not charged.

A new build leaves running sandboxes alone. `sbx.switchImage("data:v2")` moves a sandbox to the new build. It keeps the sandbox's id, `/workspace` (its home), volumes, environment and previews. Its processes restart. The rest of its old disk is lost. So snapshot it first to keep everything. A switch that fails is undone (`switch_undone`). See [move a sandbox to a new version](./images#move-a-sandbox-to-a-new-version).

## Volumes

A volume is a disk that outlives its sandboxes. Attach it read-write to one sandbox at a time. Or attach it as a read-only `snapshot` copy to any number of sandboxes.

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

const runtime = new Runtime();
const volume = await runtime.volumes.create({ sizeMiB: 10_240, name: "cache" });
await using sbx = await runtime.sandboxes.create({
  volumes: [{ volumeId: volume.id, path: "/data" }],
});
await sbx.exec("sudo chown runtime /data && echo kept > /data/note.txt");
```

A volume lives on one server. A sandbox that uses it is placed on that server. Runtime backs it up off that server every day, and whenever you ask. A backup restores as a new volume ([storage and backups](./storage)). The volume is charged on its full size from the moment it is created. This holds whether or not it is written ([pricing](./pricing#snapshots-images-and-volumes)). Stopping a sandbox first writes out what it wrote to its volumes. A time limit or credit that runs out does the same. The sandbox's programs are frozen just before its end. The write after that is not charged.

`sbx.mounts.add({ provider, bucket, path, secret })` mounts your own S3, R2 or Google Cloud Storage bucket as a directory. `sbx.mounts.list()` shows mounts. `sbx.mounts.remove(path)` ends a mount. The sandbox never holds the bucket's key ([mount your own bucket](./storage#mount-your-own-bucket)).

## Snapshots and forks

A fork is a copy of a sandbox as it is now. It has the same files, memory and running processes. It becomes a new sandbox of its own. Prepare a machine once. Then try several things from exactly that point.

```ts check
import { Runtime, Sandbox } from "withruntime";

const runtime = new Runtime();
await using base = await Sandbox.create();
await base.exec("pip install --quiet requests");
const [a, b] = await base.fork({ count: 2 }); // both running, answered together
await Promise.all([a!.stop(), b!.stop()]);

// Or keep the machine to start copies from later:
const snapshot = await base.snapshot({ name: "with-requests", retentionDays: 7 });
await using later = await runtime.sandboxes.create({ snapshot: snapshot.id });
await runtime.snapshots.delete(snapshot.id);
```

A running sandbox is paused while a snapshot or fork captures it. It is woken before the call returns. A bigger snapshot takes longer, the more memory it holds. A paused sandbox stays paused. Copies get the source's vCPUs, memory, disk and CPU. That covers reserved CPU, or a raised floor. Copies are billed as a create with those settings would be. They run on its host. A snapshot is kept on that host. It is copied off the host, encrypted, after its final compressed form is ready. It survives loss of the server once `backedUp` is `true`. That means the off-host copy has been checked ([storage and backups](./storage)). A sandbox with volumes cannot be snapshotted.

Snapshots default to `mode: "memory"`. That mode keeps files, memory and running processes. `await base.snapshot({ mode: "disk" })` keeps only the root filesystem. Each sandbox created from it boots fresh, without the saved processes. You set the `vcpu`, `memoryMiB` and `diskMiB` for each one. The disk must be at least the saved size. A copy of a memory snapshot is always the snapshot's size. Both modes pause a running source until capture finishes. Then they wake it. A source that was already paused stays paused. For a disk snapshot, the pause first waits for the sandbox to write out what it holds in memory. This takes a few seconds at most.

Where deferred compression has been qualified and enabled, a memory snapshot can be `ready` with `compressionPending: true`. Such a snapshot can start copies on the same server from the captured raw state. Runtime compresses it in the background. Billing uses its final verified compressed allocation. Temporary raw files are not charged. The off-server copy waits for that final form. So `backedUp` stays false while compression is pending. See [snapshot storage](./storage#snapshots-survive-their-server).

If a snapshot was captured but waking its source fails, the error keeps the original failure. It also includes `details.snapshotId`, `details.sourceSandboxId` and `details.sourceWakeError`. Read that saved snapshot. Wake the source explicitly before taking another capture. A failed recovery does not erase the snapshot id.

Copies run on what the account's new sandboxes run on, as `create` does. `funding` is accepted and ignored. On an account without credit, a copy must fit the limits without credit. So a sandbox with reserved CPU, or a floor above 250, forks only once the account holds credit.

The snapshot a fork takes is deleted when the fork ends. This happens whether or not every copy started. Nothing is billed for it. Pass `keepSnapshot: true` to keep it. You can then start more copies later. The kept snapshot is billed as snapshot storage.

- **A copy fails:** the error's `details.startedSandboxIds` names the copies that did start. They keep running, and billing, until you stop them.
- **Retrying:** a failed fork is over. A retry with the same idempotency key returns the same error. So fork again with a new key.
- **A fork stops partway,** for instance because our server restarted. A source the fork paused stays paused. It is not woken when nobody asked. An account notice (`GET /v1/notices`) names the sandbox and the fork. It says nothing was charged for the fork's snapshot. It also says how to wake the sandbox.

A snapshot is kept as long as you have credit. It has no end date. Without credit, it is kept for 7 days. Or it is kept for `retentionDays`, which can be 1 to 365. Delete it sooner with `runtime.snapshots.delete`.

## Code interpreter

A notebook-style session runs in the sandbox. It supports Python, JavaScript, TypeScript, R, Java, Bash and Go. Variables persist between runs. Go keeps its functions, types and imports. It runs each cell as a program. matplotlib charts and R plots come back as PNG. pandas and R data frames, and arrays of objects, come back as tables. In any language, `display` returns a file (.png, .svg, .html, .csv...) as a result.

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.interpreter.run("import math\nx = math.pi");
const cell = await sbx.interpreter.run("round(x * 2, 3)");
console.log(cell.results[0]?.data["text/plain"]); // 6.283

const ts = await sbx.interpreter.run("const n: number = 21; n * 2", { language: "typescript" });
const r = await sbx.interpreter.run("summary(c(1, 2, 3))", { language: "r" });
```

Python, JavaScript, TypeScript and Bash are in the default image. R, Java and Go are installed from Ubuntu's archive. That happens the first time a context uses them. On 23 September 2026, this took about 35 seconds for Java or Go, and 90 seconds for R. It happens once per sandbox. To skip it, bake them into an image with `apt`.

## Network rules

`sbx.network.get()`, `sbx.network.set({ internet, allow, deny, connect })`, `sbx.network.off()` and `sbx.network.on()`. See [the sandbox environment](./sandbox-environment) for what each rule does.

## Share a port

A preview gives one port of a sandbox an HTTPS address. It is private by default. A request needs the token. Send the token in the `x-runtime-preview-token` header. Or use the `urlWithToken` link, which carries the token. That link works as it is in a browser, `fetch`, `curl` or a WebSocket client. It works until the token expires. A browser keeps the token for the site, and drops it from the address bar. This also applies inside an iframe on your own site. WebSockets work.

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.spawn("python3 -m http.server 3000");
const preview = await sbx.previews.create(3000);
const page = await fetch(preview.url, {
  headers: { "x-runtime-preview-token": preview.token! },
});
console.log(page.status);
```

Pass `{ visibility: "public" }` for an address anyone can open. Only paid sandboxes can do this. A sandbox without credit's previews stay private. `previews.rotate(port)` refuses every token issued so far. `previews.delete(port)` stops sharing.

- **When a change applies:** sharing, rotating, deleting, and switching between public and private take effect when the call returns. The next request with an old token is refused. Runtime also closes any WebSocket opened with one.
- **Which sites may embed it:** `embedOrigins: ["https://app.example.com"]` holds the preview to those sites. You can list up to 16 sites. Use `https://*.example.com` for subdomains. Any other site's iframe is refused. The link's token works in an iframe only on the listed sites. If you leave it out, a shared port keeps its list. `[]` allows any site again. That is the default.
- **Token lifetime:** a token lasts a day by default. `ttlSeconds` sets the lifetime, from 60 seconds to 7 days. A token lasts at least that long. It lasts at most one step longer. A step is an hour, or a 24th of a shorter lifetime. So reads within a step return the same token. A browser's cookie from the link lasts exactly as long as its token.
- **Absolute token deadline:** pass `expiresAt` as a timezone-qualified ISO timestamp in `create`. Or pass it in `previews.get(port, undefined, { expiresAt })`. It must be between a minute and a week ahead. It rounds down to a whole second. If you pass both fields, the earlier deadline wins. A session's expiry also limits its preview reads. Use the returned `tokenExpiresAt` as the actual deadline. This requires the server's matching absolute-deadline support. An older server refuses the field. It does not substitute a relative lifetime.
- **When nothing is listening on the port:** the preview returns 502 with the `x-runtime-preview-error: port_closed` header. Within 60 seconds after the sandbox is created or wakes, a request to a port that is not listening yet waits up to 10 seconds for your server to start, and is forwarded as soon as the port opens. A port that is already listening is not delayed. The same applies to TCP ports.
- **When the sandbox is not running:** a paused or waking sandbox's preview returns 503 with `Retry-After` while it wakes. A stopped sandbox's preview returns 404. A deleted or failed sandbox's preview returns 410. Neither of the last two has `Retry-After`. A preview's address is under `runtimehost.com`. That is the domain for everything sandboxes serve. It is kept apart from Runtime's own site.

## A sandbox from a browser

A session lets your own frontend reach one sandbox directly. Calls do not pass through your servers, and the browser holds no key. Your backend creates the session with its key. It then gives the page the token:

```ts no-run
// On your server, with RUNTIME_API_KEY.
import { Sandbox } from "withruntime";

export async function sessionFor(sandboxId: string) {
  const sbx = await Sandbox.connect(sandboxId);
  const session = await sbx.sessions.create({
    origins: ["https://app.example.com"],
    ttlSeconds: 900,
  });
  return { token: session.token, sandboxId: session.sandboxId };
}
```

```ts no-run
// In the page, with what your server returned.
import { Sandbox } from "withruntime";

const { token, sandboxId } = (await (await fetch("/api/sandbox-session")).json()) as {
  token: string;
  sandboxId: string;
};
const sbx = Sandbox.fromSession({ token, sandboxId });
const { stdout } = await sbx.exec("ls /workspace");
await sbx.files.write("/workspace/notes.txt", "from the browser");
console.log(stdout);
```

- **What it can do:** run commands and read their output as it streams. It can start and drive processes, read, write and watch files, and run the code interpreter. It can also read the sandbox's previews with their tokens.
- **What it cannot:** stop, pause, extend, fork, snapshot or change the sandbox. It cannot create anything. It cannot reach another sandbox, keys, billing or secrets. Those calls return `403 forbidden`.
- **How long:** 1 hour, unless `ttlSeconds` asks otherwise. Never more than 24 hours. `sbx.sessions.revoke(id)` ends one immediately. Revoking the key that made a session ends all of that key's sessions. `sbx.sessions.list()` shows them.
- **Which pages:** `origins` lists up to 10 exact origins, such as `https://host`. While you develop, use `http://localhost:5173`. The API allows CORS for those origins alone. It refuses a request from any other page.
- **Who can make one:** a key that can run commands in the sandbox. The session acts as that key's agent, so it can never do more than the key.
- **Money:** a session spends only what the sandbox already spends. A paused sandbox wakes for its commands only if the sandbox wakes on requests (`autoWake`, on by default). It wakes with the time limit it had, if any.
- **Terminals:** a session has no WebSocket terminal. Start a process with `spawn(command, { pty: {}, stdin: "pipe" })`, write to it and follow its output.

The token appears in the response to `create` only. Keep it out of logs and URLs.

## A desktop

A Linux desktop runs in the sandbox. You drive it as a person would. Open a page, click, type, press keys, take screenshots, and watch it live.

```ts check
import { writeFile } from "node:fs/promises";
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
const { streamUrl } = await sbx.desktop.start({ width: 1280, height: 800 });
console.log("watch it:", streamUrl);
await sbx.desktop.open("https://example.com");
await sbx.desktop.click(640, 400);
await sbx.desktop.type("hello");
await writeFile("screen.png", await sbx.desktop.screenshot());
```

The live view is a private preview of the desktop. `streamUrl` carries its token, so anyone holding it can watch. Open it in a browser, and keep it to yourself.

The desktop and Chromium are ready on every server. The first start in a sandbox installs nothing on its disk. It takes about a second.

Record the screen to MP4:

```ts check
import { writeFile } from "node:fs/promises";
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.desktop.start();
const rec = await sbx.desktop.recordings.start({ fps: 10, maxMiB: 256 });
await sbx.desktop.open("https://example.com");
await sbx.desktop.recordings.stop(rec.id);
await writeFile("demo.mp4", await sbx.desktop.recordings.download(rec.id));
```

A recording uses one encoder thread, at low priority, and at most 4 Mbit/s. So the desktop and your programs come first. A recording file never grows past `maxMiB`. Recording stops before the sandbox's disk fills. A sandbox keeps at most 8 GiB of recordings. Recordings are files on the sandbox's own disk. They count toward its disk. Nothing is stored or charged apart from that.

A recording started before the desktop is running is refused immediately with 409 `desktop_not_running`. Nothing is installed or written.

## A browser over CDP

`sbx.browser.start()` runs Chromium in the sandbox. It returns `cdpUrl`, the address that Playwright, Puppeteer, browser-use and Stagehand connect to. The browser runs in the sandbox, so its traffic follows the sandbox's network rules.

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create({ memoryMiB: 2048 });
const { cdpUrl, version } = await sbx.browser.start();
console.log(version, cdpUrl);
```

Give a browser 2 GiB. Chromium takes what the sandbox has, and heavy apps need that memory. We measured 100 visits to ten heavy pages. The pages ranged from news sites to Google Sheets, YouTube and StackBlitz. None crashed at 2 GiB. At 1.5 GiB, 20 visits crashed for memory. At 1 GiB, 56 crashed. These results were measured on 6 October 2026. 1 GiB suits light pages and scraping. It costs half the memory charge. Under 2 GiB, `start` returns a `hint` that says so. The hint sits beside `memoryMiB`, the sandbox's size. The browser starts either way.

Pass `cdpUrl` to the tool as it is. Use `chromium.connectOverCDP(cdpUrl)` in Playwright. Use `puppeteer.connect({ browserWSEndpoint: cdpUrl })` in Puppeteer.

`cdpUrl` is private. It carries a token that lasts a day. `sbx.browser.get()` returns a fresh one. Anyone holding it can drive the browser, so keep it to yourself. Code inside the sandbox finds the same browser at `http://127.0.0.1:9222`. `start({ headless: false })` shows the browser on the sandbox's [desktop](#a-desktop). It also returns the live view as `streamUrl`. `sbx.browser.stop()` ends the browser. After that, `get()` returns `running: false`. The browser comes from the host as a read-only disk. So a start in a new sandbox takes about 1 to 2 seconds, and installs nothing. A sandbox from a custom image that is not Ubuntu 24.04 x86_64 installs Chromium on its first start. That takes about a minute, once. `start` waits for the install. Called directly, the API returns 409 `browser_installing` until the install is done. Call again after `retryAfterMs`. A browser that cannot start or install returns 409 `browser_failed`. The error carries the sandbox's own words.

The CLI is `runtime sandboxes browser <id> start`, and agents use the MCP tool `runtime_sandboxes_browser`.

### Spare browsers, paused

For many short tasks, such as fetching one page each, keep spare browsers paused. A paused sandbox is charged only for its storage. It wakes on the next request, with Chromium as it was:

```ts check
import { Sandbox } from "withruntime";

const spare = await Sandbox.create({ vcpu: 1, memoryMiB: 1024 });
const { cdpUrl } = await spare.browser.start();
await spare.pause(); // ready for the next page

await spare.wake(); // about 0.1 s
// connect to cdpUrl, open a new browser context, fetch the page, close it
await spare.pause();
```

Open each page in its own browser context. In Playwright, that is `browser.newContext()`. So no cookie or storage passes from one page to the next. On 18 October 2026, we measured from a client outside Runtime. A woken spare had one page loaded, its screenshot taken and its HTML read. That took 0.56 to 0.81 seconds after the wake was asked for.

Wikipedia, BBC News and a GitHub repository page each peaked between 194 and 331 MiB. So 1 GiB is enough for fetching pages like these.

## MCP servers in a sandbox

Runtime does not run catalog MCP servers for you. To run an MCP server in a sandbox, start it as a process and share its port with a [preview](#share-a-port). The server must serve MCP over Streamable HTTP. Your agent then connects to the preview URL, at the path your server serves MCP on (often `/mcp`), and sends the preview token in the `x-runtime-preview-token` header.

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

const sbx = await Sandbox.create();
await sbx.spawn("python3 server.py --port 8000", { cwd: "/workspace/my-mcp" });
const preview = await sbx.previews.create(8000);
console.log(preview.url, preview.token); // the address and the token to send
```

The server runs as the sandbox's user, behind the sandbox's network rules. It can use [secrets the sandbox never sees](./security#secrets-sandboxes-never-see).

## Domains, TCP ports, addresses, the tunnel and your own proxy

Paid accounts only. See [networking](./networking).

```ts check
import { Runtime } from "withruntime";
const runtime = new Runtime();
const sbx = await runtime.sandboxes.create();
const domain = await runtime.domains.add({
  hostname: "app.example.com",
  sandboxId: sbx.id,
  port: 3000,
});
console.log(domain.records); // the TXT and CNAME to set; then runtime.domains.verify("app.example.com")
const db = await runtime.ports.open({ sandboxId: sbx.id, port: 5432 });
console.log(db.connect); // "203.0.113.10:23456"
const ip = await runtime.ips.reserve(); // ip.address
await runtime.networks.wireguard.create();
const office = await runtime.networks.wireguard.addPeer({
  name: "office",
  routes: ["10.0.0.0/16"],
});
console.log(office.config); // a wg-quick file
await runtime.networks.upstreamProxy.set({
  url: "http://proxy.example.com:3128",
  secret: "PROXY_AUTH",
});
```

`runtime.networks.upstreamProxy` sends every sandbox's outbound connections through your own proxy. It is available from `withruntime` 0.12.0. From 0.7.0, it is `runtime.network.upstreamProxy`. `get()` reads the proxy setting. `remove()` removes it. See [your own proxy](./security#your-own-proxy).

## Metrics and webhooks

```ts check
import { Runtime, Sandbox, verifyWebhook } from "withruntime";

const sbx = await Sandbox.create();
const { latest } = await sbx.metrics({ range: "15m" }); // CPU and memory, measured

const runtime = new Runtime();
const hook = await runtime.webhooks.create({ url: "https://example.com/hooks/runtime" });
// In the endpoint: await verifyWebhook(rawBody, request.headers.get("runtime-signature"), hook.secret!)
console.log(latest?.cpuPercent, typeof verifyWebhook);
```

`runtime.events.list()` reads lifecycle events. `runtime.otel.create()` pushes events and metrics to an OpenTelemetry endpoint. See [metrics and webhooks](./observability).

## Account API calls

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

const runtime = new Runtime();
const counts = await runtime.usageRequests("7d");
console.log(counts.calls, counts.errorPercent);
for (const row of counts.operations) console.log(row.operation, row.serverErrors);
```

`usageRequests()` defaults to `"24h"`. `"7d"`, `"30d"` and `"90d"` select longer windows. Counts are exact decimal strings. `errorPercent` is null when no calls were counted. A key needs the `usage` scope. It also needs read-only access or all-products access. See [account API calls](./observability#account-api-calls).

### Export settled usage

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

const runtime = new Runtime();
let cursor: string | undefined;
do {
  const page = await runtime.usageExport({
    since: "2026-09-01T00:00:00Z",
    until: "2026-10-01T00:00:00Z",
    ...(cursor ? { cursor } : {}),
  });
  process.stdout.write(page.csv);
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

The range includes settlements at `since`. It excludes settlements at `until`. Pending holds are excluded. Rows cover every visible product, with exact amount strings. Concatenate each server CSV page unchanged. The header appears only on the first page. Each page checks current permissions and reads current settlements. `page.finalThrough` is the time before which no more charges will settle. The range is final once it reaches `until`. A row's `final` is true once its resource is deleted and can be charged nothing more. See [export settled usage](./api#export-settled-usage).

## Identity tokens

Inside a sandbox, `Sandbox.identityToken({ audience })` returns a short-lived OIDC token. The token names the sandbox. Use it to trade for AWS or Google Cloud credentials, without a stored key. It needs no API key. `runtime.sso.get()` reads the account's single sign-on. See [identity tokens](./identity-tokens) and [single sign-on](./single-sign-on).

## Feedback and support

`runtime.feedback.submit(...)` tells the team what broke or is missing. `runtime.support.message(...)` asks for help. See [feedback and support](./feedback-and-support).

## Coming from E2B, Daytona, Vercel Sandbox or Blaxel

After you change the import, their supported sandbox calls keep the same call shapes on Runtime. The versions are `withruntime` 0.4.0 or later for E2B. They are 0.5.0 or later for Daytona and Vercel Sandbox. They are 0.8.0 or later for Blaxel:

```ts no-run
import { Sandbox } from "withruntime/e2b"; // was: from "e2b"
import { Daytona } from "withruntime/daytona"; // was: from "@daytona/sdk"
import { Sandbox as VercelSandbox } from "withruntime/vercel"; // was: from "@vercel/sandbox"
import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"
import { MorphCloudClient } from "withruntime/morph"; // was: from "morphcloud"
import { ModalClient } from "withruntime/modal"; // was: from "modal"
```

Sandboxes get the old provider's defaults. If Runtime cannot honor a call the same way, the call throws `NotSupportedError`. It does this before anything happens. The error names what to use instead. `E2B.md`, `DAYTONA.md`, `VERCEL.md` and `BLAXEL.md` in the package list every mapping and gap. To move to Runtime's own calls, see [migration](./migrate).

To run a Worker written for Cloudflare's Sandbox SDK (0.x), change its import to `withruntime/cloudflare`. Delete the `containers` block from its Wrangler config. Add a `RUNTIME_API_KEY` secret. See [change the import](./cloudflare-sandbox-alternative#change-the-import).

To run code that calls Fly's Machines API, change only its address, to `npx withruntime fly-api`. A Node service can answer the same calls itself. It uses `machinesApi()` from `withruntime/fly`. See [migration](./migrate).

## Configuration

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

const runtime = new Runtime({
  apiKey: process.env.RUNTIME_API_KEY, // the default
  maxRetries: 4,
  timeoutMs: 120_000,
});
console.log((await runtime.me()).orgId);
```

`RUNTIME_API_URL` points the client at another API origin. Code inside a Runtime sandbox calls Runtime's API at `http://runtime.internal`. See [Runtime's API from inside a sandbox](./sandbox-environment#runtime-s-api-from-inside-a-sandbox). Connections are kept alive and reused across calls. A client holds at most 48 connections at once (`maxConnections`). That count includes calls and streams, such as a command's output. The client keeps 8 of them for calls. Past that limit, calls and streams wait their turn instead of failing. One address may hold 64 connections to the API until it has used a valid key. After that, it may hold more. See [limits](./api#limits).

Before 0.3.0, the package was `@withruntime/cloud`. That name, and `runtime-cloud` and `withruntime-cloud`, stopped at 0.5.1. They get no new releases. Install `withruntime` for everything since.


---

<!-- https://withruntime.com/docs/jobs -->

# Scheduled jobs

A job runs a command in a fresh sandbox. It runs once, at a time you choose, or on a cron schedule. It keeps each run's exit code and output. Use a job for a nightly report, an hourly cleanup, or one task that should start at 3 AM. You need no machine of your own waiting to start it.

```bash no-run
runtime jobs create nightly-report --cron "0 3 * * *" --timezone Europe/Berlin \
  -- python3 /workspace/report.py          # prints the job id
runtime jobs create hello --at now -- bash -lc 'echo hello from a job'
runtime jobs ls                              # state, schedule, next run
runtime jobs logs "${job}" -f                # its latest run's output, followed
```

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

const runtime = new Runtime();
const job = await runtime.jobs.create({
  name: "nightly-report",
  schedule: { cron: "0 3 * * *", timezone: "Europe/Berlin" },
  command: ["python3", "/workspace/report.py"],
});
for await (const run of await runtime.jobs.runs(job.id))
  console.log(run.id, run.state, run.exitCode);
```

```python check
from withruntime import Runtime

runtime = Runtime()
job = runtime.jobs.create("nightly-report", cron="0 3 * * *", timezone="Europe/Berlin",
                          command=["python3", "/workspace/report.py"])
for run in runtime.jobs.runs(job["id"]):
    print(run["id"], run["state"], run["exitCode"])
```

Agents use the `runtime_jobs` MCP tool. Set `action` to `create`, `list`, `get`, `runs`, `run`, `logs`, `pause`, `resume`, `trigger`, `reschedule`, `update` or `cancel`.

Every job also appears on the [Jobs page](https://withruntime.com/account/jobs) of your account. The page shows the job's schedule, size, last and next run. It shows each run's exit code, length, cost and output. It has buttons to run the job now, change its schedule, pause it, resume it or cancel it.

## What a run is

Every run starts a new sandbox, runs the command in it, and stops the sandbox. Nothing on the sandbox's own disk carries over to the next run. So a job that keeps data between runs either [attaches a volume](#keep-data-between-runs), or reads and writes somewhere else that lasts, such as your own bucket or database.

- **The command runs as given, without a shell.** Pass an argv list. For pipes, `&&` or variables, run it through bash: `-- bash -lc 'cd /workspace && make'`. A command can be at most 16 KiB. `cwd` must be under `/workspace`.
- **The size is the same as a sandbox's.** The default is 2 vCPU and 4 GiB of memory, with a 4 GiB disk, unless you set a different size. You can go up to 16 vCPUs and 64 GiB. An odd memory size in MiB is rounded up to the next even one. The disk is at least 3 GiB, the size of the system image. It can be at most 400 GiB.
- **A run may last up to 60 minutes.** The timeout is 30 minutes unless you set it. It counts from when the command starts. At the timeout, the run is stopped, along with every process it started. The run ends `failed` with the reason `timeout`. A timeout as long as the run's paid time (`durationSeconds`) falls 15 seconds before that time ends. So the run's exit and output are kept, and a retry you set still runs.
- **It can prove which sandbox it is.** The command's environment has `RUNTIME_ID_TOKEN_REQUEST_URL` and `RUNTIME_ID_TOKEN_REQUEST_TOKEN`, as in any sandbox. So `Sandbox.identityToken()` (`identity_token()` in Python), or curl, gets an [identity token](./identity-tokens) for AWS, Google Cloud or your own API. No stored key is needed. The token names the run's sandbox.
- **Output is kept.** A run keeps its last 256 KiB of standard output and standard error, combined. `logsTruncated` is set when earlier output was dropped.
- **It starts from the standard image, or yours.** `--image` (`image` in the SDKs and API) takes an [image](./images) of your account. You can name it by id, by name (its `latest` tag), as `name:tag`, or as `name@version`. So a job's code and tools can sit in the image, not in its command. Like an App deploy, the name resolves to the image's id when the job is made. Moving a tag later changes no job. To move a job to a new version, run `runtime jobs update <id> --image <ref>`. The image must be ready, in the job's region, and fit its disk. An image that fails any of these is refused when the job is made, never at a run.

## Keep data between runs

A job attaches up to four existing [volumes](./storage#attaching-a-volume) to every run's sandbox. Each one attaches at a path, as a sandbox create does. Read-write is the default. It allows one sandbox at a time. So each run in turn gets the volume, and reads what the run before it wrote. `snapshot` is a read-only copy of the volume, taken as the run starts. Any number of sandboxes and runs can hold a snapshot at the same time.

```bash no-run
vol=$(runtime volumes create --size-mib 10240 --name state)   # the volume id
runtime jobs create count --cron "0 * * * *" --volume "${vol}":/data \
  -- bash -lc 'date >> /data/runs && wc -l < /data/runs'
```

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

const runtime = new Runtime();
const volume = await runtime.volumes.create({ sizeMiB: 10_240, name: "state" });
await runtime.jobs.create({
  name: "count",
  schedule: { cron: "0 * * * *" },
  command: ["bash", "-lc", "date >> /data/runs && wc -l < /data/runs"],
  compute: { region: volume.region, volumes: [{ volumeId: volume.id, path: "/data" }] },
});
```

```python check
from withruntime import Runtime

runtime = Runtime()
volume = runtime.volumes.create(10_240, name="state")
runtime.jobs.create("count", cron="0 * * * *",
                    command=["bash", "-lc", "date >> /data/runs && wc -l < /data/runs"],
                    compute={"region": volume["region"],
                             "volumes": [{"volumeId": volume["id"], "path": "/data"}]})
```

- **A run starts on its volume's server,** in the volume's region. Give the job that region (`compute.region`; the CLI takes it from the volume). A job in another region is refused when you create it.
- **What a run wrote is on the volume when the next run starts.** A run's sandbox writes its volumes out as it stops, even at its timeout. It keeps no disk of its own, so it releases the volumes then. The next run waits the few seconds that takes.
- **A volume held read-write by another sandbox holds the job.** Any other sandbox keeps its volume until that sandbox is deleted. This includes a sandbox that is running, paused or stopped ([a stop keeps the disk](./storage#what-is-kept-where)). To free the volume, delete that sandbox. The job waits with `blockedReason` `volume`. It starts within 30 seconds of the volume coming free. A `snapshot` attachment is never held.
- **The key that makes the job** is allowed to attach the volume. It needs `write_file` on the volume for read-write, or `read_file` for a snapshot. A sandbox create needs the same.
- **Update a job to change its volumes:** `runtime jobs update <id> --volume "${vol}":/data` (or `compute.volumes` in an update) replaces its whole list. `--no-volumes` removes them. The next run attaches them. Its history stays.
- **A volume is paid for as always,** by the GiB-hour while it exists. It is backed up every day ([backups](./storage#volume-backups)). Each run is paid for as any run is.

A run never starts in an existing sandbox, whether running, paused or stopped. Every run is a fresh sandbox. To keep a sandbox's whole disk, use a [persistent sandbox](./javascript#keep-a-sandbox-running) and run the command in it yourself. To keep data for a job, put it on a volume.

## Schedules

- **Once:** `--at` takes an ISO time with its offset, such as `2026-10-01T03:00:00Z`, or `now`. In the SDKs, `at` also takes a date or Unix milliseconds. A time already past runs immediately.
- **Recurring:** `--cron` takes the five cron fields: minute, hour, day of month, month and day of week. Each field is `*`, a number, a list, a range or a step. `*/15 * * * *` runs every fifteen minutes. `--timezone` takes an IANA name, such as `America/New_York`. It is UTC unless you set it. Set a time zone so a schedule follows daylight saving time where you are.
- **Missed times run once.** If runs were missed, for example while the service was down or while a run was still going, the job runs once for all of them. Then it keeps to its schedule.
- **One run at a time.** A job never has two runs going at the same time.

`runtime jobs pause <id>` stops new runs. `resume` starts them again. A run already going finishes. `runtime jobs cancel <id>` ends the job for good and stops a run in progress. A run that has already finished keeps its result. Cancelling a job twice changes nothing.

**Run it now.** `runtime jobs trigger <id>` (`jobs.trigger` in the SDKs) runs the job once, now, in a fresh sandbox. Its schedule stays as it was. A paused job runs once and stays paused. A job has one run at a time. While a run is starting or going, a trigger is refused with `run_in_progress`. A cancelled or finished job is refused with `invalid_state`. The run is listed with its others, with `trigger` `manual`. It is paid for as any run is.

**Change the schedule.** `runtime jobs reschedule <id> --cron "30 4 * * 1-5" --timezone Europe/Berlin`, or `--at` for one run (`jobs.reschedule(id, schedule)` in the SDKs), gives the job a new schedule. It keeps the job's id and its runs. The next run is at the new schedule's next time. A run already going finishes as it started. A paused job stays paused until you resume it. On the Jobs page, Change schedule needs no cron. Pick every hour, day, weekday, week or month, or pick once. Then pick a time zone. The page describes the schedule in words before you confirm. Choose Custom to enter a cron.

**Change a job.** `runtime jobs update <id>` (`jobs.update(id, changes)` in the SDKs, `PATCH /v1/jobs/{id}` in the API) changes a job in place. You can change its command (after `--`), image (`--image`, or `--standard-image` to go back), size, secrets, alert, timeout, retries or cost cap. Its id, its runs and its schedule stay. Change the schedule with `reschedule`. The name does not change. Fields you leave out stay as they are. `compute` and `retry` change only the fields you give. `secrets` replaces the whole list. A run already bought or going finishes with the command it started with. The next run uses the new job. A cancelled or finished job is refused with `invalid_state`.

```bash no-run
runtime jobs update "${job}" --image hub:latest --timeout 600 -- bash -lc 'bun run loop.ts'
```

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

const runtime = new Runtime();
await runtime.jobs.update("job-id", { image: "hub@8", compute: { memoryMiB: 2048 } });
```

```python check
from withruntime import Runtime

runtime = Runtime()
runtime.jobs.update("job-id", image="hub@8", compute={"memoryMiB": 2048})
```

## Failures and retries

A run that exits with a code other than 0 has failed. By default, a job tries once. `--attempts 3 --backoff 60` (in the SDKs, `retry: { maxAttempts, backoffSeconds }`) retries a failed run in a fresh sandbox. It makes up to 5 attempts per occurrence. It waits up to 60 minutes between them.

A run whose outcome Runtime could not see ends in state `unknown`. This happens when its sandbox stopped under it. Runtime never runs that occurrence again, even with retries set. The command may have done its work. Check what it did before you run it by hand. The schedule carries on. The next occurrence runs as usual.

If a run cannot start, the job's `blockedReason` says why. The job tries again every 30 seconds. The reasons are:

- `credits`: the account has no credit. Scheduled jobs run only on an account that holds credit, so add credit.
- `cost_cap`: a limit you set, or the key's daily limit, was reached.
- `capacity`: there is no room right now.
- `volume`: a volume it attaches was deleted, is not ready, or is attached read-write to another sandbox.
- `permission`: the key that made the job was revoked or narrowed, or the key may not use a volume it attaches.

## Alerts

A job can tell you when its runs fail. Then nothing has to poll its runs. Once `afterFailures` runs in a row end `failed`, timed out or `unknown`, one alert goes out. The default is 1, unless you set another number. While runs keep failing, no more alerts go out. Once a run succeeds again, one more alert says the job recovered. A run that will be retried counts when its last attempt ends. A run you cancel does not count.

```bash no-run
printf %s "$HOOK_SECRET" | runtime secrets set HOOK_SECRET --jobs
runtime jobs create loop --cron "*/5 * * * *" --image hub:latest \
  --alert-webhook https://example.com/runtime-alerts --alert-secret HOOK_SECRET --alert-after 3 \
  -- bash -lc 'bun run loop.ts'
runtime jobs update "${job}" --alert-email     # mail me instead
runtime jobs update "${job}" --no-alert        # tell no one
```

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

const runtime = new Runtime();
const hook = await runtime.secrets.set("HOOK_SECRET", { value: "…", jobs: true });
await runtime.jobs.create({
  name: "loop",
  schedule: { cron: "*/5 * * * *" },
  command: ["bash", "-lc", "bun run loop.ts"],
  alert: {
    afterFailures: 3,
    webhook: { url: "https://example.com/runtime-alerts", secretId: hook.jobs.id },
  },
});
```

- **A webhook** (`alert.webhook`) gets a POST. It takes `url` and `secretId`. The `url` is an https address on the public internet, named by a host name or an IPv4 address. The `secretId` is a secret stored with `--jobs`. The POST has the same body that an [account webhook](./observability#webhooks) gets for the same run. Its `type` is `job.run.failed` or `job.recovered`. It has `data.job`, and `data.run`, which holds the run's state, `reason` (such as `timeout`), exit code and times. It also has `data.logTail`, the run's last 20 lines of output. With a `secretId`, the POST is signed with that secret's value. Account webhooks are signed with their secrets the same way, in `Runtime-Signature`. So `verifyWebhook(body, header, value)` checks it. Without a `secretId`, the POST is sent unsigned. `Runtime-Webhook-Id` is the alert's id. It is the same on every attempt. A send that does not get a 2xx is tried again for about three days, as webhooks are. The key that sets the alert, and the job's key, must be allowed to reveal the secret as well as use it (`secrets_reveal`). A run's output is the job's to choose. So a key that can only use a secret in a run never gets that output signed with its real value. In a run, its sandbox sees a stand-in. If the secret is deleted, or the job's key may no longer use and reveal it, the alert stops. It is not sent unsigned.
- **An email** (`alert.email: true`) goes to the job's person. That is whoever made the job, or the person whose key made it. It goes only while they are an active member of the account. The email names the job, the run, its reason and exit code. It links to the run. It never carries the run's output. The job's page shows the output to anyone who may read it. Once that person is removed or suspended, the job's alerts are no longer mailed to them.
- **Your account's webhooks** receive every failing run as `job.run.failed`. They receive each recovery as `job.recovered`. This happens whether or not the job has an alert ([events](./observability#events)). The run's output is not included.

Only the job's own key, or another key of the same agent, can change a job. A new command, image, size or secret list then runs with the key that wrote it. That key must be allowed every secret the job binds, including an alert's `secretId`. It must also be allowed the job's image. A rule that stops the key's agent from starting sandboxes from an image also stops a job from being set to that image. It also stops each run of a job that already uses it.

A job shows `failingRuns`, the number of runs in a row that ended failing. It also shows `alertingSince` and `lastAlert`. `lastAlert` is its last alert and how its delivery went.

## What it costs

A run is paid for as any sandbox is. You pay for exactly the time it runs. The job itself costs nothing extra. The [free usage](./included-usage) applies first, then credit. You do not choose the order:

- **Without credit,** no run starts. A job waits until the account holds credit. Adding credit lets the job run.
- **Once the account holds credit,** a run uses the free usage while it lasts. Then it spends credit, at the sandbox rates: $0.025 per active vCPU-hour and $0.0075 per reserved GiB-hour. Before a paid run starts, it holds its cost for its time limit. It is charged only for what it used. The same [spending limits](./security) apply as for every sandbox.

A job on an account with no credit waits with `blockedReason` `credits`. It starts by itself once the account holds credit.

Two limits cap what a job spends. `--max-cost` caps one run. `--max-total-cost` caps every run of the job together. In the SDKs and API, they are `compute.maxCostMicros` and `maxTotalCostMicros`. An account holds up to 1,000 jobs, active or paused. A finished or cancelled job does not count. [Ask](./feedback-and-support) for more.

## Secrets in a job

A job puts secrets into its run's environment. Store the value once with `--jobs`. Then bind it by name when you create the job:

```bash no-run
printf %s "$DB_PASSWORD" | runtime secrets set DB_PASSWORD --jobs
runtime jobs create backup --cron "0 2 * * *" --secret DB_PASSWORD=PGPASSWORD \
  -- bash -lc 'pg_dump "$DATABASE_URL" | gzip > /workspace/backup.sql.gz'
```

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

const runtime = new Runtime();
const saved = await runtime.secrets.set("DB_PASSWORD", { value: "…", jobs: true });
await runtime.jobs.create({
  name: "backup",
  schedule: { cron: "0 2 * * *" },
  command: ["bash", "-lc", 'pg_dump "$DATABASE_URL" > /workspace/backup.sql'],
  secrets: [{ name: "PGPASSWORD", secretId: saved.jobs.id }],
});
```

The name in the run's environment is the secret's own name. Give another name after `=` to change it. Names that start with `RUNTIME_`, `LD_` or `PYTHON` are reserved. So are `PATH` and `HOME`. A job that binds a reserved name is refused with `env_name_reserved`. Bind the secret to another name instead, as `PGPASSWORD` does above.

One `runtime secrets` entry can hold both kinds of use. A secret can go to sandboxes, to jobs, or to both (`--host` and `--jobs` together). The two copies behave differently:

|                    | For sandboxes (`--host`)                                | For jobs (`--jobs`)                                                         |
| ------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------- |
| What the code sees | A placeholder; the egress proxy adds the value on HTTPS | The value itself, in the variable you name                                  |
| Size               | Up to 8 KiB of plain text              | Up to 64 KiB                                                   |
| How many           | Up to 50 per account                   | Up to 1,000 per account                                          |
| Read it back       | Never, by anyone                                        | `runtime secrets reveal NAME`, with a key allowed to reveal                 |
| Change it          | `set` again                                             | `runtime secrets rotate NAME`: a new version, the old one stops immediately |
| Belongs to         | The account                                             | The person whose key stored it                                              |
| Delete             | `runtime secrets rm NAME` deletes both copies           | The same; the name cannot be used again                                     |

A job takes up to 16 secrets. A run gets the value only while it is going. A secret that is rotated or deleted after a run started is refused to that run. The value is in the run's environment. So a command that prints it puts it in the job's logs.

A jobs secret stored by an API key belongs to that key. Your other keys cannot list, read, rotate, delete or bind it until you share it. To share it, use `runtime secrets share NAME --agent <id>`. Share it once per agent. An agent's id is the `principalId` that `runtime me` prints for its key. Or use `--all` to share it with every key of yours. Or use `--none` to share it with only the key that stored it. You, signed in, can always use it. A secret stored on the website is every key's, as before. A job created with a secret its key may not use is refused with `secret_not_shared`. A job that binds a secret another key stored stops at its next run. This applies whenever the job was made. The job stays stopped until that key or you share the secret with the job's key. If another of your keys could reach a secret before now, rotate it.

## Move jobs from another platform

Jobs from Trigger.dev, Inngest, Modal, Google Cloud Run and AWS Batch move with one import or one command. They run unchanged. Each keeps its schedule, its size, its timeout and its retries. What cannot be carried over is listed with the reason. Nothing is silently dropped.

| From                                 | Change                                                                                                      | Then                                                |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Trigger.dev `schedules.task`, `task` | `@trigger.dev/sdk` (or `/v3`) to `withruntime/trigger`                                                      | `npx withruntime jobs deploy`                       |
| Inngest functions                    | `inngest` (and `inngest/next` and the other serve adapters) to `withruntime/inngest`                        | `npx withruntime jobs deploy`                       |
| Modal scheduled Functions            | `import modal` to `from withruntime import modal`                                                           | `python -m withruntime.modal deploy app.py`         |
| Google Cloud Run jobs                | Nothing: export the job and its Cloud Scheduler job                                                         | `runtime jobs import job.yaml scheduler.yaml`       |
| AWS Batch                            | Nothing: export the job definition and its EventBridge schedule or rule, or use the CloudFormation template | `runtime jobs import definition.json schedule.json` |

The drop-ins need SDK 0.36.0 or later (Python 0.34.0).

### Trigger.dev and Inngest

`runtime jobs deploy` builds the project into one image. The project's own lockfile installs its dependencies, with npm, pnpm, Yarn or Bun. Bun runs the TypeScript as written. The command then lists the tasks the project's files declare and makes one job per task, named `<project>-<task id>`. Deploying again updates each job in place.

```ts check
import { logger, schedules, task } from "withruntime/trigger";

export const nightly = schedules.task({
  id: "nightly-report",
  cron: { pattern: "0 3 * * *", timezone: "Europe/Berlin" },
  machine: "small-2x",
  maxDuration: 600,
  retry: { maxAttempts: 3 },
  run: async (payload) => {
    logger.log("report", { for: payload.timestamp, last: payload.lastTimestamp });
  },
});

export const resize = task({
  id: "resize-image",
  run: async (payload: { url: string }) => ({ resized: payload.url }),
});
```

- **A scheduled task** is a job on its cron. Its payload has `timestamp` (the time the run was due), `lastTimestamp`, `timezone`, `scheduleId` and the next ten `upcoming` times, as on Trigger.dev.
- **A task run on demand** is a paused job. `tasks.trigger(id, payload)`, or the task's own `trigger(payload)`, runs it once, now, in a fresh sandbox, with that payload. The payload is at most 64 KiB as JSON. The caller needs `RUNTIME_API_KEY`. The task's job is found by the task's id. If two deployed projects have a task with that id, set `RUNTIME_JOBS_PROJECT` to the project's name where `trigger` is called.
- **Size and limits.** `machine` sets the size: `micro` and `small-1x` are 1 vCPU with 256 or 512 MiB, `small-2x` 1 vCPU and 1 GiB, `medium-1x` 1 vCPU and 2 GiB, `medium-2x` 2 vCPU and 4 GiB, `large-1x` 4 vCPU and 8 GiB, and `large-2x` 8 vCPU and 16 GiB. `maxDuration` is the run's timeout, at most 60 minutes. `retry.maxAttempts` is the number of attempts, at most 5. `trigger.config.ts`'s `maxDuration`, `machine` and `retries.default.maxAttempts` apply to every task that sets none.
- **Hooks** (`init`, `onStart`, `onSuccess`, `onFailure`, `onComplete`, `cleanup`) and `wait.for` and `wait.until` work. A wait counts toward the run's timeout.

An Inngest function with a `cron` trigger is a job on that schedule. A time zone written as `TZ=Europe/Paris 0 12 * * 5` is the job's time zone. A function with an `event` trigger is a paused job. `inngest.send(event)` runs every function of the app triggered by that event name once, now, with the event as its payload. The functions must be imported where `send` is called, as `serve()` imports them. Inside a run, `step.run` runs its code and returns its result. `step.sleep` and `step.sleepUntil` wait in the run. `step.sendEvent` sends events. A function's `retries` (4 by default, as on Inngest) become its attempts, at most 5. `timeouts.finish` is the run's timeout. A `NonRetriableError` ends the run with no more attempts. `serve()` returns 410 Gone, because nothing calls the app's endpoint any more.

### Modal

```python check
from withruntime import modal

app = modal.App("reports")
image = modal.Image.debian_slim().pip_install("requests")


@app.function(image=image, schedule=modal.Cron("0 9 * * MON-FRI", timezone="America/New_York"),
              cpu=2, memory=2048, timeout=900, retries=2,
              secrets=[modal.Secret.from_name("reports", required_keys=["API_TOKEN"])])
def morning_report():
    print("sent")
```

`python -m withruntime.modal deploy app.py` (or `app.deploy()`) makes each function with a `schedule` a job named `<app>-<function>`. All the app's functions run from one image that holds every function's packages. So a scheduled function's `.remote()`, `.local()`, `.map()`, `.for_each()` and `.spawn()` calls run in the same sandbox, as plain calls. Every function must start from the same base image. `cpu`, `memory`, `timeout` and `retries` size the job. Each of a secret's `required_keys` is bound from the jobs secret of that name. Every function's secrets are bound to every job, because the functions a scheduled function calls run in its sandbox. Store it first with `runtime secrets set NAME --jobs`.

`modal.Cron` keeps its expression and time zone. `modal.Period` becomes the cron that runs as often: `Period(hours=1)` is `0 * * * *`, and `Period(days=1)` is `0 0 * * *`. Unlike on Modal, these runs fall on the clock's marks, not on intervals counted from the deploy. A period under a minute, such as `Period(seconds=5)` in Modal's own example, runs as a job each minute that calls the function every 5 seconds through that minute. Its sandbox is billed for the whole minute.

### Google Cloud Run and AWS Batch

```bash no-run
gcloud run jobs describe nightly-export --format export > job.yaml
gcloud scheduler jobs describe nightly-export-trigger --format yaml > scheduler.yaml
runtime jobs import job.yaml scheduler.yaml --dry-run    # the plan; creates nothing
runtime jobs import job.yaml scheduler.yaml              # builds and creates the job

runtime jobs import template.yaml --parameter AWS::Region=us-east-1 --parameter AWS::AccountId=123456789012
```

`runtime jobs import` reads the files into a plan (`POST /v1/job-imports`, `jobs.importPlan` in the SDKs, or the `runtime_jobs_import` MCP tool). For each job, it builds an image `FROM` the job's container image. It adds the job's environment and working directory, with the platform's command and args as the image's `ENTRYPOINT` and `CMD`. It then creates the job, which runs the image's start command, or updates the job of the same name. Pulling from Artifact Registry, ECR or another private registry needs its credential once: `runtime images registry set <host>`.

- **Size, timeout and retries** carry over. CPU rounds up to whole vCPUs. A timeout over 60 minutes, or a job with none (AWS Batch's default), is 60 minutes. Cloud Run's `maxRetries` and Batch's `retryStrategy.attempts` become attempts, at most 5.
- **Schedules.** A Cloud Scheduler job's cron and time zone carry over unchanged. An EventBridge `cron(...)` becomes five fields: `?` becomes `*`, and days of the week count from Sunday as 0. A `rate(...)` becomes the cron that runs as often, on the clock's marks. `at(...)` runs once, in the schedule's time zone. A job with no schedule in the files runs when triggered, or at `--cron`.
- **Secrets.** A value from Secret Manager, Secrets Manager or SSM is bound from the jobs secret of the same name. The import refuses the job until that secret is stored. A secret never goes into the image.
- **Batch parameters.** `Ref::name` in a command is filled in from the definition's `parameters`, then from the parameters its schedule submits. The schedule's container overrides apply too.
- **CloudFormation.** `!Ref`, `!Join` and `!Sub` of the template's parameters (their defaults, or `--parameter`) are worked out. A value that still names something only CloudFormation knows blocks the job, and the reason names the `--parameter` to give.

Some settings have no equivalent. A job that would not run as it did is blocked, with the reason, and the rest move. `--dry-run` also prints each image's full Dockerfile. A user or working directory that is not a plain value (letters, digits and `- _ . / : @ +`) blocks the job, so a file cannot add its own build steps.

- More than one task at once (Cloud Run's `taskCount`), a multi-node Batch job, or sidecar containers. A job runs one command on one machine.
- A GPU.
- A mounted volume: a Cloud Storage bucket, NFS, EFS or a secret mounted as a file. Read the data over the network, or keep it on a [volume](#keep-data-between-runs).

Others are left out with a note: VPC connectors (reach private hosts over a [WireGuard network](./networking)), Cloud SQL sockets, a job queue's priority and compute environments (each run gets its own sandbox when it is due), and log drivers (a run's output is kept with the run). A service account or job role becomes an [identity token](./identity-tokens) the run trades for that account's access, with no stored key.

## Commands

| CLI                                 | SDK                          | What it does                                  |
| ----------------------------------- | ---------------------------- | --------------------------------------------- |
| `runtime jobs create <name> ... --` | `jobs.create`                | Schedule a job; prints its id                 |
| `runtime jobs ls`                   | `jobs.list`                  | Your jobs, oldest first                       |
| `runtime jobs get <id>`             | `jobs.get`                   | One job, in full                              |
| `runtime jobs runs <id> [--all]`    | `jobs.runs(id, {order})`     | Its newest 100 runs; `--all`: every one       |
| `runtime jobs logs <id> [-f]`       | `jobs.logs(runId, {cursor})` | A run's output; a job id means its latest run |
| `runtime jobs pause`, `resume <id>` | `jobs.pause`, `jobs.resume`  | Stop or restart scheduling                    |
| `runtime jobs trigger <id>`         | `jobs.trigger`               | Run it now, once                              |
| `runtime jobs reschedule <id> ...`  | `jobs.reschedule`            | Give it a new schedule                        |
| `runtime jobs update <id> ...`      | `jobs.update`                | Change what it runs, or its alert, in place   |
| `runtime jobs cancel <id>`          | `jobs.cancel`                | End it and stop a run in progress             |
| `runtime jobs import <file>...`     | `jobs.importPlan`            | Move Cloud Run or AWS Batch jobs              |
| `runtime jobs deploy [<dir>]`       | -                            | Run Trigger.dev tasks or Inngest functions    |

The HTTP routes are `POST /v1/jobs`, `GET /v1/jobs`, `GET /v1/jobs/{id}`, `GET /v1/jobs/{id}/runs` (oldest first; `?order=newest` for newest first), `POST /v1/jobs/{id}:pause`, `:resume`, `:trigger`, `:reschedule` (body `{"schedule": ...}`), `:cancel`, `PATCH /v1/jobs/{id}` (also `POST /v1/jobs/{id}:update`; a body of the fields that change), `GET /v1/job-runs/{id}`, `GET /v1/job-runs/{id}/logs` and `POST /v1/job-imports` (a plan; it changes nothing). Every write takes an `Idempotency-Key`. The SDKs and the CLI send one for you. So a retry after a lost response never creates a second job.


---

<!-- https://withruntime.com/docs/langchain -->

# Runtime for LangChain, LangGraph and Deep Agents

Run a Deep Agent's shell and files, or a LangChain or LangGraph agent's tools, in a Runtime sandbox.

A Deep Agent takes a sandbox as its backend. `RuntimeSandbox` is that backend,
like Deep Agents' Daytona, E2B or Modal sandboxes: pass it to
`create_deep_agent` and the agent's `execute`, `ls`, `read_file`, `write_file`,
`edit_file`, `glob` and `grep` tools run in a Firecracker microVM with its own
kernel, billed for the CPU it uses. LangChain and LangGraph agents get four
sandbox tools instead.

## Deep Agents

```bash no-run
pip install langchain-withruntime
```

`langchain-withruntime` installs the Runtime SDK and Deep Agents.
`pip install "withruntime[deepagents]"` gives the same backend as
`withruntime.deepagents.RuntimeSandbox`.

```python check
from deepagents import create_deep_agent
from langchain_withruntime import RuntimeSandbox
from withruntime import Sandbox


def solve(model, task: str) -> str:
    with Sandbox.create() as sbx:
        agent = create_deep_agent(model=model, backend=RuntimeSandbox(sbx))
        result = agent.invoke({"messages": [{"role": "user", "content": task}]})
        return result["messages"][-1].content
```

The key comes from `RUNTIME_API_KEY`, or from `npx withruntime login` on this
machine, as in the rest of the SDK. Leaving the `with` block deletes the sandbox.
`Sandbox.create()` takes the sandbox's settings, such as `image`, `region`,
`vcpu`, `memory_mib` and `timeout_seconds`; see the [Python guide](./python).

`RuntimeSandbox(sbx)` takes two options:

| Option             | Default | What it does                                                                                 |
| ------------------ | ------- | -------------------------------------------------------------------------------------------- |
| `timeout_seconds`  | 1800    | The limit for a command that names none. A command past it is stopped and its output says so |
| `max_output_chars` | none    | Keep only the end of a longer output and mark it truncated                                   |

Output comes back whole by default. Deep Agents moves a long result out of the
model's context on its own, and its file tools read the output of the commands
they run, so `max_output_chars` applies to those too.

### Deep Agents Code

The package registers a `runtime` sandbox provider, so Deep Agents Code runs a
session in a new Runtime sandbox and stops it when the session ends:

```bash no-run
dcode install langchain-withruntime --package
dcode --sandbox runtime
```

`--sandbox-id` attaches to a sandbox that is already running and leaves it
running. `RuntimeProvider` is the same lifecycle in your own code:

```python check
from langchain_withruntime import RuntimeProvider

provider = RuntimeProvider()
backend = provider.get_or_create(timeout=900)  # a new sandbox with a 15 minute time limit
try:
    print(backend.execute("uname -r").output)
finally:
    provider.delete(sandbox_id=backend.id)
```

`get_or_create` passes other keywords to `Sandbox.create`, and `delete` stops
the sandbox.

## LangChain

`sandbox_tools(sbx)` returns four tools as plain Python functions:
`runtime_exec`, `runtime_read_file`, `runtime_write_file` and
`runtime_list_files`. LangChain's `tool` turns them into LangChain tools for
`create_agent` or anything else that takes tools.

```bash no-run
pip install withruntime langchain
```

```python check
from langchain.agents import create_agent
from langchain_core.tools import tool
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def solve(model, task: str) -> str:
    with Sandbox.create() as sbx:
        agent = create_agent(model, tools=[tool(f) for f in sandbox_tools(sbx)])
        result = agent.invoke({"messages": [{"role": "user", "content": task}]})
        return result["messages"][-1].content
```

## LangGraph

The same tools go in a `ToolNode`:

```python check
from langchain_core.tools import tool
from langgraph.graph import START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition
from withruntime.tools import sandbox_tools


def build(model, sbx):
    tools = [tool(f) for f in sandbox_tools(sbx)]
    bound = model.bind_tools(tools)

    def call_model(state: MessagesState):
        return {"messages": [bound.invoke(state["messages"])]}

    graph = StateGraph(MessagesState)
    graph.add_node("model", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.add_edge(START, "model")
    graph.add_conditional_edges("model", tools_condition)
    graph.add_edge("tools", "model")
    return graph.compile()
```

Relative paths are under `/workspace`, and each tool's output is capped so one
noisy command cannot flood the model's context. The
[frameworks guide](./frameworks) has the same tools for other frameworks.

## What runs in the sandbox

- **Commands.** `execute` runs its command under `bash -c` in `/workspace`,
  the sandbox's home directory. Its output is stdout then stderr; a command
  that runs out of time is stopped, and the output says so.
- **Files.** `write_file` and `edit_file` create parent directories. Files
  under `/workspace` move through Runtime's Files API; files anywhere else move
  through a staged copy in `/workspace/.deepagents-staging` that is removed
  afterwards. The file tools act as the sandbox user, `runtime`, so `/tmp`
  works and a system directory does not; `execute` can still run `sudo`.
- **Search and reading.** `ls`, `read_file`, `edit_file`, `glob` and the
  preflight of `write_file` run short `python3` scripts in the sandbox, and
  `grep` runs GNU `grep`. The default image has both; a custom
  [image](./images) needs them too.
- **Deep Agents' own files**, such as its to-do list and memory, stay in the
  agent's state, as with every Deep Agents sandbox.

## What was verified

On 25 September 2026, with Deep Agents 0.7.19, LangChain 1.4.2, LangGraph
1.2.12, langchain-tests 1.1.9, Deep Agents Code 0.1.77 and Python 3.12, and
with the sandbox replaced by a stand-in that runs each command on a Linux
machine and serves `/workspace` from a directory:

- LangChain's standard sandbox suite, `SandboxIntegrationTests`, ran against
  `RuntimeSandbox`: 79 of its 86 cases passed. The other seven expect
  behavior Deep Agents 0.7 changed (`write_file` now overwrites a file, and
  `glob` returns absolute paths); they fail the same way on a bare
  `BaseSandbox` with no Runtime code in it.
- `create_deep_agent`, driven by a scripted model, called `write_file`,
  `edit_file`, `read_file`, `execute`, `ls`, `glob` and `grep` through
  `RuntimeSandbox`, and each returned what it should.
- Deep Agents Code found the `runtime` provider through its entry point.
- The LangChain and LangGraph samples above ran to a final answer with a
  scripted model calling `runtime_exec` on a stand-in sandbox.

That run found one defect, fixed in `withruntime` 0.6.1: `RuntimeSandbox` cut
any output past 100,000 characters, which broke `read_file` on files larger
than about 75 KB. `langchain-withruntime` requires 0.6.1 or later.

On 23 September 2026, `RuntimeSandbox` ran in Deep Agents 0.7.18's own
agent loop against real sandboxes without credit, driven by a scripted model, as the
[frameworks guide](./frameworks#what-was-verified) records.


---

<!-- https://withruntime.com/docs/limits -->

# Limits

Every limit an account is held to, in one place. An account with credit pays
for what it keeps. Its limits cover what runs at the same time and what it
stores. They reflect the room the fleet has, and they act as ceilings against a
runaway agent. Most customers never reach them. An account without credit has
smaller limits. Adding credit raises them immediately.

You can see your account's limits, and how much of each you use, on the
[Limits page of the console](https://withruntime.com/account/limits). A key
reads the same numbers from `GET /v1/limits` (`runtime.limits.get()` in the
SDK). They are in its `account` list, with each row's `limit` (such as
`sandbox.memory_mib`), `max` and `used`. An agent can check a limit before a
create is refused, and hold back new work when it nears the limit. A key
limited to a compartment, or a worker key another key made, sees only its own
sandboxes. Its `account` is null.

## When you meet one

A create past a limit is refused with `quota_exceeded`. A limit on what runs at
the same time returns 429 with `Retry-After: 5` and `retryable: true`. A limit
on what is kept returns 409 with `retryable: false`. It clears only when you
delete one. The refused create costs nothing.

The message names the limit and its number. The error's `details` give the same
information in code:

```json
{
  "error": {
    "code": "quota_exceeded",
    "status": 429,
    "message": "This account holds up to 5 volumes. Delete one you no longer need, or write to support@withruntime.com to raise the limit.",
    "details": {
      "limit": "volume.count",
      "max": 5,
      "raise": "Write to support@withruntime.com to raise it.",
      "docs": "https://withruntime.com/docs/limits"
    },
    "retryable": true
  }
}
```

Retrying helps only after something the limit counts has ended. Delete or stop
something the limit counts. Add credit if the account has none. Or write to
support@withruntime.com with the limit (`details.limit`) and the number you
need. Support can raise any limit below for an account, usually the same day
([feedback and support](./feedback-and-support)).
Raising the sandbox count immediately also raises the vCPUs, memory and disk
across running sandboxes, so the larger count fits. A raised limit belongs to
the account. It starts at what auto top-up gives: 200 sandboxes,
and twice the vCPUs, memory and disk. It replaces auto top-up's doubling, so it
stays the same with auto top-up on or off. It is never below what auto top-up
would give. It shows on the Limits page and in `GET /v1/limits` immediately.

**Raise a limit for a burst: book room.** For many sandboxes at the same time,
for a few hours (a batch of evals, rollouts or browser runs), book the room
ahead. During that window, your sandbox limits rise by what you booked. Creates
up to that amount are never refused for room or limits. Runtime confirms or
declines the booking immediately, without a need to write to support
([book room for a burst](./reservations)).

## Waiting in line for room

A create or a wake refused because its region is short of room
(`503 no_capacity`, not a limit) takes a place in the region's line. The request
is retried while it waits. By default, the SDKs retry with the same
`Idempotency-Key` for up to two minutes. Freed room goes first to the highest
lane waiting for it: Enterprise, then Scale, Pro Max, Pro and Free, based on the
account's [plan](./plans). Runtime's own work comes after every customer's. The
refusal says where the request stands:

```text
no capacity; in line at place 2: the region's room goes to higher lanes first: 1 waiting ahead (pro 1); this account's lane is free
```

The error's `details.line` gives the same information in code: `lane`, `place`
(1 is next), `ahead` (how many wait ahead of it, by lane) and `words`. The
console shows the message where you create or wake a sandbox.

- Nothing already running stops for a higher lane. Room your account
  [booked](./reservations) stays yours, whoever waits.
- A lower lane waits only for room that a higher waiting lane could use. An
  account's waits hold others back for three minutes at most in any fifteen, in
  each lane and region.
- A place not requested again within 15 seconds holds no one. An account holds
  one place per lane in a region, however many requests it sends.

## Each account's share of a server

Sandboxes of different accounts share servers, and no account can slow down
or crowd out another on the same server. This applies to every account,
Runtime's own included, and needs no setting:

- **CPU.** Under contention, a server divides its CPU between accounts
  first, then between each account's sandboxes. Each sandbox keeps the CPU
  floor it was created with (`cpuFloorMillis`, or every vCPU with
  `cpu: "reserved"`). Each account's weight is the sum of its sandboxes'
  floors plus an equal part of half the CPU that no floor holds, so an
  account with one busy sandbox is not outweighed by the number of busy
  sandboxes another account runs.
- **A ceiling on CPU.** One account's sandboxes together use at most half
  of a server's cores, even when the rest of the server is idle, so other
  accounts' commands start without waiting for a core. A single sandbox
  larger than half a server, or reserved CPU above half, keeps all of its
  vCPUs.
- **Memory and placement.** Placement books at most half of one server's
  memory and CPU floors for one account, and places the account's
  additional sandboxes on other servers. An account's first sandbox on a
  server is never refused for this, and capacity your account
  [booked](./reservations) on a server is yours whatever the share.
- **Disk I/O and network.** A server divides disk I/O and outbound network
  bandwidth between accounts by weight, then between each account's
  sandboxes. A paid sandbox weighs more than a trial one.

When the account holds its share of every server in the region that could run
a new sandbox, the create is refused with `account_share_full` (429 with
`Retry-After: 30`) and nothing is charged:

```json
{
  "error": {
    "code": "account_share_full",
    "status": 429,
    "message": "This account already uses its share of every server in us-east that could run this sandbox: no account books more than 50% of one server's memory or CPU floors, so that other accounts on it keep theirs. Stop or pause sandboxes you no longer need, or retry when some end.",
    "retryable": true
  }
}
```

Stop or pause sandboxes you no longer need, or retry after `Retry-After`.
For a large burst, [book room](./reservations) ahead.

## What an account holds and runs

`details.limit` names each row. Counts are per region, except sandboxes kept.
The two storage limits count every region together.

| Limit (`details.limit`)                                       | Without credit        | With credit                                             |
| ------------------------------------------------------------- | --------------------- | ------------------------------------------------------- |
| Sandboxes at once (`sandbox.count`)                           | 4 | 100, 200 with auto top-up |
| vCPUs across running sandboxes (`sandbox.vcpu`)               | 8                     | 200, twice that with auto top-up          |
| Memory across running sandboxes (`sandbox.memory_mib`)        | 16 GiB                | 400 GiB, twice that with auto top-up         |
| Disk across running sandboxes (`sandbox.disk_mib`)            | 10 GiB each           | 1 TiB                                        |
| Sandboxes kept, running, paused or stopped (`sandbox.kept`)   | 5    | 1,000                                                   |
| Storage kept in all (`sandbox.stored_mib`), [below](#storage) | 50 GiB                | 500 GiB                                                 |
| Snapshot storage (`snapshot.stored_mib`)                      | 20 GiB                | 250 GiB                                                 |
| Volumes (`volume.count`)                                      | 5                     | 10,000                                                  |
| Volume storage (`volume.disk_mib`)                            | 500 GiB               | Storage kept in all; charged by the GB                  |
| Volume backups (`volume-backup.count`)                        | 200                   | 10,000                                                  |
| Snapshots (`snapshot.count`)                                  | 50                    | 10,000                                                  |
| Images (`image.count`)                                        | 20                    | 10,000                                                  |
| Image storage (`image.disk_mib`)                              | 200 GiB               | Storage kept in all; charged by the GB                  |
| Jobs, active or paused (`job.count`)                          | 1,000                 | 10,000                                                  |
| Secrets (`secret.count`)                                      | 1,000                 | 10,000                                                  |
| Dedicated outbound addresses (`address.count`)                | Needs credit          | 2                                                       |
| Private networks (`tunnel.count`)                             | Needs a kept top-up   | 1                                                       |

Without credit, a sandbox has at most 2 vCPU, 4 GiB of memory and a 10 GiB
disk. An account can keep up to 5 sandboxes, running, paused or
stopped. It makes 50 in any 24 hours. It starts
10 image builds a day. It holds 10 live API
keys. These refusals have codes of their own, starting `no_credit_`
([included usage](./included-usage#without-credit)). With credit, a sandbox is
up to 16 vCPUs, 64 GiB of memory and a 400 GiB disk
([pricing](./pricing#how-many-at-once)). A disputed payment, a suspension or
an abuse report holds an account to 50 sandboxes running
at the same time.

## Storage

An account's stored data is limited in GiB, not only counted. `sandbox.stored_mib`
covers everything it keeps: snapshots, images, volumes, volume backups, and
paused or stopped sandboxes. `snapshot.stored_mib` counts its snapshots alone,
both memory and disk-only. A memory snapshot keeps the sandbox's memory as well
as its disk.

What counts is the amount actually stored. Storage is billed by that same
figure ([pricing](./pricing#snapshots-images-and-volumes)). It includes a
snapshot's or backup's stored bytes, and an image's stored bytes. It also
includes a paused sandbox's memory and disk, and a stopped sandbox's kept disk,
as its server measured them. A volume counts at its size. Its server sets that
size aside in full when the volume is made. A grow not yet done counts at its
new size. Until a size is measured, it counts at the most it may store. A
capturing snapshot counts at its sandbox's measured memory and disk. A disk-only
snapshot counts at its disk alone. Otherwise it counts at the sizes asked for.
An image being built counts at its `maxImageMiB`, or else at its base image's
size. A pending backup counts at what its volume holds as last measured.
Otherwise it counts at the volume's size.

A snapshot (including a fork's), an image build, a requested backup, or a volume
made, restored or grown is refused with `quota_exceeded` when what it may store
would take the account past the limit. The message and `details` give the
limit, its size, and what the account stores now (`used`, in MiB):

```json
{
  "error": {
    "code": "quota_exceeded",
    "status": 409,
    "message": "This account keeps up to 50 GiB stored in all: snapshots, images, volumes, volume backups, and paused or stopped sandboxes, and stores 50 GiB now. Nothing you keep is deleted. Delete what you no longer need to make room, add credit if the account has none (it raises this limit), or write to support@withruntime.com to raise the limit.",
    "details": {
      "limit": "sandbox.stored_mib",
      "max": 51200,
      "used": 51200,
      "raise": "Write to support@withruntime.com to raise it.",
      "docs": "https://withruntime.com/docs/limits"
    }
  }
}
```

A storage limit never deletes or stops anything. An account past one keeps
everything it has. Its running and paused sandboxes keep working. But it does
not make anything new that stores data until it is under the limit again.
Pausing and stopping are never refused. Neither is anything Runtime does itself,
such as a daily volume backup or a server's nightly backup. An account that
already stored more than a limit when these limits began has what it stored then
as that limit. The Limits page shows it. Credit or a plan still raises it above
that.

## Limits of one sandbox or one feature

These limits keep one sandbox or one host healthy, whatever the account pays.
Each is refused with its own message. Support can raise most of them.

| Limit                                      | Number                                                                                                     |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Previews one sandbox shares                | 16 ports                                                                                                   |
| TCP ports                                  | 5 a sandbox, 20 an account                                                                                 |
| Custom domains                             | 50 an account, 20 added a day                                                                              |
| Peers on a private network                 | 16                                                                                                         |
| Image registry credentials                 | 20                                                                                                         |
| Secrets with rules for sandboxes' requests | 50                                                                                                         |
| Webhooks                                   | 16                                                                                                         |
| OpenTelemetry exports                      | 3                                                                                                          |
| Watches sending file changes at once       | 16                                                                                                         |
| Image builds at once                       | 1 without credit, 4 with                                                                                   |
| Open files a process (`ulimit -n`)         | 65,536; a process raises it to 1,048,576 without root                                                      |
| New connections to one site                | 20 a second a sandbox, 100 an account on one server ([outbound traffic](./egress#connections-to-one-site)) |

API requests are limited per key and per account. A request past one is refused
with `rate_limited` and a `Retry-After` ([API](./api)).


---

<!-- https://withruntime.com/docs/mcp -->

# Runtime Cloud MCP

Runtime's MCP server gives an agent every Runtime product as tools, with instructions on first contact, so it needs no wrapper code.

MCP and the HTTPS API share authentication, ownership, spending checks and
idempotency.

## Add it to your agent

One command, no key to copy. Claude Code:

```bash no-run
claude mcp add --scope user runtime -- npx -y withruntime mcp
```

Codex:

```bash no-run
codex mcp add runtime -- npx -y withruntime mcp
```

or, in `~/.codex/config.toml`:

```toml
[mcp_servers.runtime]
command = "npx"
args = ["-y", "withruntime", "mcp"]
```

Cursor, in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project), and any
other client that takes the same shape:

```json
{
  "mcpServers": {
    "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] }
  }
}
```

**The first time, one approval connects it.** When this machine is not
connected, the server offers one tool, `runtime_connect`:

1. The agent calls it and shows you a link and a code.
2. You approve **Connect agent** in your browser.
3. The agent calls it again, and every Runtime tool appears. The response
   carries the server's full instructions (limits, cleanup, safe retries).
   Before it connected, the agent had read only the short version. A client
   that does not refresh its tools when told shows them after the server or
   the client restarts. The connection is saved, so it connects immediately.

A machine already connected by the CLI (`npx withruntime login`) skips this
step.

Approve only a connection you started and whose code matches. It can manage
resources and spend prepaid credit across your account until you revoke it
with `npx withruntime logout` or on the API keys page.

The command is a bridge. It forwards MCP messages as they are to the remote
server over the saved connection, so no key sits in the agent's configuration.
It needs Node 22.12 or later. It loads its one dependency, `undici`, only when a
proxy applies. It does not create an account. For CI, `RUNTIME_API_KEY` from a
secret manager overrides the saved connection.

## Remote connection

Clients that speak MCP over HTTP can skip the bridge. The endpoint is
`https://api.withruntime.com/mcp`, over MCP Streamable HTTP.

**Sign in through the browser, with no key.** Add the address as a custom
connector or remote server, in Claude, ChatGPT, Cursor, VS Code or any client
that supports MCP sign-in:

1. The client opens a Runtime page in your browser.
2. You sign in and approve **Connect** for that app. The page shows where the
   key goes, so check it is the app you are using.
3. The client receives a key of its own and every Runtime tool appears.

The key belongs to a new agent named after the app. It can manage resources and
spend prepaid credit across your account until you revoke it on the
[API keys page](https://withruntime.com/account/keys), where it is listed with
the app's name. A client that asks for scope `runtime:read` gets a read-only
key.

Claude Code can do the same without the bridge:

```bash no-run
claude mcp add --transport http --scope user runtime https://api.withruntime.com/mcp
```

Then run `/mcp` in Claude Code and choose to authenticate.

**Or send a key.** A server or CI job sends `Authorization: Bearer <key>` with a
key from https://withruntime.com/account/keys, supplied from a secret manager.
Never put a key in the URL, a command line, a browser bundle or a configuration
you commit.

Clients discover sign-in the standard way: a request with no key gets a `401`
whose `WWW-Authenticate` header points at
`https://api.withruntime.com/.well-known/oauth-protected-resource/mcp`, which
names `https://withruntime.com` as the authorization server. It supports OAuth
2.1 with PKCE, dynamic client registration and client metadata documents.

For ChatGPT, use `https://api.withruntime.com/mcp?profile=chatgpt`. Its tools
keep persistent credentials out of the conversation. Starting or reading a
sandbox MCP server returns safe state and scoped preview links. When another
client needs the server's gateway token or authorization headers, get them
through the website or a local CLI. This profile also leaves out what a ChatGPT
request does not need. The audit log, referrals, single sign-on settings and the
price comparison are not listed. `runtime_account` returns usage and limits
without names, internal identifiers or card details. The ordinary MCP
connection keeps its usual credential behavior.

**Only the docs?** `https://withruntime.com/mcp` is a separate, public MCP
server with no sign-in: it searches and reads these guides
(`search_runtime_docs`, `read_runtime_doc`, `list_runtime_docs`) and runs
nothing.

## Tools

The server returns instructions in its `initialize` response: the quick start, safe retries,
and how to report problems. Read them, then inspect tool results rather than
assuming a completed tool call means the workload succeeded.

The tools describe the interface, but a listed tool is not a promise that its
capability is enabled. Check the [products page](./products) for availability.

| Tool                                                                                                                                                                               | What it does                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runtime_sandboxes_create`                                                                                                                                                         | Create a sandbox and wait for readiness; inspect its returned state. `env` sets variables for every command, terminal and SSH session in it                                                                                                                                                                                                                       |
| `runtime_sandboxes_list`                                                                                                                                                           | List by state, name or label, or read one by id                                                                                                                                                                                                                                                                                                                   |
| `runtime_sandboxes_manage`                                                                                                                                                         | Stop, which keeps its disk, pause, wake, extend; retention, persist, restart a stopped one; update (name, labels, `env`); delete, which stops it, deletes its disk and memory and removes it for good; `switch-image`, which moves it to another image keeping `/workspace`                                                                                       |
| `runtime_sandboxes_inspect`                                                                                                                                                        | A sandbox's storage, paused storage, lifetime or recovery point                                                                                                                                                                                                                                                                                                   |
| `runtime_sandboxes_exec`                                                                                                                                                           | Run a command and get its exit code and output, or start it in the background                                                                                                                                                                                                                                                                                     |
| `runtime_sandboxes_process`                                                                                                                                                        | Read, feed, signal or list background processes                                                                                                                                                                                                                                                                                                                   |
| `runtime_sandboxes_files_read`, `runtime_sandboxes_files_write`                                                                                                                    | Read (whole or by line range) and write files                                                                                                                                                                                                                                                                                                                     |
| `runtime_sandboxes_files_list`, `runtime_sandboxes_files_manage`                                                                                                                   | List and glob; stat, make, move and remove                                                                                                                                                                                                                                                                                                                        |
| `runtime_sandboxes_files_link`                                                                                                                                                     | A link to one file anyone can open with no key, to hand a person in chat: download it (a folder as `.tar.gz`), or upload to it; 1 hour by default, at most 7 days                                                                                                                                                                                                 |
| `runtime_sandboxes_interpreter_run`, `runtime_sandboxes_interpreter_contexts`                                                                                                      | A notebook-style session in Python, JavaScript, TypeScript, R, Java, Bash or Go; charts as images, data frames as tables                                                                                                                                                                                                                                          |
| `runtime_sandboxes_files_watch`                                                                                                                                                    | Watch a directory for file changes: start, read events after a cursor, list, stop                                                                                                                                                                                                                                                                                 |
| `runtime_images_build`, `runtime_images_registries`                                                                                                                                | Custom images from a recipe, any public or private image, or a Dockerfile, with versions and tags; registry credentials                                                                                                                                                                                                                                           |
| `runtime_images`                                                                                                                                                                   | `list`, `get`, `tag` and `delete` image versions                                                                                                                                                                                                                                                                                                                  |
| `runtime_volumes`                                                                                                                                                                  | Persistent disks: `create` (with `fromBackup` to restore a backup), `list`, `get`, `delete`; `attach` and `detach` require shared-volume availability, and `resize` requires volume growth to be enabled                                                                                                                                                          |
| `runtime_volumes_backup`                                                                                                                                                           | Back a volume up off its server: `create`, `list`, `get`, `policy` for daily backups, `delete`                                                                                                                                                                                                                                                                    |
| `runtime_sandboxes_fork`                                                                                                                                                           | Copies of a sandbox as it is now, with its memory and processes; on its server, or another when it is full                                                                                                                                                                                                                                                        |
| `runtime_snapshots`                                                                                                                                                                | `create` keeps a running or paused sandbox (a running one is paused for the moment it takes and woken again), copied off its server (not with volumes), with `mode: "memory"` or `"disk"`; `list`, `get`, `update` (name, labels), `delete`                                                                                                                       |
| `runtime_sandboxes_mounts`                                                                                                                                                         | Your S3, R2 or Google Cloud Storage bucket as a directory: `mount`, `list`, `unmount`; the proxy signs, the sandbox never holds the key                                                                                                                                                                                                                           |
| `runtime_sandboxes_previews`                                                                                                                                                       | Share a port at `runtimehost.com`, private by default: `create`, `list`, `rotate`, `delete`; browser access to one sandbox: `session_create`, `session_list`, `session_revoke`                                                                                                                                                                                    |
| `runtime_sandboxes_tailscale`                                                                                                                                                      | Join a paid sandbox to your tailnet: `up`, `status`, `down`                                                                                                                                                                                                                                                                                                       |
| `runtime_sandboxes_network`                                                                                                                                                        | `get` or `set` a sandbox's network rules                                                                                                                                                                                                                                                                                                                          |
| `runtime_sandboxes_desktop_act`, `runtime_sandboxes_desktop_screenshot`                                                                                                            | Drive a desktop in the sandbox                                                                                                                                                                                                                                                                                                                                    |
| `runtime_sandboxes_desktop_record`                                                                                                                                                 | Record the desktop to MP4: start, stop, list, delete                                                                                                                                                                                                                                                                                                              |
| `runtime_sandboxes_metrics`, `runtime_events_list`                                                                                                                                 | A sandbox's CPU and memory over time; lifecycle events                                                                                                                                                                                                                                                                                                            |
| `runtime_webhooks_manage`, `runtime_otel_manage`                                                                                                                                   | Webhooks for lifecycle events, and OpenTelemetry export                                                                                                                                                                                                                                                                                                           |
| `runtime_domains`, `runtime_ports`, `runtime_ips`, `runtime_networks_wireguard`, `runtime_networks_upstream_proxy`, `runtime_networks_private`, `runtime_networks_signed_requests` | Custom domains, public TCP ports, dedicated outbound addresses, the WireGuard tunnel, your own upstream proxy, reaching your sandboxes by name and signing requests as Runtime's; see below                                                                                                                                                                       |
| `runtime_account`                                                                                                                                                                  | `get` the account, its free usage and credit; `limits` for this key's access and daily spending limit; `referrals` for your link and its credit (you both get up to $1,000); `sso` for single sign-on and SCIM; `compare` for what your sandboxes would cost at a rival, and what you save a month; `emails` for which optional emails your person gets |
| `runtime_reservations`                                                                                                                                                             | [Book room](./reservations): `create` holds room for many sandboxes over a window, or standing room for a pool until cancelled, confirmed or declined immediately; `update` changes standing room; `list`, `get`, `cancel`                                                                                                                                        |
| `runtime_switching_record`                                                                                                                                                         | Record the provider you are leaving, before you first add credit; credit added within 30 days of signing up is matched, up to $1,000 in total                                                                                                                                                                                              |
| `runtime_audit_list`                                                                                                                                                               | The account's audit log: members, keys, credit and security changes, with who and from where                                                                                                                                                                                                                                                                      |
| `runtime_secrets`                                                                                                                                                                  | Secrets sandboxes use without seeing, a placeholder inside and the value added by the proxy, or given to the machine as its real value (`exposed`): `set`, `list`, `get`, `delete`; and `jobs_put`, `jobs_list`, `jobs_get`, `jobs_rotate`, `jobs_reveal`, `jobs_delete` for the copy a scheduled job puts in its environment                                     |
| `runtime_jobs`                                                                                                                                                                     | [Scheduled jobs](./jobs): a command in a fresh sandbox, once or on a cron schedule: `create`, `list`, `get`, `runs`, `run`, `logs`, `pause`, `resume`, `trigger`, `reschedule`, `update`, `cancel`                                                                                                                                                                |
| `runtime_feedback`                                                                                                                                                                 | `submit` a problem or a missing feature; `list` what happened to it                                                                                                                                                                                                                                                                                               |
| `runtime_support`                                                                                                                                                                  | Ask Runtime support: `message`, then `read` the reply                                                                                                                                                                                                                                                                                                             |
| `runtime_notices`                                                                                                                                                                  | Account notices: pause expiry, unpaid storage and deletion deadlines                                                                                                                                                                                                                                                                                              |
| `runtime_docs_read`                                                                                                                                                                | Read any page of these docs                                                                                                                                                                                                                                                                                                                                       |

Tool names read `runtime_<product>_<verb>`, or `runtime_<product>` for a tool
that takes an `action`, the product spelled as the CLI spells it. The verbs an
agent needs in its first session each have a tool of their own; a product's
rarer verbs share one, and its `action` names the verb: `runtime_volumes` with
`"action": "get"` reads a volume. Everything that
acts on one sandbox is `runtime_sandboxes_*` and takes the sandbox as `id`;
images, volumes and snapshots are `runtime_images*`, `runtime_volumes*` and
`runtime_snapshots`; what spans products, such as the account, usage, secrets,
events, feedback and docs, names no product. Results come back as both text and
`structuredContent`. An error is a tool result with `isError`, a code, a hint
and a `requestId`.

## Renamed tools

On 26 September 2026, 52 tools became 16 that take an `action`, which cut the
tool list's context cost for an agent by nearly a quarter. The old names now
fail with `not_found`, before any operation runs, and the hint names the grouped
tool and its `action`. Change any permission rule, prompt or script that names
one, then refresh the tool list. `runtime_sandboxes_mounts` and
`runtime_volumes_backup` keep their grouped names and require an `action`; an
old call that omits it is refused.

| Before                                                                                          | Now                                                               |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `runtime_domains_add`, `_verify`, `_list`, `_remove`                                            | `runtime_domains` with `add`, `verify`, `list`, `remove`          |
| `runtime_ports_open`, `_list`, `_close`                                                         | `runtime_ports` with `open`, `list`, `close`                      |
| `runtime_ips_list`, `_reserve`, `_release`                                                      | `runtime_ips` with `list`, `reserve`, `release`                   |
| `runtime_networks_wireguard_create`, `_get`, `_add_peer`, `_rotate_peer`, `_remove_peer`        | `runtime_networks_wireguard` with the same verbs                  |
| `runtime_networks_upstream_proxy_get`, `_set`, `_remove`                                        | `runtime_networks_upstream_proxy` with `get`, `set`, `remove`     |
| `runtime_networks_private_get`, `_set`                                                          | `runtime_networks_private` with `get`, `set`                      |
| `runtime_networks_signed_requests_get`, `_set`                                                  | `runtime_networks_signed_requests` with `get`, `set`              |
| `runtime_sandboxes_network_get`, `_set`                                                         | `runtime_sandboxes_network` with `get`, `set`                     |
| `runtime_sandboxes_previews_create`, `_list`, `_rotate`, `_delete`                              | `runtime_sandboxes_previews` with the same verbs                  |
| `runtime_sandboxes_mount`, `runtime_sandboxes_mounts`, `runtime_sandboxes_unmount`              | `runtime_sandboxes_mounts` with `mount`, `list`, `unmount`        |
| `runtime_images_get`, `_tag`, `_delete`                                                         | `runtime_images` with `get`, `tag`, `delete`                      |
| `runtime_volumes_create`, `_get`, `_delete`                                                     | `runtime_volumes` with `create`, `get`, `delete`                  |
| `runtime_volumes_backup`, `_backup_get`, `_backup_policy`, `_backup_delete`                     | `runtime_volumes_backup` with `create`, `get`, `policy`, `delete` |
| `runtime_snapshots_create`, `_get`, `_delete`                                                   | `runtime_snapshots` with `create`, `get`, `delete`                |
| `runtime_secrets_set`, `_list`, `_delete`                                                       | `runtime_secrets` with `set`, `list`, `delete`                    |
| `runtime_account_get`, `runtime_limits_get`, `runtime_referrals_get`, `runtime_account_sso_get` | `runtime_account` with `get`, `limits`, `referrals`, `sso`        |
| `runtime_usage_compare`                                                                         | `runtime_account` with `compare`                                  |
| `runtime_support_message`, `_read`                                                              | `runtime_support` with `message`, `read`                          |
| `runtime_feedback_submit`, `_list`                                                              | `runtime_feedback` with `submit`, `list`                          |

On 24 September 2026 every tool took its product's name, as the CLI spells it,
with no aliases: `runtime_exec` became `runtime_sandboxes_exec`,
`runtime_sandboxes_create` became `runtime_sandboxes_create`, and so on. A call to
one of those names fails, and its error names the call that replaces it.

## A typical session

1. Choose a unique `idempotencyKey` before creating. Call
   `runtime_sandboxes_create` with that key. Check that the returned state is
   `running` before executing anything. The free usage is spent first, then prepaid credit.
2. `runtime_sandboxes_files_write`, then `runtime_sandboxes_exec` with `{"id": "<sandbox id>", "command": "python3 main.py"}`
   (or `"command": ["python3", "main.py"]` to run it without a shell).
   Add `"user": "root"` to run it as root without `sudo` in front.
   Give each write that accepts `idempotencyKey` its own key; do not add
   unsupported fields to other tools. Check `exitCode`, `timedOut`, output and
   truncation flags; tool or HTTP success alone does not prove program success.
   `runtime_sandboxes_exec` returns `stdoutBytes` and `stderrBytes`, the full size
   of each stream; `truncated` is `true` when part of the output is not in the
   result. The result holds the first and last 64 KiB of each stream. Over MCP, output over
   16,000 characters in all keeps each stream's beginning and end within its
   share of the output budget; even a long first line may be shortened.
   Quotes, backslashes and control characters can shorten it further, because
   escaped output must also fit the complete serialized response budget.
   `outputCut` says how many characters of each were cut. When the result
   includes `processId`, read the existing process with `runtime_sandboxes_process`
   and `"action": "read"`, using its output cursors. For a future command whose
   full output you need, save it to a file and read it in parts with
   `runtime_sandboxes_files_read`. Do not run a command again just to recover
   output: its changes may already have happened.
3. For a server or a long job, `runtime_sandboxes_exec` with `"background": true`, then
   `runtime_sandboxes_process` with `"action": "read"` to follow its output.
4. `runtime_sandboxes_manage` with `"action": "delete"` when done, even if a step
   failed. A stop keeps the disk, billed until it is deleted; delete unless the
   owner's task needs the sandbox again. Confirm it is gone before reporting
   cleanup complete. Export needed outputs before deleting.

**Retries.** When a tool accepts `idempotencyKey`, choose and record a unique
key **before the first call** and pass it explicitly. After a lost reply, reuse
that key with identical input.

A key the server generated for an omitted field cannot be recovered from a lost
reply, so do not repeat that write blindly: read the original resource first.
The SDKs keep their own retry key during a call; this guidance is for direct MCP
calls.

**Errors.** Follow error codes and hints.

- Back off with a bounded deadline on `no_capacity`, `busy` or
  `host_unavailable`, keeping the original write key and input.
- Do not keep retrying `fork_unavailable`, `previews_unavailable` or
  `unavailable`: an operator has switched that capability off.
- If a create stops before becoming ready, read that sandbox's `stopReason` and
  report the failure. Do not call it running or loop over new creates.
- For support or feedback, send a sanitized summary and request ID, never
  credentials or private code and file contents.

## Pause and wake

`runtime_sandboxes_manage` with `"action": "pause"` saves files and memory, and
`"wake"` restores them. Each sandbox keeps only its latest
state, not a history of billed snapshots.

A wake never silently substitutes a fresh boot: missing memory images refuse
it. A full host can also refuse a wake; the paused data remains and no compute
is charged for the failed attempt. See [pricing](./pricing) for paused storage
and retention.

A paused sandbox also wakes by itself when `runtime_sandboxes_exec`, a file or terminal
tool, or a visit to a shared port reaches it, unless it was created with
`autoWake: false`. A sandbox pauses itself after 300 seconds with nothing
happening in it. A process due on a timer also wakes a sandbox that paused for being idle,
unless it has `wakeOnTimers: false`. `"action": "update"` changes `autoWake`,
`wakeOnTimers`, `idlePauseSeconds`
(60 to 86,400 seconds; 0 is never), `name` and
`labels`; `"persist"` keeps a paid sandbox running while credit lasts.
`runtime_sandboxes_create` with `name` and `getOrCreate: true` returns the
sandbox that already has the name, woken if paused, instead of `name_taken`.

## Domains, TCP ports, addresses and the tunnel

They need a kept top-up, and a dedicated address credit; see [networking](./networking).

- `runtime_domains` (`add`, `verify`, `list`, `remove`): serve a sandbox's port
  at your own hostname.
- `runtime_ports` (`open`, `list`, `close`): a public TCP port to a sandbox.
- `runtime_ips` (`reserve`, `list`, `release`): a dedicated outbound
  address.
- `runtime_networks_wireguard` (`create`, `get`, `add_peer`, `rotate_peer`,
  `remove_peer`): the WireGuard tunnel. `add_peer` without `publicKey`
  generates the key pair and returns the private key once, in `config`.
- `runtime_networks_upstream_proxy` (`get`, `set`, `remove`): send the
  sandboxes' outbound connections through your own proxy.
- `runtime_networks_private` (`get`, `set`): with `enabled: true`, your
  sandboxes reach each other at `<name>.sandbox.internal:<port>` over TCP.
  Needs a kept top-up; free.
- `runtime_networks_signed_requests` (`get`, `set`): with `enabled: true`,
  your sandboxes can sign their HTTP requests as Runtime's agents with Web Bot
  Auth ([how](./networking#signed-requests)). Needs credit; free.


---

<!-- https://withruntime.com/docs/migrate -->

# Switch to Runtime from another sandbox provider

Move your sandbox code to Runtime in one pass, test it on the free usage, and see what you save each month.

Your model, prompts and application stay as they are; only the sandbox calls
change. For a project with no sandbox yet, start with [Get started](./start).

## Give your agent one instruction

> Move this project to Runtime Cloud: read https://withruntime.com/llms.txt and
> follow it.

The agent follows the steps below and keeps going until your real job runs on
Runtime. It ends with your monthly saving in dollars, and what is left for you
to do before going live. It tests without credit. It asks before going on once
the free usage is used. It never touches your old provider's account.

**Why teams switch:**

- **You pay for the CPU you use.** $0.025 per active vCPU-hour, measured, and
  $0.0075 per reserved GiB-hour of memory. No plan fee, and no one-minute
  minimum.
- **The calls map one to one.** Create, exec, files and stop have direct
  equivalents (table below). Code written for E2B, Daytona, Vercel Sandbox or
  Blaxel, Morph and others runs after changing one import.
- **Pause keeps memory.** A paused sandbox wakes where it left off, kept while a
  paid account has credit. A fork copies a running sandbox with its memory
  and processes.
- **More is built in.** A desktop, a code interpreter, custom images, volumes,
  and preview URLs that are private by default.
- **No API key to copy.** One browser approval connects the CLI, SDKs and MCP.
- **Test it free.** 100 free hours of a 1 GB machine, no card, up to four running at the same time.
  A sandbox without credit reaches ports 80 and 443 and shares previews privately, with
  a token; other outbound ports and public previews need paid credit.

The [comparison pages](./e2b-alternative) work through the cost of the same job
on each provider.

## 1. Find the old provider's calls

Read the project before changing it:

- dependency manifests and lockfiles;
- provider imports and sandbox configuration;
- creation calls, command execution, file access, background processes and
  cleanup;
- the names of environment variables, never their values;
- the framework and its version.

A framework's tool integration is not its sandbox backend. Adding an MCP tool
does not redirect a framework's local shell or filesystem operations.

## 2. Check what the project needs

**Most projects map straight across.** Check whether the application needs
Docker, root access, WebSockets, browser sessions, custom images, GPU support,
snapshots or region guarantees. On Runtime:

| The project needs       | Runtime                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Root                    | Passwordless `sudo` inside the sandbox                                                                                   |
| Docker                  | Docker Engine and Compose with `sudo enable-docker` ([environment](./sandbox-environment#docker))                        |
| SSH or an editor        | `runtime sandboxes ssh`, and `<id>.runtime` in VS Code or JetBrains ([SSH and editors](./editors))                       |
| A port on your machine  | `runtime sandboxes port-forward <id> 5432`, any TCP port, over the API                                                   |
| WebSockets              | Supported, including through a preview                                                                                   |
| A browser               | Playwright's Chromium installs in two commands, or use the [desktop](./products)                                         |
| Custom images           | Build from a package list, any public or private image, or a Dockerfile                                                  |
| Snapshots and forks     | Keep files, memory and running processes                                                                                 |
| A public URL            | A preview: an HTTPS address for one port                                                                                 |
| Other ports outbound    | Paid accounts reach every port, raw sockets included ([environment](./sandbox-environment#the-network))                  |
| API keys in the sandbox | Secrets: a placeholder in the sandbox, the value added by the proxy ([security](./security#secrets-sandboxes-never-see)) |

Do not represent a missing feature as supported. If the project needs something
Runtime does not offer, tell the owner which call before you remove it, and
send it as feedback. We build next from these reports:

```bash no-run
npx withruntime feedback --kind migration_blocker --competitor E2B \
  "Our evaluation jobs need X"
```

## 3. Connect and prove it

```bash no-run
npx withruntime login --no-browser
npx withruntime sandboxes run -- echo hello
```

The first command prints a link and a code: show them to the owner and wait for
their approval of **Connect agent**. The second must print `hello` and exit 0.
[Get started](./start) has the details.

## 4. Replace the calls

**Replace every call and leave no fallback.** Work on a branch, so git keeps the
old code. Then:

- Map create, readiness, exec, read and write, and stop to Runtime (table
  below).
- Remove the old provider's SDK, its client setup and its settings from the
  code.
- Test within the free usage. Once it is used up, sandboxes run on the
  account's credit by themselves. Check what is left with
  `npx withruntime usage`, and ask the owner before going on.
- Use one sandbox per isolated task or tenant, not a shared global sandbox.
- Choose an idempotency key before a write that accepts one, and reuse it with
  identical input after a lost response; a new key can run the work twice. The
  SDKs keep the same key for retries within a call. Across calls or restarts,
  choose and keep your own.
- Pass argument arrays rather than shell commands built from untrusted strings.

**From Daytona or Vercel Sandbox:** change the import to `withruntime/daytona`
or `withruntime/vercel` (Python `withruntime.daytona`, `withruntime.vercel`).
Their `stop()` keeps the disk to start again, as it does there, so it pauses the
sandbox; `delete()` ends it. See [JavaScript](./javascript) and
[Python](./python).

**From Blaxel:** change `from "@blaxel/core"` to `from "withruntime/blaxel"`
(Python `from blaxel.core import SandboxInstance` to
`from withruntime.blaxel import SandboxInstance`). Standby becomes a pause that
keeps memory and processes after 300 seconds idle, and the next call wakes the
sandbox. Sessions carry over as
Runtime's [sandbox sessions](./javascript#a-sandbox-from-a-browser). A call
Runtime handles differently, such as drives or schedules, throws
`NotSupportedError` naming what to use instead.

- A Blaxel workspace key sees every sandbox; a Runtime key sees the ones it
  made unless an owner or admin makes it account-wide
  (the API keys page, or `runtime keys create --account-wide`). Give services
  that share sandboxes account-wide keys
  ([keys in a team](./teams#keys-in-a-team)).
- Without credit, a sandbox is at most 2 vCPU and 4096 MB; `memory: 8192` needs paid
  credit.
- An image other than Blaxel's own templates must be a ready Runtime image of
  the same name: `npx withruntime images build --dockerfile Dockerfile --name <name>`.
- Blaxel's preview token header (`X-Blaxel-Preview-Token`) and parameter
  (`?bl_preview_token=`) are accepted.

**From Morph:** change `from "morphcloud"` to `from "withruntime/morph"`
(Python: `morphcloud` to `withruntime.morph` in the imports, so
`from withruntime.morph import MorphCloudClient`).
`MorphCloudClient`'s snapshots, instances, `setup`, `branch`, `pause`,
`resume`, `exec` and `exposeHttpService` work as they are; metadata become
labels. `stop` deletes the sandbox, as on Morph. Give `ttlSeconds` at
`instances.start` (60 to 86400): Runtime cannot add a time limit later. An
HTTP service with `auth_mode: "api_key"` is a private preview: send its token
(`instance.native.previews.get(port)`) as `x-runtime-preview-token`. Morph's
SSH calls refuse; use `npx withruntime sandboxes ssh <id>`. In Python,
`set_ttl` moves a time limit later but never adds or shortens one, and a
snapshot's `ttl_seconds` is whole days. Commands run as the user `runtime`
(with `sudo`), not root, so write to `/workspace` or `/tmp`.

**From Modal Sandboxes:** change `from "modal"` to `from "withruntime/modal"`
(Python `import modal` to `from withruntime import modal`), SDK 0.25.0 and
later (Python 0.23.0). Modal's own sandbox examples run unchanged where they
use none of what is refused below, and no Modal
token is needed or sent. Commands run as root, as in a Modal container. A
`timeout` ends the sandbox, and an `idle_timeout` pauses it with its memory
kept until the next call wakes it. A Function with a `schedule` deploys as a
[job](./jobs#modal) (SDK 0.36.0, Python 0.34.0). GPUs, other Modal Functions, named secrets,
volumes made on first use, sidecars, connect tokens and directory snapshots
throw `CompatibilityError` before anything is created, naming what to use
instead ([Modal](./modal-sandbox-alternative#what-the-drop-in-refuses)).

**From E2B:** change `from "e2b"` to `from "withruntime/e2b"` (Python
`from withruntime.e2b import ...`, SDK 0.4.0 and later). Errors stay E2B's:
`commands.run` throws `CommandExitError` (Python `CommandExitException`) on a
non-zero exit and `TimeoutError` (Python `TimeoutException`) past its timeout,
so keep your `try`/`catch`. A call Runtime handles differently throws
`NotSupportedError` naming what to use instead. Without credit a shared port is private, so `getHost(port)` throws `PublicPreviewNotAllowedError` (Python
`PublicPreviewNotAllowedException`) instead of returning a host nobody can
reach: while you test, open
`(await sandbox.runtime.previews.create(port)).urlWithToken` instead, or send
its token in the `x-runtime-preview-token` header.

An E2B template becomes a Runtime image of the same name, built once from the
same Dockerfile:

1. Build it: `npx withruntime images build --dockerfile e2b.Dockerfile --name <template>`.
   Its `WORKDIR` is where commands start, as on E2B. A start or ready command
   from `e2b.toml` is not carried over; start it with
   `commands.run(cmd, { background: true })` after the create.
2. Keep the create as it is: `Sandbox.create("<template>")`, with or without
   E2B's `team/` prefix and a `:tag`, starts from that image, and `getInfo()`
   reports the template by the name you gave.

A `timeoutMs` (Python `timeout`) is kept by Runtime's server, up to 24 hours,
and `kill()` deletes the sandbox, as on E2B. With no timeout, E2B's 300 seconds
ends in a pause rather than a delete, so call `kill()` when the work is done.

**From Cloudflare's Sandbox SDK (0.x):** change `from "@cloudflare/sandbox"`
to `from "withruntime/cloudflare"` in both the `getSandbox` import and the
`export { Sandbox }` line, delete the `containers` block from the Wrangler
config (keep the `Sandbox` Durable Object binding and its migration), and store
a key with `npx wrangler secret put RUNTIME_API_KEY` (SDK 0.18.0 and later).
The Worker's `getSandbox(env.Sandbox, name)` then reaches a Runtime sandbox
kept for that name. Backups, tunnels, terminals and outbound interception
refuse by name and say what to use instead; a sandbox holds at most 4 code
contexts ([Cloudflare](./cloudflare-sandbox-alternative#change-the-import)).

**From Fly Machines:** code that calls Fly's Machines API (`api.machines.dev`)
runs on Runtime after one address change. Run `npx withruntime fly-api`, which
serves the Machines API on `http://127.0.0.1:4280` as your Runtime login, and
point the client there: `FLY_API_HOSTNAME` in Fly's own examples,
`FLY_FLAPS_BASE_URL` for Fly's Go client (fly-go), or the base URL of your HTTP
client. On 18 October 2026 we ran the 22 curl examples on Fly's
[Machines API pages](https://fly.io/docs/machines/api/machines-resource/)
unchanged this way, and fly-go 0.11.6's flaps client unchanged. A Node service
can answer the same calls itself with `machinesApi()` from `withruntime/fly`, a
fetch handler. Your Fly token is never sent anywhere; to run as another Runtime
key, send it (`rtcloud_...`) as the bearer token. Served on anything but
`127.0.0.1`, every request must carry its own Runtime key.
`npx withruntime compare --from fly-machines` prices your usage at Fly Machines'
rates, and `npx withruntime switch --from fly-machines` records the switch.

- A machine is a sandbox, an app a label on it. Its `config.image` is built
  once into a Runtime image, with Fly's `init` (`exec`, `entrypoint`, `cmd`)
  and `files`, and the image's command is the machine's main process.
- Handled: apps, create, get, list (by `metadata.*`), update (env, metadata
  and restart policy), delete (`force`), start, stop, suspend, restart, wait,
  exec, signal, ps, events, versions, metadata and leases.
- The restart policy is kept: `always` and `on-failure` (up to `max_retries`,
  10 by default, in five minutes) start the main process again when it exits,
  and `no` lets the machine stop. A main process that exits stops the machine,
  and `auto_destroy` deletes it.
- `suspend` keeps the main process running, and `stop` keeps the disk; `start`
  of a stopped machine runs the main process again. Fly resets a stopped
  Machine's root disk.
- `services` (and cordon), `mounts`, `checks`, `processes`, GPUs, `files` from
  secrets and regions other than `iad` return 400 naming Runtime's alternative
  (previews, volumes, an image ready check, secrets), before anything is made.
  A size change in `update` says plainly when it is not available. Runtime
  runs in one region, us-east in northern Virginia; Fly's `iad` is Ashburn,
  Virginia.

### 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()`, Blaxel `SandboxInstance.create()`, Modal `Sandbox.create(app=...)`, Cloudflare 0.x `getSandbox(env.Sandbox, id)`, Sprites `client.createSprite(name)`               | `Sandbox.create()` while you test                                                                                                  |
| E2B `sbx.commands.run(cmd)`, Daytona `sandbox.process.exec(cmd)`, Vercel `sandbox.runCommand(cmd, args)`, Blaxel `sandbox.process.exec({ command })`, Modal `sb.exec(*args)`, Cloudflare `sandbox.exec(cmd)`, Sprites `sprite.execFile(cmd, args)` | `sbx.exec(cmd)` or `sbx.exec([cmd, ...args])`                                                                                      |
| E2B `CommandExitError` on a non-zero exit, once you port to `withruntime` (the `withruntime/e2b` import keeps throwing it)                                                                                                                         | `exec` returns `exitCode` (and `timedOut: true` on a timeout) without throwing; `exec(cmd, { check: true })` throws `CommandError` |
| 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()`, `destroy()`                                                                                                                                                                                         | `sbx.delete()`; `sbx.stop()` keeps the disk for `restart`                                                                          |
| `setTimeout`, `timeout` (optional: a sandbox runs while it works with none)                                                                                                                                                                        | `timeoutSeconds` at create, `sbx.extend(seconds)`                                                                                  |
| Daytona `auto_stop_interval`, Modal `idle_timeout`                                                                                                                                                                                                 | `idlePauseSeconds` at create or with `sbx.update()`                                                                                |
| Running past an hour, or a long session                                                                                                                                                                                                            | Nothing: with no `timeoutSeconds` it runs while it works; `persistent: true` (paid) keeps it up even when idle                     |
| Pause and resume                                                                                                                                                                                                                                   | `sbx.pause()` and `sbx.wake()`                                                                                                     |
| E2B `lifecycle.autoResume`, Blaxel standby                                                                                                                                                                                                         | On by default: a request to a paused sandbox wakes it (`autoWake`)                                                                 |
| Cloudflare 0.x `getSandbox(env, name)`, Modal `Sandbox.from_name`, Blaxel `createIfNotExists`, Sprites by name                                                                                                                                     | `Sandbox.getOrCreate(name)`                                                                                                        |
| A code interpreter (`run_code`)                                                                                                                                                                                                                    | `sbx.interpreter.run(code)`                                                                                                        |
| A public URL for a port (`getHost`, `get_preview_link`, `domain`)                                                                                                                                                                                  | `sbx.previews.create(port)`, private with a token; `visibility: "public"` on paid                                                  |
| 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 sandboxes <verb>` (`runtime sandboxes <verb>`
  installed), and MCP tools are `runtime_sandboxes_*`, `runtime_sandboxes_exec`,
  `runtime_sandboxes_files_*`.
- The 0.1.0 HTTP routes were removed; each returns 410 and names its
  replacement.

## 5. Make it work without credit

**Run the project's own tests, then its real job, not a stand-in.** Use the
same inputs, dependency versions, output checks and deadline as before. Fix what
fails and run again, until everything that passed on the old provider passes on
Runtime. A first command that prints `hello` checks the connection; it does not
finish the switch.

- Check that outputs match, not only that commands succeeded.
- Check exit codes, failures and retries.
- Record completion time over several runs, startup included.
- List sandboxes at the end (`npx withruntime sandboxes ls --json`) and stop any
  the test left running.
- If the job hits a limit without credit, stop and tell the owner which limit the error
  named and that adding credit lifts it. Do not shrink the job to fit.

## 6. Work out the saving

**Tell the owner what they save each month, in dollars, from measured usage.**

The quickest way is `npx withruntime compare --from <provider>`. It prices the
sandboxes you actually ran at that provider's published rates. It prints the
monthly saving, with the date the rates were checked. Over MCP, use
`runtime_account` with action `compare`. It prices sandboxes without credit at
the standard rates, and it says how many ran without credit. So the saving is
the one paid credit gives. `npx withruntime switch --from <provider>` records the
move. Credit the owner adds within 30 days of signing up is matched,
up to $1,000 in total ([welcome match](./pricing#welcome-match)). To work
it out by hand:

1. **Runtime's cost.** After the test runs, `npx withruntime usage --json` lists
   each sandbox with its measured `activeCpuSeconds`, `billedCpuSeconds` and
   `memoryGiBSeconds`. A sandbox without credit is charged nothing, so price the usage at
   the standard rates in [pricing](./pricing):

   ```text
   cost = billedCpuSeconds × $0.025 / 3,600 + memoryGiBSeconds × $0.0075 / 3,600
   ```

2. **The old provider's cost.** Use its own billing or usage records where you
   can see them. Otherwise price the same size and running time at its published
   rates; the comparison pages give each rival's rates and the date they were
   checked.
3. **Per job.** Divide each total by the successful jobs. Failed attempts and
   retries count in the total.
4. **Per month.** Saving = (old cost per job − Runtime cost per job) × jobs per
   month. Take the monthly volume from the project's logs, metrics or the old
   provider's bill; ask the owner only if none is visible. The percentage is the
   saving divided by the old cost; leave it out when the old cost is unknown.

Say which figures are measured and which are published rates, with their dates.
Never present an estimate as an invoice, or count free usage as a saving.
If Runtime is more expensive or lacks a needed feature, say so.

A report in this shape, with made-up volumes:

> Switched from E2B to Runtime on branch `runtime`. 40 test jobs passed with the
> same outputs. Runtime, measured: $0.00064 a job. E2B at its published rates
> (checked 25 October 2026): $0.00276 a job. At your 30,000 jobs a month,
> that is $19 on Runtime against $83 on E2B: you save about $64 a month (77%).
> Add credit at https://withruntime.com/account/billing before production
> traffic runs.

## 7. Go live

Open a pull request with the switch if you can, and tell the owner the steps
only they can take:

- The owner adds prepaid credit at
  [Usage & billing](https://withruntime.com/account/billing), any amount from
  $10. There is no subscription.
- The app needs a key where it runs: the owner creates one at
  [API keys](https://withruntime.com/account/keys) and stores it as
  `RUNTIME_API_KEY` in the app's secrets. The agent's own connection is for
  this machine only.
- The owner merges. Then check that `npx withruntime sandboxes ls` shows the
  app's sandboxes.
- Never spend paid credit on your own. Only the owner can decide to go on past the free usage.
- The old provider's account, keys and data are the owner's to close. Leave
  them as they are.
- Send feedback on anything that slowed the switch:
  `npx withruntime feedback "..."`. See
  [feedback and support](./feedback-and-support).


---

<!-- https://withruntime.com/docs/modal-sandbox-alternative -->

# Runtime vs Modal Sandboxes

Runtime gives each agent sandbox its own microVM kernel. It costs **84% less than Modal** for an agent that mostly waits on a model.

**Switch in one line.** Your Modal Sandbox code keeps working. Change the
import and set `RUNTIME_API_KEY`.

```ts no-run
import { ModalClient } from "withruntime/modal"; // was: from "modal"
```

```python no-run
from withruntime import modal  # was: import modal
```

Modal's own sandbox examples run on it unchanged, except the features
[listed below](#what-the-drop-in-refuses). Those stop with an error naming
Runtime's alternative.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $3.97 on Modal**. At 100,000 runs a month that is $63.89 against
$396.60, **$333 a month saved**.

Comparing more than two? [Modal Sandbox alternatives](/compare/modal-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Modal bills whichever is higher, the CPU a
  sandbox requested or the CPU it used. So a requested core is billed while it
  waits. Runtime measures the CPU your code actually uses, with a floor of a twentieth of a vCPU. There is no request to size in advance.
- **Waiting costs storage, not compute.** A Runtime sandbox left idle for 300 seconds pauses by
  itself and keeps its memory. It then pays $0.08 per GB (10⁹ bytes) a month
  until a request wakes it.
- **An uptime promise that pays itself.** Paid accounts are promised
  99% API uptime each month. A month below it returns 10% of that
  month's charges as credit. No claim is needed ([Uptime Promise](/legal/sla)).
- **Lower rates on both meters.** A vCPU-hour costs $0.025 on Runtime. Modal
  charges $0.1419 per physical core-hour, $0.071 per vCPU. Memory costs $0.0075
  per GiB-hour against Modal's $0.0240. Even with every CPU busy the whole
  time, the example job costs $1.33 on Runtime and $3.97 on Modal.
- **Its own kernel per sandbox.** A microVM puts a hardware virtualization
  boundary between sandboxes. Modal uses gVisor, a user-space kernel that
  intercepts system calls. See [security](./security).
- **Pause with memory, on every sandbox.** A paused Runtime sandbox wakes with
  its processes still running, kept while you have credit. Forks copy a running
  sandbox, memory and processes included.
- **Nothing to set up first.** One call creates a sandbox, with no app or
  project. Outside Modal, a Modal sandbox needs an App.
- **Teams at no extra charge.** Single sign-on over SAML or OIDC (Okta,
  Microsoft Entra ID, Google Workspace), SCIM, roles and an audit log come with
  every account ([single sign-on](./single-sign-on)). Modal puts SAML single sign-on and
  audit logs on its Enterprise plan.
- **Custom domains and a fixed address without a plan.** A paid account serves
  a sandbox port at your own hostname. It sends from a dedicated outbound
  address for $5 a month ([networking](./networking)). Modal's custom
  domains and static IP proxy come with its Team plan, $250 a month.
- **Keys the sandbox never sees.** Store an API key once. The sandbox holds a
  placeholder. Runtime's proxy adds the value only to HTTPS requests to the
  hosts you name. A prompt injection has nothing to leak ([security](./security)).
- **Your credit matched.** Credit you add within 30 days of signing up is matched, up to $1,000 in total
  ([welcome match](./pricing#welcome-match)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, private previews, a Linux desktop, metrics,
webhooks, OpenTelemetry export, S3, R2 and GCS bucket mounts and identity tokens for AWS and Google Cloud. Paid accounts add TCP
ports and WireGuard private networks. See [products](./products).

## At a glance

Modal's figures come from its public pricing and documentation, checked
25 October 2026.

|                | Runtime                                                                     | Modal Sandboxes                                                                                                        |
| -------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Isolation      | Firecracker microVM, own kernel                                             | gVisor, a user-space kernel that intercepts system calls                                                               |
| CPU billing    | $0.025 per vCPU-hour of measured CPU, with a small floor              | $0.1419 per physical core-hour (2 vCPUs), request or use                                            |
| Memory billing | $0.0075 per reserved GiB-hour                                       | $0.0240 per GiB-hour, request or use                                                                 |
| Plan fee       | None; prepaid credit from $10                                     | Starter $0 with $30 a month of compute; Team $250 a month |
| Free start     | 100 free hours of a 1 GB machine in the first 30 days, no card                          | $30 of compute a month on Starter                                                            |
| Session length | No time limit: runs while it works, pauses itself after 300 seconds idle | Up to 24 hours; snapshots carry state beyond that                                                                      |
| Setup          | One call; no app or project                                                 | A Modal App is needed outside Modal                                                                                    |
| Port URLs      | Private with a token by default                                             | Public to anyone with the URL                                                                                          |

## Cost for the same job

Take 1,000 runs of a sandbox with 2 vCPUs (one physical core on Modal) and
4 GiB. Each run lasts 60 seconds and keeps the CPU busy for 20 CPU-seconds. This
is an agent that spends most of its time waiting for a model.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
         Total                                        $0.64

Modal    CPU    1,000 × 60 s × 1 core × $0.00003942 = $2.37
         Memory 1,000 × 60 s × 4 × $0.00000667      = $1.60
         Total                                        $3.97
```

- **Saving:** 84%, or $3.33 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $396.60 on Modal.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on
  Runtime against $3.97 on Modal. At this size, Runtime is cheaper however busy the
  sandbox is.

A smaller request lowers Modal's figure. It also caps what the sandbox can
use when it needs more. Plan fees, storage, network, taxes and free credits are
left out of both. On Runtime, inbound traffic is free. Each account's first
100 GiB out a month is free. After that, outbound traffic costs
$0.02 per GB (10⁹ bytes). See [pricing](./pricing) for
Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Modal calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### Change one import

Runtime's SDK runs code written for Modal's Sandboxes, as this page describes
from version 0.25.0 (Python 0.23.0), for Modal's JavaScript SDK 0.11.1 and
Python SDK 1.6.2. Change the import and set `RUNTIME_API_KEY`:

```ts no-run
import { ModalClient } from "withruntime/modal"; // was: from "modal"
```

```python no-run
from withruntime import modal  # was: import modal
```

A Modal token is never needed or sent. Apps group sandboxes by name. Images
build from the same registry tags and Dockerfile steps. Commands run as
root, as in a Modal container. A `timeout` (`timeoutMs`) ends the sandbox. An
`idle_timeout` (`idleTimeoutMs`) pauses it with its memory kept, waking at
the next command, file call or tunnel request. Outbound domain and CIDR
allowlists, tunnels, tags, names, file calls and watches, filesystem snapshots,
and in Python memory snapshots work as Modal documents them. Each of Modal's
sandbox examples was run against Runtime on 18 October 2026, in both
languages.

### What the drop-in refuses

These stop with a `CompatibilityError` before anything is created. The
message names what to use on Runtime:

- **GPUs.** Runtime runs on CPUs.
- **Modal Classes, Dicts, Queues, web endpoints and Functions without a
  schedule.** Run the code in a sandbox. A Function with a `schedule` deploys
  as a [job](./jobs#modal).
- **Named secrets** (`Secret.from_name`, `secrets.fromName`). Runtime's
  [secrets](./security#secrets-sandboxes-never-see) are used without being seen. Store one with
  `runtime.secrets.set`, or pass values with `Secret.from_dict`
  (`secrets.fromObject`).
- **Secrets in image build steps.** A Runtime build keeps no secret. Use the
  secret when the sandbox runs instead.
- **Volumes made on first use** (`create_if_missing`, ephemeral volumes) and
  volume sub-paths. A Runtime [volume](./storage#attaching-a-volume) has a fixed size. Create it
  first, then mount all of it.
- **Sidecars.** Start a second sandbox and join both to a private network.
- **Connect tokens and custom domains** on a tunnel. Share the port as a
  private preview instead.
- **Directory snapshots and exit snapshots.** Take a filesystem snapshot
  before `terminate()`, then start new sandboxes from it.
- **Proxies and inbound CIDR allowlists.** Use Runtime's static outbound
  addresses and network rules.

`COMPATIBILITY.md` in each package lists every mapping.

### Or port the calls

Modal:

```python check
import modal
app = modal.App.lookup("my-app", create_if_missing=True)
sb = modal.Sandbox.create(app=app)
process = sb.exec("python3", "-c", "print(sum([125, 250, 375]))")
print(process.stdout.read())
sb.terminate()
```

Runtime:

```python
from withruntime import Sandbox
with Sandbox.create() as box:
    box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n")
    print(box.exec("python3 /workspace/invoice.py", check=True).stdout)
```

## When Modal may fit better

- **GPUs.** Modal sandboxes can use GPUs. Runtime runs on CPUs.
- **A wider platform today.** Functions and web endpoints sit beside sandboxes
  in the same account and SDK. Runtime has [scheduled jobs](./jobs) beside its
  sandboxes, but not functions or endpoints.

## Sources

Checked 23 September 2026; plan features checked 27 September 2026; port URLs checked 3 November 2026.

- [Modal pricing](https://modal.com/pricing)
- [Modal resources and billing](https://modal.com/docs/guide/resources)
- [Modal Sandboxes](https://modal.com/docs/guide/sandbox)
- [Modal security](https://modal.com/docs/guide/security)
- [Modal tunnels](https://modal.com/docs/guide/tunnels)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/morph-alternative -->

# Runtime vs Morph

Runtime runs each agent sandbox in its own microVM. For an agent that mostly waits on a model, it costs **62% less than Morph**.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $1.67 on Morph**. At 100,000 runs a month, that is $63.89 against
$166.67, **$103 a month saved**.

Comparing more than two providers? [Morph Cloud alternatives](/compare/morph-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Morph bills a machine's full size in MCUs for
  as long as it runs. Runtime measures the CPU your code actually uses. Time
  spent waiting on a model costs only a small floor, a twentieth of a vCPU.
- **Idle time bills only storage.** A Runtime sandbox pauses itself after 300 seconds
  with nothing happening in it. It keeps its memory and processes. While paused, the sandbox
  pays $0.08 per GB (10⁹ bytes) of saved state a month.
- **A written uptime promise.** Paid accounts get 99% API uptime a month,
  measured from outside. If a month falls short, 10% of that month's charges
  is returned as credit automatically ([Uptime Promise](/legal/sla)).
- **Cheaper even when busy.** With both CPUs working the whole time, the example
  job costs $1.33 on Runtime and $1.67 on Morph.
- **CPU and memory priced apart.** One MCU covers 1 vCPU, 4 GB of memory or
  16 GB of disk. A machine pays for whichever it needs most. On Runtime, you choose
  vCPUs and memory separately and pay for each.
- **No plan fee.** Morph's plans with included credit cost $40 or $250 a month.
  Runtime is prepaid credit from $10, with 100 free hours of a 1 GB machine in the first 30 days.
- **Secrets stay outside the sandbox.** Code inside sees a placeholder. The
  real key is added at the egress proxy, only on HTTPS to the hosts you allow
  ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Give an agent a read-only key or a daily spending
  limit per key. Cap any sandbox's total cost with `maxTotalCostMicros`. Every write takes an
  idempotency key, so a lost response never creates a second sandbox.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, snapshots and forks with memory, private
previews, a Linux desktop, metrics, webhooks, OpenTelemetry export, S3, R2 and
GCS bucket mounts, identity tokens for AWS and
Google Cloud, and free single sign-on. Paid accounts add custom domains, TCP
ports, dedicated outbound addresses and WireGuard private networks. See
[products](./products).

## At a glance

Morph's figures come from its public pricing and product pages. Last checked
25 October 2026.

|                  | Runtime                                                        | Morph                                                                                          |
| ---------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Isolation        | Firecracker microVM, own kernel                                | Full virtual machines                                                                          |
| CPU billing      | $0.025 per vCPU-hour of measured CPU, with a small floor | $0.05 per MCU-hour for the machine's size                                        |
| Memory billing   | $0.0075 per reserved GiB-hour                          | Inside the MCU: 4 GB per MCU                                                                   |
| Plan fee         | None; prepaid credit from $10                        | Developer free with no credit; Team $40 and Scale $250 a month |
| Free start       | 100 free hours of a 1 GB machine in the first 30 days, no card             | 1,000 MCUs with the $40 Team plan                                              |
| Snapshots, forks | Files, memory and running processes                            | Memory and disk; branches to many replicas                                                     |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most of its time
waiting for a model. On Morph, 2 vCPUs and 4 GB is 2 MCUs an hour.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
         Total                                        $0.64

Morph    Size   1,000 × 60 s / 3,600 × 2 MCU × $0.05 = $1.67
```

- **Saving:** 62%, or $1.03 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $166.67 on Morph.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $1.67 on Morph.

Plan fees, included credit, storage, network and taxes are excluded from both. On
Runtime, inbound traffic is free. Each account's first 100 GiB out a month
is free, then $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Morph calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

Or keep your Morph code and change one import:

```ts no-run
import { MorphCloudClient } from "withruntime/morph"; // was "morphcloud"
const client = new MorphCloudClient();
const snapshot = await client.snapshots.create({ vcpus: 2, memory: 4096, diskSize: 8192 });
const ready = await snapshot.setup("pip install pandas"); // cached after the first run
const instance = await client.instances.start({ snapshotId: ready.id });
console.log((await instance.exec("python3 -c 'import pandas; print(pandas.__version__)'")).stdout);
const { instances } = await instance.branch(4); // four copies, memory included
```

In Python, change `morphcloud` to `withruntime.morph`:

```python no-run
from withruntime.morph import MorphCloudClient  # was: from morphcloud import MorphCloudClient
client = MorphCloudClient()
snapshot = client.snapshots.create(vcpus=2, memory=4096, disk_size=8192)
ready = snapshot.setup("pip install pandas")  # cached after the first run
with client.instances.start(ready.id) as instance:
    print(instance.exec("python3 -c 'import pandas; print(pandas.__version__)'").stdout)
    branched, copies = instance.branch(4)  # four copies, memory included
```

Runtime's own SDK:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

## When Morph may fit better

- **Branching at scale.** Morph's Infinibranch branches a running machine,
  memory included, to hundreds of parallel replicas.
- **Development environments for people.** Morph Devboxes are shareable
  workspaces. They scale to zero when idle and keep their memory.

## Sources

Checked 23 September 2026; plan names and included MCUs reread 17 October 2026.

- [Morph Cloud pricing](https://cloud.morph.so/web/pricing)
- [Morph Devboxes](https://cloud.morph.so/web/product/devboxes)
- [Morph snapshots](https://cloud.morph.so/docs/documentation/instances/creating-snapshot)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/networking -->

# Custom domains, TCP ports, dedicated addresses and private networks

Six ways to connect sandboxes to the rest of your world and to each other. A
dedicated address needs credit on the account. The others need a kept top-up:
one paid and not refunded, because spammers abuse them. Without one, a request
returns `payment_required` (402) and says which ([pricing](./pricing#how-many-at-once)).
A custom domain or a TCP port also needs the sandbox it serves to be a paid one.

- **Custom domain:** a sandbox's web port at your own hostname, with HTTPS.
- **TCP port:** a public `address:port` for anything that is not HTTP, such as
  Postgres, Redis, MQTT or a game server.
- **Dedicated outbound address:** every sandbox in your account sends from one
  address of its own, so you can allow-list it.
- **Private network:** a WireGuard tunnel from your own network, in any cloud or
  on your premises, into your sandboxes (`runtime networks wireguard`). This is
  the only "tunnel" on this page. `runtime sandboxes ssh` and `port-forward` are
  a separate connection from your own computer ([SSH and editors](./editors)).
- **Sandboxes by name:** your sandboxes reach each other at
  `<name>.sandbox.internal`, free. It needs no tunnel. The CLI and MCP call it
  `networks private` (`runtime networks private on`). This is not the WireGuard
  private network above.
- **Your Tailscale network:** a sandbox joins your tailnet as a machine of its
  own, with your auth key.

None of them belongs to one sandbox alone, so each is its own product in the CLI,
the SDKs and MCP: `runtime domains`, `runtime ports`, `runtime ips` and
`runtime networks wireguard`; `runtime.domains`, `runtime.ports`, `runtime.ips`
and `runtime.networks.wireguard`; `runtime_domains_*`, `runtime_ports_*`,
`runtime_ips_*` and `runtime_networks_wireguard_*`. A tailnet belongs to one
sandbox: `runtime sandboxes tailscale`, `sbx.tailscale` and
`runtime_sandboxes_tailscale`. A dedicated IPv4 address and a tunnel each cost
$5 per 30-day month, charged in proportion to funded time. IPv6,
custom domains, TCP ports and joining a tailnet are included. See [pricing](./pricing).

## Private preview links

A [preview link](./sandbox-environment) shares an HTTP port without adding a
custom domain. Keep it private when only selected visitors should connect.
Anyone holding its token can use it until it expires or you rotate it.
Revoking the key or sandbox session that was handed a token, or removing the
member whose key it was, also refuses every token for that preview immediately,
as a rotate does. Read the preview again to get a new one.

A page on another preview cannot open a private preview with the visitor's
cookie. A link, image, frame or request from another sandbox's preview is
refused with `origin_not_allowed`. These are allowed: another port of the same
sandbox, a site listed in `embedOrigins`, and a request that sends the token itself.

The API can issue a token with a relative `ttlSeconds` lifetime, or an absolute
`expiresAt` ISO timestamp. If you set both, the earlier deadline wins. Tokens
issued through a sandbox session also end when that session ends. An absolute
deadline is never rounded past the time you requested. Read the returned
`tokenExpiresAt` for the actual end time. Each create and read signs its own
token. So a list shows a different token and `tokenExpiresAt` than the create
did. The token you already hold keeps working until its own expiry or a rotate.
See [private preview tokens](./api#private-preview-tokens) for the supported API and MCP inputs.

### Search engines

No preview address is ever indexed by a search engine, private or public. Every
response under `runtimehost.com` carries `X-Robots-Tag: noindex, nofollow`, in
place of any header your server sends. `/robots.txt` on a preview address is
Runtime's own file, not your server's. For a site that should appear in search
results, add a [custom domain](#custom-domains). It serves your site's own
headers and `robots.txt` unchanged.

## Custom domains

```bash no-run
runtime domains add app.example.com <sandbox> 3000
```

The response lists two DNS records to set at your DNS provider:

| Record | Name                                 | Value                     | What it does              |
| ------ | ------------------------------------ | ------------------------- | ------------------------- |
| TXT    | `_runtime-challenge.app.example.com` | `runtime-verify=<token>`  | Proves the name is yours  |
| CNAME  | `app.example.com`                    | `domains.runtimehost.com` | Sends visitors to Runtime |

A name with no subdomain (`example.com`, `example.co.uk`) cannot have a CNAME.
The response gives an A record (and an AAAA for an IPv6 address) with the
addresses to set instead. Then check:

```bash no-run
runtime domains verify app.example.com
```

The name goes live when the TXT record matches. The first visit gets its
certificate from Let's Encrypt, which takes a few seconds. As for a
[preview link](./sandbox-environment), your server must listen on `0.0.0.0` or
`localhost` inside the sandbox. Start it with `spawn`, which keeps it running.
WebSockets work. A paused sandbox is woken by a visit, as with a preview.

- **Ownership is the TXT record.** A CNAME pointing at Runtime proves nothing.
  So a record someone forgot to delete cannot be used to take their name. Each
  claim has its own token.
- **The DNS owner wins.** If another account proves the same name later, it
  takes the name over and your claim ends.
- **To move the name to another sandbox or port,** run `add` again with the new
  target. To stop serving it, run `runtime domains rm app.example.com`. Either
  change takes effect before the command returns. This includes open connections.
- **Limits:** 50 domains per account, 20 added a day. Certificates are issued
  for proved names only.
- **Reports** reach Runtime through the `X-Runtime-Report` header on every
  response and the abuse address, as for previews. Runtime can take a name down.
  It stops serving immediately and stays down for every account.

### On an App

An App serves your domain through every deploy and rollback, with no
certificate fetched on a visit. The name's certificate is issued, checked and
served before you point the name at the App.

```ts no-run
import { Runtime } from "withruntime";

const runtime = new Runtime();
const domain = await runtime.domains.add({ hostname: "example.com", appId: "<your App's id>" });
console.log(domain.records);
```

The response lists three records:

| Record | Name                             | Value                      | What it does                               |
| ------ | -------------------------------- | -------------------------- | ------------------------------------------ |
| TXT    | `_runtime-challenge.example.com` | `runtime-verify=<token>`   | Proves the name is yours                   |
| CNAME  | `_acme-challenge.example.com`    | `<token>.<challenge zone>` | Lets Runtime get and renew its certificate |
| A      | `example.com`                    | the App's addresses        | Sends visitors to the App                  |

Set the TXT and the `_acme-challenge` CNAME first, then verify. Within a few
minutes, `certificate.ready` turns true on `runtime.domains.get`. Every Runtime
router now serves a checked certificate for the name. Only then change the A
record (or the CNAME, for a subdomain such as `www`). That way the first visitor
already gets HTTPS. Keep the `_acme-challenge` CNAME. Renewals use it, at the
latest 30 days before the certificate expires. If the first certificate
authority fails, renewals use a second one. A deploy or a rollback never changes
DNS or a certificate.

## TCP ports

```bash no-run
runtime ports open <sandbox> 5432
# 203.0.113.10:23456
psql "postgres://app@203.0.113.10:23456/app?sslmode=require"
```

A TCP port carries raw TCP from a public address and port to a port inside the
sandbox. Opening the same sandbox and port again returns the same public port.

- **Anyone who knows the address can connect.** Use your service's own
  authentication and TLS.
- **Only TCP is carried.** UDP (most game servers' own traffic, QUIC) is not.
- **Limits:** 5 ports per sandbox, 20 per account and 50 opened a day. Each
  sandbox's ports share 256 open connections, 50 new connections a second, and
  32 connections from any one client address.
- **Speed:** each sandbox's ports move up to 500 Mbit/s each way, 200 Mbit/s once
  10 GiB has moved at that speed, and 500 GiB a day, in and out together.
  When ports of several sandboxes on one address send at the same time, they
  share 500 Mbit/s equally.
- **Use the address each port was given.** A port keeps its address for as
  long as it is open. Ports opened later may get a different address from
  earlier ones. So read it from the response (`address`, `connect`). Do not
  assume one address for all of them.
- **A closed port is held for a day** before anyone else can be given it. So a
  client still pointed at it never reaches someone else's service.
- **A paused sandbox is woken** by a connection. Its connections end when it
  stops, pauses or is deleted.
- **Data the sandbox sends back is outbound traffic.** It counts against the
  account's monthly allowance, then costs $0.02 per GB. This applies to
  sandboxes created from 5 October 2026. Data that clients send in is free. See
  [pricing](./pricing#network-products).
- `runtime ports ls` lists them. `runtime ports close <portId>` closes one, and
  its open connections, before it returns. A port you open listens before its
  address is returned.

## Dedicated outbound addresses

```bash no-run
runtime ips reserve
# 203.0.113.50
```

From then on, every sandbox in your account sends from that address, on every
port. A database, an API provider or a firewall can then admit exactly you. No
other account sends from it while you hold it.

- One IPv4 address per account, and one IPv6 with `--ipv6`.
- Your sandboxes send only in the address families you hold. With an IPv4
  address and no IPv6 one, a site that has no IPv4 address is refused with
  `address-family`. It is never reached from a shared IPv6 address.
- If funding expires, traffic stops while the reservation remains yours. There
  is no fallback to a shared address and no charge for the unpaid interval.
- `funded` reports whether traffic is funded now. `fundedUntil` is the last
  funded-through time and may be in the past; it is null when no meter exists.
  `rateMicros` and `rateUnit` give the price of the reserved address. If renewal
  is blocked, check your balance, spending limits and permissions.
- `runtime ips release <addressId>` gives it back. Your sandboxes send from the
  shared addresses again immediately. A released address is held for 30 days
  before any other account can get it. Remove it from your allow-lists first.
- Addresses are added to Runtime as accounts need them. If none is free, the
  response is `no_capacity` (503). Write to support.
- An address is served from one place. So while you hold one, your sandboxes
  start only where it can send from. If there is no room there now, a create
  returns `no_capacity` (503). It does not start a sandbox that would send from
  a shared address, so retry with the same idempotency key.

## Your own upstream proxy

Your sandboxes' outbound connections can go through your own HTTP or HTTPS
proxy, after Runtime's own rules allow them. Your proxy's controls and logs apply.

```bash no-run
runtime networks upstream-proxy set http://proxy.example.com:3128 --host '*.internal.example.com'
runtime networks upstream-proxy get
runtime networks upstream-proxy remove
```

It is a setting of the whole account, so it lives under `runtime networks`, as
`runtime.networks.upstreamProxy` in JavaScript, `runtime.networks.upstream_proxy`
in Python and `runtime_networks_upstream_proxy_*` in MCP. The CLI and SDK
commands were added in `withruntime` 0.7.0. The API and MCP tools work now.
Without `--host`, every connection goes through it. If the proxy fails, the
connection fails. Nothing goes around it.
[Security](./security#your-own-proxy) has the rest: proxy credentials, what your
proxy sees, and UDP.

## Reach your other sandboxes by name

Turn it on once, and every sandbox in your account can reach the others by name,
over TCP, on any port. For example, a database in one, a queue in another, and
the agent in a third. It is free, and it stays off until you turn it on. The
setting is named `networks private` in the CLI, the API (`/v1/networks/private`)
and MCP (`runtime_networks_private`). It has nothing to do with the WireGuard
[private network](#private-networks) below, which joins your own network to
your sandboxes.

```bash no-run
runtime networks private on
# then, in any of your sandboxes:
psql -h db.sandbox.internal -p 5432 app
curl http://web.sandbox.internal:3000/
runtime networks private status
runtime networks private off                    # open connections are cut within seconds
```

- **The name** is the one the sandbox was created with (`name`), at
  `<name>.sandbox.internal`, or its id, at `<id>.sandbox.internal`. Names are
  matched without regard to case. Use letters, digits, dots and dashes. If two
  of your sandboxes have the same name, use the id.
- **Only your own sandboxes respond.** Another account's sandbox of the same
  name is never reached. Nor is anything outside Runtime. `.sandbox.internal`
  names are never looked up in public DNS.
- **Any port** the target listens on, except Runtime's own relays inside every
  sandbox (10800, 10802 and 10853). TCP only.
- **A paused sandbox wakes** when a connection reaches it. A stopped one does
  not: start it first.
- **A new sandbox is reachable immediately** after it starts running, and can
  connect to your other sandboxes right away.
- **Open connections:** up to 256 to any one sandbox and 1,024 across your
  account. Past either, new connections return `429` with
  `X-Runtime-Egress: private-network-rate-limited`.
- **New connections:** up to 1,000 a second across your account (2,000 at
  once) and 500 a second to any one sandbox (1,000 at once). A connection
  over the rate waits for its turn. It returns `429` with
  `X-Runtime-Egress: private-network-rate-limited` only when its turn is more
  than 10 seconds away.
- **A kept top-up, for paid sandboxes.** An account without one is told so when
  it turns this on. A connection from a sandbox without credit is refused with
  `private-network-paid-only`. A sandbox with its internet off also reaches no
  other sandbox.
- **Not billed, and not limited as uploads:** these connections are not
  outbound traffic. They do not count toward a sandbox's upload speed limits or
  its daily network amount. Each sandbox can be reached for 100 GiB a day, in
  and out together, from all of its callers. Past that, new connections to it
  return `429` with `X-Runtime-Egress: private-network-quota-exhausted` until the
  window ends.

From the SDKs, `runtime.networks.private` (MCP: `runtime_networks_private_*`):

```ts check
import { Runtime } from "withruntime";
const runtime = new Runtime();
await runtime.networks.private.set({ enabled: true });
const { enabled } = await runtime.networks.private.get();
```

```python check
runtime.networks.private.set(enabled=True)
```

A program that connects directly sees a refused connection close immediately.
Through the proxy (`curl -x "$HTTP_PROXY"`, or any program that reads
`HTTP_PROXY`), the response's `X-Runtime-Egress` header says why:
`private-network-off` (turn it on), `private-network-no-sandbox` (no sandbox of
yours has that name or id), `private-network-not-running` (it is stopped, or
could not be woken), or `private-network-port-reserved`.

## Signed requests

Turn it on once, and your sandboxes can sign their HTTP requests as Runtime's
agents with Web Bot Auth. Sites behind Cloudflare and other bot managers can
then tell them from anonymous traffic ([Outbound traffic](./egress#signed-requests)).
It is free. It needs credit on the account, and it is off until you turn it on.
The setting is `networks signed-requests` in the CLI, the API
(`/v1/networks/signed-requests`) and MCP (`runtime_networks_signed_requests_*`).

```bash no-run
runtime networks signed-requests on
# then, in any of your sandboxes, the headers for one site:
TOKEN=$(curl -s -H "Authorization: Bearer $RUNTIME_ID_TOKEN_REQUEST_TOKEN" \
  "$RUNTIME_ID_TOKEN_REQUEST_URL?audience=https://withruntime.com/signed-requests" |
  python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')
curl -s -H "x-runtime-sandbox-identity: $TOKEN" \
  "https://withruntime.com/api/signed-requests/sign?authority=example.com"
# {"authority":"example.com","headers":{"Signature-Agent":...,"Signature-Input":...,"Signature":...},"expiresAt":"..."}
runtime networks signed-requests off            # new signatures stop at once
```

- **Send the three headers** with every request to that site until
  `expiresAt`. That is 5 minutes after the response. Then request them again.
  `authority` is the site's host, with its port when it is not 80 or 443.
- **Refusals** say why: `signed_requests_off` (403: turn it on, or the sandbox
  is not running), `invalid_identity` (401: a token for another audience),
  `rate_limited` (429: more than 120 a minute from one sandbox).

From the SDKs, `runtime.networks.signedRequests` (Python:
`runtime.networks.signed_requests`):

```ts check
import { Runtime } from "withruntime";
const runtime = new Runtime();
await runtime.networks.signedRequests.set({ enabled: true });
const { enabled, allowed } = await runtime.networks.signedRequests.get();
```

## Private networks

A WireGuard tunnel connects a machine or router on your network to your
sandboxes (`runtime networks wireguard`, `runtime.networks.wireguard`,
`runtime_networks_wireguard`). Sandboxes that reach each other need no tunnel.
See [reach your other sandboxes by name](#reach-your-other-sandboxes-by-name).
Every sandbox gets an address in the tunnel's subnet. Your machines reach any
port on it there. While you have a tunnel, your sandboxes start where its
gateway can reach them both ways. If there is no room there now, a create
returns `no_capacity` (503). A retry with the same idempotency key goes ahead
once there is room.

```bash no-run
runtime networks wireguard create                                # subnet 10.250.0.0/16 by default
runtime networks wireguard peer add office --route 10.0.0.0/16   # writes runtime.conf
sudo wg-quick up ./runtime.conf
runtime networks wireguard get                                   # each sandbox's address
psql -h 10.250.0.32 app
```

`runtime networks wireguard peer add` makes the WireGuard key pair on your
machine. The private key goes only into `runtime.conf`, which only you can read.
Any WireGuard client works with a complete file, such as `wg-quick` on Linux and
macOS, the WireGuard apps on Windows, macOS, iOS and Android, or your router. To
use a key you already have, pass `--public-key`. If the gateway key is not ready,
`configReady` is false and the file is a draft. Keep its private key, add the
server key when it is available, and follow the CLI instructions before you
bring it up. Do not generate another peer just to get the same private key back.

- **Choose a subnet your network does not use,** from `/16` to `/24`, when you
  create the tunnel: `--subnet 172.30.0.0/16`.
- **`--route`** names your own ranges behind the peer. List them when your
  sandboxes will reach your network through the peer. TCP connections work in
  both directions. UDP is not carried by this tunnel.
- **What a peer reaches:** your own account's sandboxes, at their tunnel
  addresses, on any port except Runtime's own relays inside the sandbox (10800,
  10802 and 10853). Nothing else: not another account's sandboxes, not Runtime's
  servers, not the internet. Only TCP is carried.
- **Rotate a key** with `runtime networks wireguard peer rotate <peerId>`. The
  old key stops working within seconds, and connections opened with it end.
  `runtime networks wireguard peer rm <peerId>` removes a peer the same way.
- **Funding:** an unfunded tunnel stops traffic but keeps its reservation and
  peers until you delete it. Unpaid time is never billed. `funded`,
  `fundedUntil`, `rateMicros` and `rateUnit` report its current funding and quote.
- **Limits:** one tunnel per account, 16 peers. A paused sandbox is woken by a
  connection.

From the SDKs:

```ts check
import { Runtime } from "withruntime";
const runtime = new Runtime();
await runtime.networks.wireguard.create();
const office = await runtime.networks.wireguard.addPeer({
  name: "office",
  routes: ["10.0.0.0/16"],
});
// office.config is the wg-quick file; with no publicKey given, it holds the
// private key Runtime generated for you, shown once.
```

```python check
runtime.networks.wireguard.create()
office = runtime.networks.wireguard.add_peer("office", routes=["10.0.0.0/16"])
```

## Your Tailscale network

A paid sandbox can join your own tailnet. Your machines, databases and services
on Tailscale can then reach it, and it can reach them, by their tailnet
addresses. Make an auth key in Tailscale's admin console. Make it ephemeral and
tagged, and one-use unless the sandbox may pause for long (see below). Store it
for jobs. This is the copy a sandbox can be given. Then join:

```bash no-run
printf %s "$TS_AUTHKEY" | runtime secrets set TS_AUTHKEY --jobs
runtime sandboxes tailscale up <sandbox> --auth-key-secret TS_AUTHKEY --tag tag:agents
runtime sandboxes tailscale status <sandbox>     # its 100.x address and name
runtime sandboxes tailscale down <sandbox>       # removed from the tailnet at once
```

`--hostname` names the machine. The default is the sandbox's name. At create,
`tailscale: { authKeySecret: "TS_AUTHKEY", tags: ["tag:agents"] }` joins as
soon as it runs. A join that fails stops the new sandbox and says why.

- **The key stays in memory.** It is read from your secret with your key's
  right to reveal it, and given to `tailscaled` in the sandbox on a memory-only
  mount. It is never in a response, a log, the sandbox's disk or a command line.
  Code running as root in the sandbox could read it, as on any machine running
  Tailscale. That is why an ephemeral, tagged key is the one to use.
- **An ephemeral machine.** `down` logs it out and takes it off the tailnet
  immediately. A stop or a delete does not log it out first. The machine goes
  offline with the sandbox, and Tailscale removes an ephemeral machine by itself
  once it has been offline a while, up to about an hour. To have it removed
  immediately, run `down` before the stop, or remove it in Tailscale's admin console.
- **Pausing.** A paused sandbox is offline on the tailnet and back when it
  wakes. If Tailscale removed it meanwhile, the sandbox logs in again by itself
  with a reusable key. A one-use key cannot do that, so join again.
- **How it reaches the tailnet.** Where the sandbox's kernel allows a TUN
  device, which is the default image, it has a `tailscale0` interface. It
  reaches 100.x addresses directly (`mode: "kernel"`). Otherwise (`mode: "userspace"`),
  your tailnet still reaches the sandbox's ports. Programs in the sandbox reach
  the tailnet through the SOCKS5 and HTTP proxy on `localhost:1055`.
- **MagicDNS.** Once an image with Runtime's Tailscale DNS bridge has been
  qualified and released, it can resolve `.ts.net` names in both kernel and
  userspace modes. Ordinary public names keep using the usual resolver. Older
  images stay connected. They warn that MagicDNS needs an image with the bridge.
  Use the 100.x address, or rebuild the image, before you rely on tailnet names.
- **Your network rules still apply.** Tailscale's traffic leaves through the
  same proxy as everything else. So the sandbox needs `*.tailscale.com` and
  `pkgs.tailscale.com` on port 443. Paid sandboxes reach those by default. The
  sandbox also needs UDP for direct connections. Without it, traffic falls back
  to Tailscale's relays. Tailscale encrypts what travels inside the tailnet. Your
  [secrets](./security#secrets-sandboxes-never-see) are never put into it. Your
  tailnet's access rules decide what the sandbox's tags reach.
- **Not copied from memory.** While a sandbox is on a tailnet, a fork or a
  memory snapshot of it is refused with `tailscale_joined`. The copy would be
  the same Tailscale machine and would hold the key. Take the sandbox off the
  tailnet, copy it, and join each copy. A disk snapshot is taken as usual.
- **Sandboxes without credit** cannot join (`payment_required`). The first join
  downloads Tailscale into the sandbox, which adds a few seconds. Later joins
  reuse it.

## Outbound UDP

Paid sandboxes send UDP to any public address and port: HTTP/3 and QUIC, DNS
to a resolver of your choice, time sync, game and media servers, WireGuard or
other VPN clients. Sandboxes without credit send TCP only.

- Each flow has one destination. Only that destination's replies come back.
  Nothing reaches a sandbox over UDP unless the sandbox asked for it.
- Private, link-local and cloud metadata addresses are refused, and so are the
  ports no sandbox reaches over TCP either. The sandbox's network rules apply.
- Datagrams are limited to 1,472 bytes. A sandbox sends and receives at most
  50,000 datagrams a second. That is enough for full-size traffic at its
  500 Mbit/s upload peak, within its upload limits and daily allowance.
- A flow that has sent 256 datagrams without a reply is closed, so a sandbox
  cannot flood a host that does not reply.
- NTP to port 123 accepts standard 48-byte client requests and matching server
  replies only.
- There is no public inbound UDP port. UDP is not carried through a private
  tunnel or through your own upstream proxy.

## Errors

| Code                  | Status | Meaning                                                            |
| --------------------- | -----: | ------------------------------------------------------------------ |
| `payment_required`    |    402 | The account has no kept top-up, or the sandbox runs without credit |
| `tailscale_failed`    |    422 | Tailscale refused the login, or the sandbox could not reach it     |
| `tailscale_joined`    |    409 | A fork or memory snapshot of a sandbox on a tailnet                |
| `network_not_allowed` |    403 | Runtime turned network features off for the account                |
| `quota_exceeded`      |    409 | A limit above was reached: close or delete one first               |
| `rate_limited`        |    429 | Too many added today                                               |
| `no_capacity`         |    503 | No public port or dedicated address is free now                    |
| `network_unavailable` |    501 | The feature is not switched on in this region yet                  |

### What a visitor can get

When Runtime's router responds to a visit to an App, a balancer or a custom
domain itself, rather than your code, the response names its code in the
`x-runtime-error` header and the body, with the request's id:

| Code                   | Status | Meaning                                                                    |
| ---------------------- | -----: | -------------------------------------------------------------------------- |
| `bad_request`          |    400 | No hostname, two Host headers, or a Host that disagrees with the authority |
| `firewall_denied`      |    403 | The firewall refuses the visitor                                           |
| `no_route`             |    404 | Nothing is served at this hostname                                         |
| `misdirected_request`  |    421 | TLS was opened for a name whose certificate does not cover this one        |
| `rate_limited`         |    429 | The visitor is over the per-address limit (`Retry-After`)                  |
| `unsupported_protocol` |    501 | CONNECT did not name the websocket protocol                                |
| `upstream_failed`      |    502 | Every copy tried failed before responding                                  |
| `machine_no_capacity`  |    503 | No copy had a free slot in time (`Retry-After`)                            |
| `router_not_ready`     |    503 | A router just started has not yet had its route table (`Retry-After: 1`)   |
| `network_off`          |    503 | Runtime cut the machine's network                                          |

`router_not_ready` comes only from a router that has never had its table, such
as a new one. It cannot yet say whether the name is served. So it asks the
visitor to try again in a second, rather than return `no_route`. Every router
keeps its table on disk, so a restart serves immediately.


---

<!-- https://withruntime.com/docs/northflank-alternative -->

# Runtime vs Northflank

Runtime is built for agent sandboxes. For an agent that mostly waits on a model, it costs **42% less than Northflank**.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $1.11 on Northflank**. At 100,000 runs a month, that is $63.89
against $111.10, **$47 a month saved**.

Comparing more than two providers? [Northflank alternatives](/compare/northflank-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Northflank bills the vCPUs and memory a
  sandbox holds for as long as it runs. Runtime measures the CPU your code
  actually uses. Time spent waiting on a model costs only a small floor, a twentieth of a vCPU.
- **It pauses itself when idle.** After 300 seconds with no request, command, connection,
  traffic or CPU use, a Runtime sandbox pauses. While paused, it pays only paused storage,
  $0.08 per GB (10⁹ bytes) a month. The next request wakes it. Its processes keep running.
- **An uptime promise that pays itself.** Paid accounts get
  99% API uptime each month. A month below that returns 10% of that
  month's charges as credit. No claim is needed ([Uptime Promise](/legal/sla)).
- **Cheaper memory.** $0.0075 per GiB-hour on Runtime, against $0.00833 per
  GB-hour on Northflank. A GiB is about 7% larger than a GB.
- **A sandbox is one call.** `Sandbox.create()` returns a running sandbox.
  No service, project or deployment plan is needed. Northflank creates each
  sandbox as a service.
- **Pause and fork keep memory.** A paused Runtime sandbox wakes with its
  processes still running, kept while you have credit. A fork copies a running
  sandbox with its memory.
- **Teams at no extra charge.** Single sign-on over SAML or OIDC (Okta,
  Microsoft Entra ID, Google Workspace), SCIM, roles and an audit log come with
  every account ([single sign-on](./single-sign-on)). Northflank lists SAML and OIDC
  sign-in on its Enterprise plan.
- **A fixed outbound address on any paid account.** Every sandbox in the
  account sends from one dedicated address you can allow-list. It costs
  $5 a month ([dedicated addresses](./networking#dedicated-outbound-addresses)).
  Northflank lists egress IPs on its Enterprise plan.
- **Keys the sandbox never sees.** Store an API key once. The sandbox holds a
  placeholder. Runtime's proxy adds the value only to HTTPS requests to the
  hosts you name, so a prompt injection has nothing to leak ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Give an agent a read-only key or a daily spending
  limit per key. Cap any sandbox's total cost with `maxTotalCostMicros`. Every write takes an
  idempotency key, so a lost response never creates a second sandbox.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, private previews, a Linux desktop, metrics,
webhooks, OpenTelemetry export, S3, R2 and GCS bucket mounts, and identity tokens for AWS and Google Cloud. Paid accounts add custom
domains, TCP ports and WireGuard private networks. See [products](./products).

## At a glance

Northflank's figures come from its public pricing and documentation. Last checked
25 October 2026.

|                | Runtime                                                        | Northflank                                           |
| -------------- | -------------------------------------------------------------- | ---------------------------------------------------- |
| Isolation      | Firecracker microVM, own kernel                                | microVMs for CPU workloads, gVisor for GPU workloads |
| CPU billing    | $0.025 per vCPU-hour of measured CPU, with a small floor | $0.01667 per allocated vCPU-hour      |
| Memory billing | $0.0075 per reserved GiB-hour                          | $0.00833 per GB-hour               |
| Plan fee       | None; prepaid credit from $10                        | None published for compute                           |
| Free start     | 100 free hours of a 1 GB machine in the first 30 days, no card             | 2 services, 2 jobs and 1 database free               |
| Sandbox model  | A sandbox, created in one call                                 | A service with a deployment plan                     |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox (4 GB on Northflank). Each run lasts
60 seconds and keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most
of its time waiting for a model.

```
Runtime     CPU    1,000 × 20 s / 3,600 × $0.025        = $0.14
            Memory 1,000 × 60 s / 3,600 × 4 × $0.0075   = $0.50
            Total                                          $0.64

Northflank  CPU    1,000 × 60 s / 3,600 × 2 × $0.01667  = $0.556
            Memory 1,000 × 60 s / 3,600 × 4 × $0.00833  = $0.555
            Total                                          $1.11
```

- **Saving:** 42%, or $0.47 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $111.10 on
  Northflank.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $1.11 on Northflank.

The more time an agent spends waiting, the more Runtime saves. Storage,
network, taxes and free allowances are excluded from both. On Runtime, inbound
traffic is free. Each account's first 100 GiB out a month is free. After that,
the rate is $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Northflank calls on a branch, tests them on the free usage, and
tells you what you save each month. Your old code stays on the main branch until
you merge.

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

## When Northflank may fit better

- **Work that keeps every CPU busy.** Northflank's allocated vCPU rate is lower
  than Runtime's measured rate. A job that uses all its CPUs all the time
  costs less there: $1.11 against $1.33 in the example.
- **GPUs.** Northflank rents GPUs billed by the second, including L4, A100 and H100.
- **Your own cloud and many regions.** Northflank runs in your AWS, GCP or Azure
  account as well as its own regions. Runtime runs in one US region.

## Sources

Checked 23 September 2026; isolation, billing and free plan rechecked 26 October 2026; single
sign-on and egress IPs checked 27 September 2026.

- [Northflank pricing](https://northflank.com/pricing)
- [Northflank sandboxes](https://northflank.com/product/sandboxes)
- [Sandboxes on Northflank](https://northflank.com/docs/v1/application/sandboxes/sandboxes-on-northflank)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/observability -->

# Metrics, events and webhooks

See what a sandbox is doing. Get notified when it changes. Send both to the tools you already use.

- **Metrics.** The CPU, memory, disk use, disk I/O and network traffic of every running sandbox, over time. You can see them on the sandbox's page in your account. You can also get them from the API, the SDKs, the CLI and MCP.
- **Events.** Every lifecycle change for a sandbox, snapshot or volume. Examples: created, running, paused, woken, stopped, or a start that failed.
- **Webhooks.** Those events are sent as POSTs to your URL. Each is signed and retried for about three days. You get a delivery log and a test send.
- **OpenTelemetry export.** Events are pushed as logs. Each sandbox's readings are pushed as metrics. Every API call can be pushed as a trace span. The push uses OTLP/HTTP. Targets include Grafana, Honeycomb, Datadog, New Relic, an OpenTelemetry Collector, or any OTLP endpoint.

None of it costs anything extra.

## Metrics

```ts check
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create();
const m = await sbx.metrics({ range: "1h" });
console.log(m.latest?.cpuPercent, m.latest?.memoryBytes);
for (const point of m.points) console.log(point.at, point.cpuPercent, point.memoryBytes);
```

```python check
from withruntime import Sandbox

sbx = Sandbox.create()
m = sbx.metrics(range="1h")
print(m["latest"]["cpuPercent"], m["latest"]["memoryBytes"])
```

```bash check
npx withruntime sandboxes metrics <id> --range 6h
```

What you get:

| Field                                               | Meaning                                                                                                        |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `cpuPercent`                                        | CPU in use, as a percent of all the sandbox's vCPUs (0 to 100)                                                 |
| `cpuCores`                                          | The same as a number of cores                                                                                  |
| `cpuPeakPercent`                                    | The busiest interval between two readings inside the bucket                                                    |
| `cpuWaitPercent`                                    | Measured wall time ready to run while waiting for a processor, as a percent                                    |
| `memoryStallPercent`                                | Measured wall time with a thread waiting for memory, as a percent                                              |
| `memoryBytes`                                       | Memory the sandbox's machine holds, as its host measures it                                                    |
| `memoryPeakBytes`                                   | The most it held inside the bucket                                                                             |
| `diskUsedBytes`                                     | Bytes used on the root file system, as `df /` in the sandbox reports                                           |
| `diskReadBytesPerSecond`, `diskWriteBytesPerSecond` | Bytes read from and written to the sandbox's disks, per second                                                 |
| `diskReadOpsPerSecond`, `diskWriteOpsPerSecond`     | Read and write operations completed, per second                                                                |
| `networkReceivedBytesPerSecond`                     | Bytes received over the sandbox's connections, per second                                                      |
| `networkSentBytesPerSecond`                         | Bytes sent over its connections and served through its preview links, custom domains and TCP ports, per second |
| `latest`                                            | The newest reading while the sandbox runs; null when it is not running                                         |

The response also has `memoryLimitBytes` and `diskLimitBytes`, the sandbox's memory and disk sizes.

CPU is measured, not estimated. It is the machine's CPU time between two readings of its host. The bill uses the same readings. The host reads every running sandbox at least every half minute. A paused or stopped sandbox uses nothing, so it has no new readings. `latest` is null, and its earlier readings stay in `points`.

CPU wait and memory stalls use the differences between complete readings of the same run. Each is weighted by the time measured. A first reading, a missing counter or a counter reset returns null. It does not report no waiting. The same fields are in `points` and `latest`. Older servers can omit them.

Disk use and disk I/O are counted by the sandbox's own kernel. So they include reads served from the host's page cache, which the host cannot see. Network traffic is counted by the host's network proxy, in both directions. It covers every connection the sandbox opens and every request it serves. Rates are per second of the time the bucket's readings cover. A reading the sandbox did not answer in time returns null, not zero. So does a reading from before these fields existed.

`range` picks the window, and the bucket that each point sums:

| Range | Bucket     | Kept for |
| ----- | ---------- | -------- |
| `15m` | 10 seconds | 24 hours |
| `1h`  | 20 seconds | 24 hours |
| `6h`  | 2 minutes  | 24 hours |
| `24h` | 8 minutes  | 24 hours |
| `7d`  | 1 hour     | 30 days  |
| `30d` | 1 hour     | 30 days  |

Each reading is kept 24 hours. Hourly averages and peaks are kept 30 days.

In your account, [Sandboxes](https://withruntime.com/account/sandboxes) shows each sandbox's CPU and memory now. Home draws a trace of each running sandbox. A sandbox's own page charts CPU, with its events marked on the chart. Its Activity tab charts CPU, memory, CPU wait, memory stalls, disk used, disk reads and writes, and network in and out over any of the ranges above. The tab updates while the sandbox runs. It also lists the sandbox's commands and what happened to it. Once the sandbox has stopped, its page shows its whole life. That is CPU and memory from start to stop, and a timeline of its events and commands. CPU wait is time ready to run while waiting for a processor. A memory stall is time with a thread waiting for memory. A first reading, a missing counter or a counter reset shows as not measured. It never shows as no waiting.

## Account API calls

[Usage & billing](https://withruntime.com/account/billing) shows the account's recorded authenticated calls. It shows the error rate and service errors, grouped by operation. The window is 24 hours, 7, 30 or 90 days. Refused calls are 4xx responses. Service errors are 5xx responses. The error rate includes both. Its total counts every recorded response, redirects included. A window with no counted calls has a null rate. A failed read remains unavailable.

`GET /v1/usage/requests?range=24h` returns the same counts. The other ranges are `7d`, `30d` and `90d`. Each window is a fixed number of hourly buckets. It ends with the current partial hour. `since` is inclusive. `until` is the read time. Counts are written about once a minute. Requests that never authenticated are excluded. A key needs the `usage` scope, or a read-only or all-products key. Every account member can read the account's counts on the website.

`calls`, `clientErrors` and `serverErrors` are exact integer decimal strings. `errorPercent` is a percentage rounded to two decimal places. It is null when there are no calls. `operations` has the same fields, and an `operation` name for each row. These are recorded API responses. They are separate from the [uptime promise](/legal/sla).

For billing detail over a chosen period, the same page exports settled usage as a CSV file. [Export settled usage](./api#export-settled-usage) covers every resource visible to your key. The export keeps exact amounts and includes settled charges. Pending holds stay separate.

## Commands

Each command run in a sandbox is kept for 14 days. This covers runs through the API, an SDK, the CLI or MCP. Runtime keeps the program's name, its exit code and how long it ran. For example: `pytest · exit 1 · 28 s`. A command still running shows as running. A process started in the background gets its exit when a read or a list of its processes sees it end. If its sandbox is stopped or deleted while it runs, it shows `ended by the sandbox's stop` (or `delete`). That is not a failure. A command whose answer was lost on the way back shows `its answer was lost`. Its connection may have been cut, or the sandbox may have stopped or paused under it. The command may or may not have run to the end. So check its effects before you run it again. A command that timed out is kept with the time limit it ran under. The name is the program alone. For example, `python3` for `FOO=1 python3 train.py --key …`, and `pytest` for `bash -c "pytest -q"`. Arguments and environment values are never stored ([security](./security#keys-and-secrets)). A terminal is kept as its shell (`bash`). What is typed in it is never kept. A code interpreter cell, including E2B's `runCode`, is kept as its language and `-cell`. For example, `python-cell · exit 1 · 2 s` for a cell that raised an error. Its code is never kept.

Code written for E2B's `getMetrics()` gets CPU and memory from these readings through `withruntime/e2b`. Its `diskUsed` is null.

## Events

Every lifecycle change of a sandbox, snapshot or volume is an event. Events are kept for 14 days. Every change to your egress secrets and your upstream proxy is an event too, kept the same way.

| Type                         | When                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `sandbox.created`            | A sandbox is made; it is starting                                                                            |
| `sandbox.running`            | It is ready and running                                                                                      |
| `sandbox.paused`             | It paused, keeping its memory and files                                                                      |
| `sandbox.woken`              | A paused sandbox is running again                                                                            |
| `sandbox.stopped`            | It stopped. `stopReason` says why                                                                            |
| `sandbox.start_failed`       | It stopped before it ran; `sandbox.stopped` follows                                                          |
| `sandbox.wake_failed`        | A wake did not complete; the sandbox is paused or stopped                                                    |
| `sandbox.host_unreachable`   | Its server has not responded for 35 s, so what runs there is frozen; `host.unreachableSince` says since when |
| `sandbox.host_reachable`     | Its server responds again. The sandbox runs on as it was                                                     |
| `sandbox.unreachable`        | It is running but does not respond; `unreachable.reason` says why and `unreachable.since` since when         |
| `sandbox.reachable`          | It responds again; `unreachable.since` and `unreachable.reachableAt` say from when to when                   |
| `sandbox.recovered`          | Its server was lost and it is back; `recovery` says from when                                                |
| `sandbox.recovery_failed`    | Its server was lost and it cannot come back; `recovery.reason` says why                                      |
| `sandbox.files.changed`      | Files changed under a watch that sends to webhooks                                                           |
| `sandbox.out_of_memory`      | The sandbox ran out of memory and Linux ended a command's program; `outOfMemory` says how many and its size  |
| `sandbox.oom_kill`           | Linux's out-of-memory killer ended a process in the sandbox; `oomKill` names it, its PID and its memory      |
| `sandbox.secret_not_applied` | A request carried a secret's placeholder that was not replaced; `secretNotApplied` says which secret and why |
| `sandbox.network.limited`    | The sandbox met an outbound connection limit; `networkLimited` says which and its figure                     |
| `snapshot.ready`             | A snapshot finished and can be started from                                                                  |
| `snapshot.failed`            | A snapshot could not be taken                                                                                |
| `snapshot.deleted`           | A snapshot was deleted or expired                                                                            |
| `volume.ready`               | A volume is made and can be attached                                                                         |
| `volume.failed`              | A volume could not be made                                                                                   |
| `volume.deleted`             | A volume was deleted                                                                                         |
| `volume.recovered`           | Its server was lost and it is back on another, from the copy kept of it; `recovery` says from when           |
| `egress_secret.created`      | An egress secret was added; `secret` has its name, hosts and number of rules, never its value                |
| `egress_secret.updated`      | An egress secret was replaced                                                                                |
| `egress_secret.deleted`      | An egress secret was deleted                                                                                 |
| `upstream_proxy.set`         | Your upstream proxy was set or changed; `upstreamProxy` has its address, credential's name and hosts         |
| `upstream_proxy.removed`     | Your upstream proxy was removed                                                                              |
| `credit.low`                 | Credit lasts under 5 days at this month's pace; `credit` has what is left and what 5 days need               |
| `credit.empty`               | No credit is left; `credit` has `availableMicros` and `agentOnly`                                            |
| `job.run.failed`             | A [job](./jobs#alerts)'s run ended failed, timed out or unknown, with no retry left                          |
| `job.recovered`              | A job's run succeeded after runs that failed                                                                 |
| `agent.call.held`            | An agent trigger held a call no session took; `call` says which, its key and why                             |

Each event carries the resource as it was:

```json
{
  "id": "0b8f2a61-4c3e-4e7a-9d2f-6c1b0e5a7d94",
  "type": "sandbox.stopped",
  "createdAt": "2026-09-23T15:04:05.123Z",
  "data": {
    "sandbox": {
      "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f",
      "name": "build-runner",
      "labels": { "team": "ml" },
      "state": "stopped",
      "previousState": "stopping",
      "stopReason": "requested",
      "vcpu": 2,
      "memoryMiB": 4096,
      "diskMiB": 10240,
      "region": "us-east",
      "funding": "paid",
      "pausable": true
    }
  }
}
```

`job.run.failed` and `job.recovered` carry the job and the run. They never carry its output, because a run's output can hold the secrets in its environment. A run that will be retried sends none until its last attempt ends. `job.run.failed` is sent for every run that ends failing. `failingRuns` says how many in a row. A job's own [alert](./jobs#alerts) sends the same body to its own URL. It adds `logTail`, the run's last 20 lines of output (at most 2,000 bytes):

```json
{
  "type": "job.run.failed",
  "data": {
    "job": { "id": "5d1c…", "name": "nightly", "failingRuns": 3, "afterFailures": 3 },
    "run": {
      "id": "9a7e…",
      "attempt": 1,
      "trigger": "schedule",
      "state": "failed",
      "reason": "timeout",
      "exitCode": -9,
      "scheduledFor": "2026-10-18T09:00:00.000Z",
      "startedAt": "2026-10-18T09:00:04.210Z",
      "endedAt": "2026-10-18T09:30:04.215Z"
    },
    "logTail": ["fetching page 412", "still waiting on api.example.com"]
  }
}
```

`sandbox.out_of_memory` is sent once for each command that the out-of-memory killer ended. For a command run to its end, it is sent with the command's result. For a background process, it is sent when the process is first read, got or listed after it ended. A process that nobody reads after it ends sends none. The command is named by its program only, never by its arguments:

```json
{
  "type": "sandbox.out_of_memory",
  "data": {
    "sandbox": {
      "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f",
      "state": "running",
      "memoryMiB": 512
    },
    "command": { "program": "node", "processId": "p-4", "exitCode": -9, "outcome": "exited" },
    "outOfMemory": { "code": "out_of_memory", "processesKilled": 1, "memoryMiB": 512 }
  }
}
```

`sandbox.oom_kill` is sent once for each process that Linux's out-of-memory killer ended in the sandbox, within about a minute. It is sent whether or not the process belonged to a command: a service, a container or a background process counts too. `inCommand` says whether a command or process started through the API ran it. `memoryMiB` is the memory the process used when it was ended. Runtime's own agent is never ended this way, so the sandbox keeps answering:

```json
{
  "type": "sandbox.oom_kill",
  "data": {
    "sandbox": {
      "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f",
      "state": "running",
      "memoryMiB": 32768
    },
    "oomKill": {
      "process": { "name": "rustc", "pid": 4242, "user": "sandbox", "memoryMiB": 2048 },
      "inCommand": true,
      "at": "2026-10-27T22:39:12.000Z",
      "message": "The sandbox ran out of memory, and Linux's out-of-memory killer ended rustc (pid 4242, using 2048 MiB). Give the sandbox more memory (memoryMiB) or make the program use less."
    }
  }
}
```

`sandbox.unreachable` is sent when a running sandbox stops responding, within about 5 seconds. Its server checks Runtime's agent in each sandbox every 2 seconds. While it lasts, `GET /v1/sandboxes/{id}` returns the same `unreachable` object and `state` stays `running`. `sandbox.reachable` is sent when it responds again, with `since` and `reachableAt`. `reason` is one of:

| `reason`              | What happened                                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `agent_not_answering` | Runtime's agent in the sandbox does not respond. Its processes may still run. Restart the sandbox if this lasts                  |
| `disk_stalled`        | Its server has not finished a write to the sandbox's disk for over 5 seconds. New commands return 503; running commands continue |
| `host_quarantined`    | Its server took it out of running after a fault. Its disk is kept. Restart the sandbox                                           |

```json
{
  "type": "sandbox.unreachable",
  "data": {
    "sandbox": {
      "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f",
      "state": "running",
      "memoryMiB": 32768
    },
    "unreachable": {
      "since": "2026-10-29T06:08:11.000Z",
      "reason": "disk_stalled",
      "message": "The sandbox's server has not finished a write to its disk for over 5 seconds, so new commands return 503. Commands already running continue."
    }
  }
}
```

`sandbox.secret_not_applied` is sent when a request from the sandbox carried an [egress secret](./security#secrets-sandboxes-never-see)'s placeholder. The placeholder went out as it was. So the server got the placeholder, not the key. It is sent once for each secret, reason and destination of a sandbox. It goes out with the host's next usage reading, within about a minute. The placeholder is never the secret, so nothing leaked. The event names the secret. It never names the placeholder or the value. `reason` is one of:

| `reason`                   | What happened                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `unencrypted`              | It went without TLS, over plain HTTP or another cleartext protocol. A secret goes only over HTTPS |
| `not_in_credential_header` | It went to the secret's host in the path or query (`place` is `target`) or in the `place` header  |
| `rule_not_matched`         | It was in a credential header, but none of the secret's `rules` allows that method and path       |
| `by_address`               | HTTPS went to an IP address, asking for one of the secret's hosts. Use the host name in the URL   |
| `withheld`                 | HTTPS went to the secret's host, but its server could not add the secret then. Runtime's fault    |

For `rule_not_matched`, the request is not sent. It returns `403 Forbidden` with `X-Runtime-Egress: secret-rule-not-matched`. Over HTTP/1.1 the connection then closes; over HTTP/2 only that stream ends. The body names the method and path that no rule allows. Add a rule for them, or send that request without the placeholder.

`withheld` is sent for a connection to the secret's host. It is sent whether or not the connection carried the placeholder. When the server has not heard from Runtime's API within the last minute, a request that carries the placeholder is not sent: it returns `503 Service Unavailable` with `X-Runtime-Egress: secret-not-current` and `Retry-After: 1`, and the connection closes. The next request on a new connection carries the value once the server hears from the API again. When the secret's value cannot be opened on the server, Runtime does not read inside the connection. Try again. If it repeats, write to support.

Runtime does not read inside HTTPS to a host that no secret names. So a placeholder sent there sends no event. Check the host against `npx withruntime secrets ls`.

```json
{
  "type": "sandbox.secret_not_applied",
  "data": {
    "sandbox": { "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f", "state": "running" },
    "secretNotApplied": {
      "secret": { "name": "OPENAI_API_KEY" },
      "reason": "unencrypted",
      "destination": { "host": "api.openai.com", "port": 80 },
      "at": "2026-10-10T18:00:00.000Z",
      "message": "A request to api.openai.com:80 carried the placeholder of OPENAI_API_KEY without HTTPS, so the secret was not added. A secret goes only over HTTPS."
    }
  }
}
```

`credit.low` and `credit.empty` are about the account. So they have no `resourceId`, and they carry `data.credit`. Each is sent once for each top-up. A new top-up starts the count again. `credit.low` is sent when the credit left lasts under 5 days at this month's pace. This is the same rule as the low-credit notice in the inbox and by email. `credit.empty` is sent when no credit is left. Amounts are strings of micro-dollars (1,000,000 to the dollar). `requiredMicros` is the pace over 5 days. It appears only in `credit.low`. `agentOnly` is `true` when the account was opened with a wallet and no person may pay for it. Its own agent adds credit itself, with its own key.

```json
{
  "type": "credit.low",
  "data": {
    "credit": { "availableMicros": "3200000", "requiredMicros": "4100000", "agentOnly": true }
  }
}
```

`sandbox.files.changed` comes only from a file watch started with `webhook: true` ([files in the API guide](./api#files)). Runtime reads the watch without waking the sandbox. It sends what changed since the last read. It sends at most once every 2 seconds for each watch. Each event holds up to 100 changes. `more` counts the changes left out. `overflow` says changes were dropped, because of a flood or because the watch fell behind. For either, list the folder again. `ended` says the watch stopped. Its values are `timeout`, `stopped`, `root-removed`, and `gone` (when the sandbox restarted). While a sandbox that pauses itself does nothing, its watch is not read. So the watch never keeps it awake. A change arrives within seconds of the sandbox next doing work, or when it wakes.

`sandbox.network.limited` is sent when a sandbox meets one of its [outbound connection limits](./sandbox-environment#the-network). It is sent at most once an hour for each limit. It goes out with the host's next usage reading, within about a minute. `limit` is `connections`, `new-connections` or `destinations`. `connections` means open at the same time: a new one was refused. `new-connections` means a second. `destinations` means new hosts and ports a minute. For the last two, a connection waited its turn. `most` is the figure it was held to. `count` is how many times it was met, by the report. `at` is when it was first met that hour. `GET /v1/sandboxes/{id}/network` shows every limit in `limits`.

```json
{
  "type": "sandbox.network.limited",
  "data": {
    "sandbox": { "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f", "state": "running" },
    "networkLimited": {
      "limit": "connections",
      "most": 64,
      "count": 1,
      "at": "2026-10-15T18:00:00.000Z",
      "message": "The sandbox reached its limit of 64 open connections at once, so a new one was refused. Close or reuse connections it no longer needs. GET /v1/sandboxes/7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f/network shows its limits."
    }
  }
}
```

```json
{
  "type": "sandbox.files.changed",
  "data": {
    "sandbox": { "id": "7f3a2c10-58d4-4b9e-9c61-0a2b3c4d5e6f", "name": "build-runner" },
    "watch": { "id": "sync", "path": "/workspace/app" },
    "events": [
      { "type": "write", "path": "/workspace/app/notes.md", "isDir": false, "count": 2 },
      {
        "type": "rename",
        "path": "/workspace/app/b.txt",
        "oldPath": "/workspace/app/a.txt",
        "isDir": false
      }
    ]
  }
}
```

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

const runtime = new Runtime();
const sbx = await runtime.sandboxes.get("<sandbox id>");
await sbx.files.watches.webhook("/workspace/app", { recursive: true, id: "sync" });
```

List them newest first, for the account or one sandbox:

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

const runtime = new Runtime();
const { data } = await runtime.events.list({ resourceId: "<sandbox id>" });
```

```bash check
npx withruntime events --sandbox <id>
```

## Webhooks

A webhook sends every event of the types you choose to an HTTPS URL. It sends each event as a POST of the event's JSON, for every sandbox in the account. The webhook belongs to the account, so every key sees the same webhooks. Making, changing or deleting a webhook, or reading its deliveries, needs a key made by an owner or admin. So do [OpenTelemetry exports](#opentelemetry-export). Another key gets 403 `forbidden`. An account can have 16 webhooks.

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

const runtime = new Runtime();
const hook = await runtime.webhooks.create({
  url: "https://example.com/hooks/runtime",
  events: ["sandbox.stopped", "sandbox.start_failed"], // or leave out for every event
});
console.log(hook.secret); // shown once: keep it with your service
console.log(await runtime.webhooks.test(hook.id)); // your endpoint's answer
```

```bash check
npx withruntime webhooks create https://example.com/hooks/runtime --events sandbox.stopped,sandbox.start_failed
npx withruntime webhooks test <id>
npx withruntime webhooks deliveries <id>
```

Owners and admins can do the same on the [Webhooks page](https://withruntime.com/account/webhooks). The page picks event types grouped by product. It shows each webhook's delivery log, with **Resend** on each finished delivery. It also offers a CSV download of every delivery kept.

### Check the signature

Every delivery carries a `Runtime-Signature` header:

```text
Runtime-Signature: t=1758650000,v1=5f2b…
```

`t` is when it was sent, in Unix seconds. `v1` is the hex HMAC-SHA256 of `{t}.{body}`, keyed with your secret. Check it before you trust a delivery. The SDKs do this for you. They refuse a signature older than five minutes, so a captured delivery cannot be replayed. Pass the raw body, before any JSON parsing.

```ts check
import { verifyWebhook } from "withruntime";

export async function POST(request: Request) {
  const event = await verifyWebhook(
    await request.text(),
    request.headers.get("runtime-signature"),
    process.env.RUNTIME_WEBHOOK_SECRET!,
  );
  if (event.type === "sandbox.stopped") {
    // ...
  }
  return new Response(null, { status: 204 });
}
```

```python check
import os

from withruntime import verify_webhook


def handle(body: bytes, headers: dict) -> int:
    event = verify_webhook(body, headers.get("runtime-signature"), os.environ["RUNTIME_WEBHOOK_SECRET"])
    if event["type"] == "sandbox.stopped":
        pass
    return 204
```

Other headers: `Runtime-Webhook-Id` is the event's ID. It is the same on every retry, so you can skip an event you already handled. `Runtime-Event-Type`, `Runtime-Delivery-Id` and `Runtime-Delivery-Attempt` are there too.

### Answer, retries and the delivery log

Respond with any 2xx status code within 10 seconds. Anything else counts as a failure. So does a timeout or a redirect. A failure is retried after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, 12 hours, 24 hours and 24 hours again. That is ten attempts in about three days. Deliveries are not guaranteed to arrive in order. Order them by `createdAt`.

`runtime.webhooks.deliveries(id)` (or `npx withruntime webhooks deliveries <id>`) lists each delivery, with its attempts, your endpoint's status, and how long it took. `runtime.webhooks.retry(deliveryId)` sends one again. The webhook shows `failingSince` while its deliveries fail. Deliveries are kept for 14 days.

### Rotate the secret

`runtime.webhooks.rotateSecret(id)` makes a new secret and shows it once. The old secret keeps signing for a day, next to the new one. So every delivery carries two `v1` signatures until your service has the new secret. To choose a different period, pass `keepPreviousSeconds`, from 0 to a week. `verifyWebhook` accepts a list of secrets, for the same reason.

### Where webhooks can go

Webhook URLs must use HTTPS on the public internet. A URL that names a private, loopback or link-local address is refused when the webhook is made. Every delivery resolves the name again when it is sent. It refuses the delivery if any address is private. It connects only to the address it checked.

## OpenTelemetry export

An export pushes new events as OTLP log records. It pushes each sandbox's readings as OTLP metrics. This happens about every 30 seconds. If you ask for traces, it also pushes every API call as an OTLP span, within about a second. The target is any endpoint that takes OTLP over HTTP with JSON. The export starts from the moment you make it.

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

const runtime = new Runtime();
await runtime.otel.create({
  endpoint: "https://otlp-gateway-prod-us-east-0.grafana.net/otlp",
  headers: { Authorization: "Basic <instance id:token, base64>" },
});
```

```bash check
npx withruntime otel create https://api.honeycomb.io --header x-honeycomb-team=<key>
```

- `endpoint` is the OTLP/HTTP base URL, as in `OTEL_EXPORTER_OTLP_ENDPOINT`. Logs go to `<endpoint>/v1/logs`. Metrics go to `<endpoint>/v1/metrics`. Spans go to `<endpoint>/v1/traces`.
- `headers` authenticate you to the endpoint. You can set up to 10. They are stored where only the sender reads them, and they are never shown again.
- `signals` is `["logs", "metrics"]` by default. Add `"traces"` for API call spans. You can also send any one or two of the three.

The metrics have one resource per sandbox with `runtime.sandbox.id`, `runtime.sandbox.name`, `runtime.sandbox.vcpu` and `cloud.region`. The first six are gauges. The I/O metrics are delta sums: each point is the amount since the reading before it (`startTimeUnixNano`). They are split by the OpenTelemetry attributes `disk.io.direction` (`read`, `write`) and `network.io.direction` (`receive`, `transmit`):

| Metric                            | Unit          | Meaning                                        |
| --------------------------------- | ------------- | ---------------------------------------------- |
| `runtime.sandbox.cpu.utilization` | `1`           | CPU in use as a fraction of its vCPUs          |
| `runtime.sandbox.cpu.usage`       | `{cpu}`       | Cores in use                                   |
| `runtime.sandbox.memory.usage`    | `By`          | Memory its machine holds                       |
| `runtime.sandbox.memory.limit`    | `By`          | Its memory size                                |
| `runtime.sandbox.disk.usage`      | `By`          | Bytes used on its root file system             |
| `runtime.sandbox.disk.limit`      | `By`          | Its disk size                                  |
| `runtime.sandbox.disk.io`         | `By`          | Bytes read and written, by `disk.io.direction` |
| `runtime.sandbox.disk.operations` | `{operation}` | Reads and writes completed                     |
| `runtime.sandbox.network.io`      | `By`          | Bytes received and sent                        |

A reading the sandbox did not answer carries no disk or network points. The next measured one covers only its own interval.

Each log record's body is the event type. Its attributes are `event.name`, `event.id` and the resource's fields. Examples are `runtime.sandbox.state`, `runtime.sandbox.stop_reason` and `runtime.sandbox.label.<key>`. A failure (`start_failed`, `wake_failed`, `recovery_failed`, `failed`) is logged at WARN. The rest are logged at INFO.

A push that fails is retried. It waits 30 seconds, then doubles the wait, up to an hour. It sends from where it stopped. `runtime.otel.get(id)` shows `lastSuccessAt`, `lastError` and how much it has sent. `runtime.otel.flush(id)` pushes now. An account can have three exports.

### Traces

With `"traces"` in `signals`, every call your account makes to the API is a span. That includes creates, commands, file reads and writes, pauses, wakes and snapshots, whether they succeed or are refused.

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

const runtime = new Runtime();
await runtime.otel.create({
  endpoint: "https://api.honeycomb.io",
  headers: { "x-honeycomb-team": process.env.HONEYCOMB_KEY ?? "" },
  signals: ["logs", "metrics", "traces"],
});
```

Each span is a `SERVER` span named for the route, such as `POST /v1/sandboxes/{id}:exec`. It is timed from when the request arrived to when it was answered. It has the OpenTelemetry HTTP attributes `http.request.method`, `http.route`, `http.response.status_code`, `url.path`, `url.scheme` and `server.address`, and `error.type` for a 5xx response. It also has these:

| Attribute             | Meaning                                                |
| --------------------- | ------------------------------------------------------ |
| `runtime.operation`   | The operation, such as `sandboxes.exec`                |
| `runtime.request.id`  | The request's ID, as in the `x-request-id` header      |
| `runtime.error.code`  | The error code of a 4xx or 5xx response                |
| `runtime.resource.id` | The sandbox, snapshot or other resource the call names |
| `runtime.sandbox.id`  | The sandbox, for a call under `/v1/sandboxes/{id}`     |
| `runtime.client`      | The SDK or tool that made the call, with its version   |

A 5xx response sets the span's status to `ERROR`. A 4xx response is an error in your request, not in the server, so it leaves the status unset, as the HTTP conventions say.

**Your own trace.** A call that carries a W3C `traceparent` header is a child of that span. So Runtime's spans appear inside your own traces. The TypeScript and Python SDKs send the header for you when OpenTelemetry is set up in your process (`@opentelemetry/api`, or `opentelemetry-api` for Python) and a span is active. For example, a `Sandbox.create()` or `sbx.exec()` inside your own `startActiveSpan` shows as its child. No other setting is needed, and without an active span the SDKs send no header. A call that its caller did not sample (`traceparent` flags `00`) is not exported.

Spans are sent in batches as each call is answered, within about a second. If an endpoint refuses a batch, or does not answer within 2 seconds, that batch is lost, as with an OpenTelemetry SDK's exporter. That export's spans are then dropped for 5 seconds, doubling up to 5 minutes while its endpoint keeps failing, and sending resumes after the first success. Each export is separate: another export of the same account keeps receiving every span. Spans that cannot be held because the endpoint falls behind are also dropped and reported. `tracesLastError` says why, and `exportedSpans` counts what arrived. Spans have their own `tracesLastAttemptAt`, `tracesLastSuccessAt`, `tracesLastError` and `tracesFailures`. `lastSuccessAt`, `lastError` and `failures` describe logs and metrics only, so one signal's failure never hides behind another's success.

## What metrics and traces cost

Disk, disk I/O and network metrics, and a trace span of every API call,
measured for what they cost on 25 October 2026 at 7:20 p.m. US Mountain time, in a production Runtime
sandbox with 4 vCPU (AMD EPYC), Bun 1.4.0 and Python 3.12.3. Percentiles are
nearest-rank.

| What                                                     | p50     | p95     | p99      | Samples |
| -------------------------------------------------------- | ------- | ------- | -------- | ------- |
| The sandbox's CPU for one disk reading                   | 54 µs   | 60 µs   | 86 µs    | 5,000   |
| Recording one API call's span                            | 0.87 µs | 7.03 µs | 14.23 µs | 100,000 |
| Recording one span inside your own trace (`traceparent`) | 1.08 µs | 5.61 µs | 12.97 µs | 100,000 |
| An API call of an account that exports no traces         | 0.04 µs | 0.05 µs | 0.05 µs  | 100,000 |
| Encoding 512 spans as one OTLP/JSON body                 | 0.82 ms | 2.35 ms | 2.87 ms  | 300     |

- **Disk reading.** The host asks each running sandbox's kernel for its disk
  counters once a reading, every 30 seconds: 54 µs of the sandbox's CPU in 30
  seconds is under 0.0002% of one vCPU. A sandbox that does not answer in
  250 ms is not waited for; that reading has no disk figures. Network traffic
  is counted on the host and costs the sandbox nothing.
- **Spans.** A span is made in memory when the call is answered and sent
  within about a second, so it adds about a microsecond to the call and
  nothing to the database.
- **Reading the metrics.** A day of readings, one every 30 seconds, read as
  the `1h` range reads it took 3.19 ms at the median (3.43 ms p95) with disk
  and network, against 2.02 ms (6.04 ms p95) without; as the `24h` range reads
  it, 20.9 ms (30.3 ms p95) against 12.2 ms (18.8 ms p95). Measured on
  Postgres 18 in the same sandbox, 50 reads each.

The [recorded figures](/benchmarks/metrics-traces-2026-10-25.json) and the
[test that measures them](https://github.com/withruntime/runtime/blob/main/packages/cloud/tests/metrics-traces.speed.test.ts)
are published. These are observations, not a latency promise.

## MCP

`runtime_sandboxes_metrics` reads a sandbox's CPU, memory, CPU wait, memory stalls, disk and network. `runtime_events_list` reads its events. `runtime_webhooks_manage` and `runtime_otel_manage` list, create, test and change webhooks and exports.


---

<!-- https://withruntime.com/docs/openai-agents-sdk -->

# Runtime for the OpenAI Agents SDK

Run a `SandboxAgent`'s shell, files and manifest in a Runtime sandbox, in Python or TypeScript, with the agent unchanged.

`RuntimeCloudSandboxClient` is a sandbox client for the OpenAI Agents SDK, like
its Docker, E2B or Modal clients. Change the client in the run configuration
and the same agent runs in a Firecracker microVM with its own kernel, billed
for the CPU it uses.

## Python

```bash no-run
pip install "withruntime[openai-agents]"
```

```python check
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File
from withruntime.openai_agents import RuntimeCloudSandboxClient, RuntimeCloudSandboxClientOptions

agent = SandboxAgent(
    name="Analyst",
    instructions="Answer from the files in the workspace.",
    default_manifest=Manifest(entries={"sales.csv": File(content=b"month,total\nJuly,120\nAugust,180\n")}),
)
run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=RuntimeCloudSandboxClient(),
        options=RuntimeCloudSandboxClientOptions(),
    )
)
print(Runner.run_sync(agent, "How much did sales grow?", run_config=run_config).final_output)
```

The key comes from `RUNTIME_API_KEY`, or from `npx withruntime login` on this
machine, as in the rest of the SDK. Pass `RuntimeCloudSandboxClient(runtime=AsyncRuntime(...))`
to share a client.

## TypeScript

```bash no-run
npm install withruntime @openai/agents
```

```ts
import { run } from "@openai/agents";
import { SandboxAgent } from "@openai/agents/sandbox";
import { RuntimeCloudSandboxClient } from "withruntime/openai-agents";

export async function analyse() {
  const agent = new SandboxAgent({
    name: "Analyst",
    instructions: "Answer from the files in the workspace.",
    defaultManifest: {
      entries: { "sales.csv": { type: "file", content: "month,total\nJuly,120\nAugust,180\n" } },
    },
  });
  const client = new RuntimeCloudSandboxClient();
  const result = await run(agent, "How much did sales grow?", { sandbox: { client } });
  return result.finalOutput;
}
```

## Options

Every option is optional.

| Python                    | TypeScript              | What it does                                                                                                   |
| ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `funding`, `image`, ...   | `create`                | How to create the sandbox: `funding`, `region`, `image`, a snapshot, `vcpu`, memory, disk, `name`, `labels`    |
| `snapshot_id`             | `create.snapshot`       | Start from a ready Runtime snapshot, with its files, memory and processes                                      |
| `timeout_seconds`         | `create.timeoutSeconds` | A time limit: the sandbox pauses when it runs out. Left out, it runs while it works                            |
| `extra`                   | `create`                | Any other create field, such as `network` or `volumes`                                                         |
| `env`                     | `env`                   | Set for every command, under the manifest's own environment                                                    |
| `exposed_ports`           | `exposedPorts`          | Ports `resolve_exposed_port` may share as Runtime previews                                                     |
| `preview_visibility`      | `previewVisibility`     | `private` (default): the endpoint carries its token in its query; `public`: anyone with the address, paid only |
| `pause_on_exit`           | `pauseOnExit`           | Pause instead of stopping at the end, so resuming wakes the same machine                                       |
| `workspace_persistence`   | —                       | `tar` (default) or `snapshot`, below                                                                           |
| `snapshot_retention_days` | —                       | Days a `snapshot` persistence snapshot is kept                                                                 |
| `exec_timeout_s`          | `execTimeoutMs`         | The longest a command may run: one hour by default, 24 hours at most                                           |

## What runs in the sandbox

- **Shell with PTY sessions.** `exec_command` returns when the command finishes
  or its yield time passes; a command still running keeps a session that
  `write_stdin` polls. With `tty` it gets a terminal and takes typed input.
- **Files.** Reads, writes and `apply_patch` edits of any size, image views,
  listings, and paths outside the workspace that the manifest grants.
- **The manifest.** Files, directories, local files and directories, git
  repositories, environment variables, and users and groups. Commands with a
  `user` run through `sudo -u`; you are root inside your own sandbox.
- **Exposed ports** become Runtime previews at `runtimehost.com`. A private
  preview's endpoint carries its token, so it works unchanged in a browser,
  `fetch`, `curl` or a WebSocket client.

## Keep a workspace between runs

Give the run a snapshot store, such as `LocalSnapshotSpec`, and a stopped
session's workspace comes back when it resumes.

- **`workspace_persistence="tar"`** (the default) keeps the workspace as an
  archive; resuming starts a new sandbox and unpacks it.
- **`workspace_persistence="snapshot"`** keeps the whole machine as a Runtime
  snapshot: the workspace, every other file, installed packages, memory, and
  processes started outside the agent's PTY sessions. Resuming starts a copy
  of it. The snapshot is billed as snapshot storage
  ([pricing](./pricing#snapshots-images-and-volumes)).
- **`pause_on_exit`** pauses the sandbox instead, and resuming wakes the same
  machine where it stopped.

In TypeScript, `pauseOnExit` resumes the same machine, and
`persistWorkspace()` and `hydrateWorkspace()` move a workspace as a tar.

## Function tools for an ordinary agent

An `Agent` that is not a `SandboxAgent` can take the four
[framework tools](./frameworks#any-other-framework): `runtime_exec`,
`runtime_read_file`, `runtime_write_file` and `runtime_list_files`.

```python check
from agents import Agent, function_tool
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def coder(sbx: Sandbox) -> Agent:
    return Agent(name="Coder", tools=[function_tool(f) for f in sandbox_tools(sbx)])
```

In TypeScript, `runtimeFunctionTools(sbx)` from `withruntime/openai-agents`
returns the same four.

## What was verified

On 23 September 2026 both clients ran `SandboxAgent` in the SDK's own runner
against real sandboxes without credit, driven by the SDK's scripted test model:
OpenAI Agents SDK 0.22.3 in Python and 0.18.0 in TypeScript. Between them the
runs covered commands, a long command polled through `write_stdin`, a terminal
session, `apply_patch`, manifests with files, users, git repositories and local
directories, a private preview, tar and snapshot persistence, pause and resume,
and cleanup, with no sandbox left running.


---

<!-- https://withruntime.com/docs/plans -->

# Plans

Plans are in a private beta. Only the organizations in it can see or choose
one. Everyone else keeps paying for what runs from prepaid credit, as before.
Nothing changes for an account until it chooses a plan.

A plan is a monthly fee that comes back as usage:

- **The fee buys usage.** Each month, the fee is given back as plan usage, at
  the same measured prices as any credit. You still pay only for what runs.
  The plan does not add a charge of its own.
- **Used first, then expires.** Plan usage is spent before any credit: first
  plan usage, then free and given credit, then credit you bought. Any plan usage
  left at the end of the month expires. Your credit stays.
- **Twice in the first month.** A plan's first month, and the first month
  after you move up to it, holds twice its usage.
- **Yearly.** A plan with a yearly price costs ten months' fee for twelve.
- **A trial.** A plan with a trial can be tried for its days, once per
  person, from the console. Starting it saves a card on Stripe's checkout
  page and charges nothing. When the trial ends, the card is charged the
  plan's first period, which holds twice its usage, unless you cancel before.
  Cancelling during the trial ends it with its days, and nothing is charged.
  Choosing a plan during the trial ends the trial and charges that plan
  immediately.
- **Higher limits, more features, more support.** A plan raises limits, such
  as how many sandboxes run at the same time. It turns on features such as single sign-on,
  roles and the audit log. It sets your support: docs, the support agent, a
  shared Slack channel, or a dedicated one. It never lowers a limit you have.
- **Limits are ceilings, not room held for you.** A plan lets you run up to
  its limits. At a busy moment, a sandbox can still wait for room, as on any
  account.
- **First in line when room is short.** When a region is short of room,
  what waits for it is admitted by its account's lane. The order is Enterprise first, then
  Scale, Pro Max, Pro and Free. Runtime's own work, such as the checks of
  our own repository, comes after every customer's. A contract is Enterprise. An
  account with no plan is in the Pro lane, or the Free lane while it is on a
  trial. See [waiting in line for room](./limits#waiting-in-line-for-room).
- **Add-ons.** Some plans offer add-ons, such as 50 more concurrent sandboxes.
  They are charged monthly beside the plan.
- **Changing.** Moving up takes effect immediately. The difference for the rest of the
  month is charged, prorated. Moving down, or cancelling, takes effect at the
  end of the period you paid for. You keep the plan until then. You can
  take a cancel back before then.
- **The card.** A paid plan, or a trial, keeps a card on file. While the plan
  or the trial is active, you can replace the card but not remove it. Bought credit pays the fee only
  when there is no card. Given credit never pays a fee.
- **Moving up by itself.** An owner can let the account move to the plan that
  lifts a limit when the limit refuses something. This is off unless an owner turns
  it on.

When a limit refuses something, the refusal names the plan that lifts it and
the command that moves to it, in `details.plan`. A feature the plan does not
include, such as single sign-on, roles other than owner, the audit log or a
new conversation with the support agent, is refused with `plan_required`.
It names the plan that includes it the same way.

Only an owner, admin or billing member, or a key one of them made, can choose,
change or cancel a plan or its add-ons. Only an owner turns moving up by
itself on or off. Any key of the organization can read them. A person, signed in,
starts a first plan and a trial, on Stripe's checkout page.

## Read the plans and yours

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

const runtime = new Runtime();
const { current, plans } = await runtime.plans.list();
console.log(
  current?.name ?? "no plan",
  plans.map((plan) => plan.id),
);
```

```python check
from withruntime import Runtime

r = Runtime().plans.list()
print(r["current"], [plan["id"] for plan in r["plans"]])
```

```sh no-run
npx withruntime plans
```

In Go it is `client.Plans.List(ctx)`, in Java `runtime.plans().list()` and in
Ruby `runtime.plans.list`. Over HTTP it is `GET /v1/plans`. Over MCP, it is the
`runtime_plans` tool's `get` action. A plan has these fields:

| Field               | Meaning                                                                         |
| ------------------- | ------------------------------------------------------------------------------- |
| `id`, `name`        | What `choose` takes, and its name                                               |
| `card`              | Plans sharing a card are one choice with a switch, such as two sizes            |
| `feeMicros`         | The monthly fee, before tax; `"0"` for Free                                     |
| `yearlyFeeMicros`   | The yearly fee, or null when the plan has none                                  |
| `bonusMicros`       | Usage given on top of the fee each month                                        |
| `includedMicros`    | Usage included each month, or null when the fee and `bonusMicros` are its usage |
| `yearlyOnly`        | Whether the plan is billed yearly only; choosing it monthly returns `409`       |
| `trialDays`         | How long its trial lasts; 0 for none                                            |
| `trialUsageMicros`  | Usage its trial includes; `"0"` for none                                        |
| `firstPeriodDouble` | Whether the first month holds twice the usage                                   |
| `support`           | `docs`, `agent`, `slack` or `dedicated`                                         |
| `collection`        | `card`, charged monthly or yearly; or `invoice`                                 |
| `contract`          | A contract made for your organization alone                                     |
| `included`          | Usage included each month: `product`, `meter`, `quantity` and `unit`            |
| `limits`            | What the plan raises: `limit` (such as `sandbox.count`) and `max` (null: none)  |
| `features`          | What the plan turns on, such as `single-sign-on`, `roles` and `audit-log`       |
| `addOns`            | `id`, `name`, `feeMicros`, the `limits` each `add`s to, and a `feature`         |

`current` is the plan you are on, or null: `planId`, `name`, `status`
(`incomplete`, `trialing`, `active`, `past_due` or `canceled`), `interval`
(`month` or `year`), `periodStart`, `periodEnd`, `trialEndsAt`,
`cancelAtPeriodEnd`, `nextPlanId` (a move down waiting for `periodEnd`),
`startedAt`, `addOns` (`id`, `quantity`, and `endsAt` once removed),
`autoUpgrade`, and `planUsage`: this month's `grantedMicros`, the
`leftMicros` spent first, and when it `expiresAt`.

## Choose, change or cancel

```sh no-run
npx withruntime plans choose <plan>
npx withruntime plans choose <plan> --yearly
npx withruntime plans cancel
npx withruntime plans resume
npx withruntime plans add-on <add-on>
npx withruntime plans remove-add-on <add-on>
npx withruntime plans auto-upgrade on
```

The SDKs call them `choose(plan)`, `cancel()`, `resume()`, `addOn(id)`,
`removeAddOn(id)` and `autoUpgrade(on)`. Over HTTP, they are
`POST /v1/plans/choose` with `{"plan": "<id>"}` and an optional
`"interval": "year"`, `POST /v1/plans/cancel`, `POST /v1/plans/resume`,
`POST /v1/plans/add-ons` with `{"addOn": "<id>"}`,
`DELETE /v1/plans/add-ons/<id>` and `PUT /v1/plans/auto-upgrade` with
`{"on": true}`. Each returns `checkoutUrl` and `current`. With no plan yet,
`checkoutUrl` is the page where a person signs in, chooses the plan and pays
the first month. The plan starts once that payment goes through. A
plan's interval changes at its renewal: cancel, then choose it yearly. MCP
only reads plans. Choosing one moves money, which a person or the CLI does.

Money is integer microdollars in strings: `"25000000"` is 25 dollars.


---

<!-- https://withruntime.com/docs/pricing -->

# Understand your sandbox bill

You pay for the CPU your code uses, not the CPUs it holds: **$0.025 per active vCPU-hour** and **$0.0075 per reserved GiB-hour of memory**.

There is no plan fee. For an agent that spends most of its time waiting on a model, that makes Runtime **42% to 88% cheaper** than fourteen other sandbox providers ([the comparison](#published-rate-comparison)).

- **Busy:** 2 vCPUs and 4 GiB with both CPUs working cost $0.08 an hour.
- **Waiting while it runs:** the same sandbox costs $0.03125 an hour, for memory plus the default CPU floor of 50 millicores (a twentieth of a vCPU). After 300 seconds with nothing happening, it pauses and pays for paused storage instead.
- **Memory:** $0.0075 per GiB-hour is the lowest memory rate of the providers in [the comparison](#published-rate-comparison) that price memory on their own.
- **At scale:** 1,000 running hours cost $31.25 waiting and $80 fully busy.

Memory is billed while compute runs. CPU is billed from the moment the sandbox is ready. Runtime pays for the CPU used while a sandbox boots or restores. A GiB is 1,073,741,824 bytes, not a decimal GB. A higher `cpuFloorMillis`, or `cpu: "reserved"`, raises the waiting charge. Reserved CPU keeps every vCPU for the sandbox and bills it as if it were always busy. The floor becomes all of them, so 2 reserved vCPUs and 4 GiB cost $0.08 an hour whether the code works or waits. The price quote for each resource is fixed when the resource is created.

**Idle time is paused time.** A sandbox pauses itself after 300 seconds with nothing happening in it: no request, no command still running, no open connection, no network traffic and no CPU use. From then on, it pays only for [paused storage](#paused-storage). The next request wakes it. Set `idlePauseSeconds` from 60 to 86,400, or 0 to keep it running.

**A running sandbox's disk.** The first 10 GiB of a running sandbox's disk is included. Past that, the blocks that only its disk holds are billed at the [paused-storage](#paused-storage) rate, $0.08 per decimal GB per 30-day month, measured every 30 seconds while it runs. A disk of 10 GiB or less never pays this. That includes the default size and every sandbox's disk without credit. The bill shows it as "Sandbox disk". Sandboxes made before 5 October 2026 keep the terms they were quoted.

**Busy time is never cut off on a clock.** A sandbox has no time limit unless you set one with `timeoutSeconds`. A busy sandbox keeps running and pays for what it uses. It runs until you stop it, it goes idle and pauses, or its credit, a spending limit or its own `maxTotalCostMicros` runs out. `onTimeout` (`onLeaseEnd` in the SDKs) says whether it then pauses or stops. `persistent: true` keeps a sandbox running until you stop it, with no idle pause. Its disk is billed as any sandbox's disk is.

**Start free.** Every account gets [free usage](./included-usage), with no card: 100 GiB-hours of memory, 25 vCPU-hours of active CPU, 10 GB of saved copies (snapshots, images, backups) and 5 GB of volumes. That is enough for 100 free hours of a 1 GB machine. An account that has never paid gets the machine time once, across its first 30 days. An account that has paid gets it every month, renewed on the 1st (UTC). Free usage is used before credit and is never charged. An account given free hours before 5 October 2026 also keeps what is left of them.

**Then prepay.** Add credit by card at [Usage & billing](https://withruntime.com/account/billing), in any amount from $10 to $10,000. There is no subscription. The page shows how long your credit lasts at this month's pace, and what each product cost each day. Its ledger links each card purchase to its Stripe receipt. Runtime emails you once each purchase's credit is added, with any match it earned and your balance. Credit you add within 30 days of signing up is matched, up to $1,000 in total ([welcome match](#welcome-match)). Refer a company, and you both get up to $1,000. After that, you get 10% of what it spends, for 12 months ([referrals](./referrals)).

## How many at once

One paid sandbox can have up to **16 vCPUs and 64 GiB of memory**, at the same per-unit rates, and a disk of up to 400 GiB; a sandbox without credit up to 2 vCPU, 4 GiB and a 10 GiB disk. Fully busy, the largest sandbox costs $0.88 an hour.

A paid account runs **100 sandboxes at once**. The count includes sandboxes that are starting, running, waking or pausing. Paused and stopped sandboxes do not count. The account has up to **200 vCPUs and 400 GiB of memory** across the running sandboxes, and 1 TiB of disk, from the first top-up. While [auto top-up](#auto-top-up) is on, these limits double, and the account runs 200 sandboxes at once. A disputed payment, a suspension or an abuse report puts an account back to 50 sandboxes at once. A paused sandbox holds no CPU or memory. Waking one while the account already runs its limit is refused with `quota_exceeded`, and the sandbox stays paused until another sandbox pauses or stops. A paused sandbox's disk is still billed as storage. An account keeps up to 1,000 sandboxes in all, running, paused or stopped. Delete the ones you no longer need, or ask support for more. At a busy moment, a create can still return `no_capacity`. The SDKs wait for room, up to two minutes by default.

Paid features come at two levels.

- **Has credit.** An account that holds credit, bought or given, has the paid limits and every other paid feature, except three things. Those three include rules on a secret, dedicated outbound addresses and four image builds at once.
- **Kept top-up.** Three features that spammers abuse also need a kept top-up: ports beyond 80 and 443 (outbound, custom domains, TCP ports and your own upstream proxy), public previews, and private networks (WireGuard tunnels, reaching your sandboxes by name, and Tailscale). A top-up counts once it is paid, by card or in stablecoins. It counts only while it is not refunded or charged back in full, and no payment of it is in dispute. Credit Runtime gave does not count. A startup accepted to Runtime for Startups counts as having a kept top-up from the day it is accepted.

When every top-up has been refunded or charged back, the three features close again. A refusal says which level is missing: "needs credit" or "needs a kept top-up".

These limits are a starting point, not a price tier. To run more, write to support with the numbers you need ([feedback and support](./feedback-and-support)). For a burst of hundreds of sandboxes for a few hours, [book the room](./reservations). Your limits rise by what you booked for the window. Sandboxes you run are billed as usual. Booked room that none of them uses costs a quarter of the memory rate, **$0.001875 per GiB-hour**, with no CPU charge. It costs nothing if you cancel at least an hour before the start ([what it costs](./reservations#what-it-costs)). Every limit, with credit and without, is listed in [limits](./limits). Past a limit, a create returns `quota_exceeded`. The error says which limit was reached and, for a new account, when it lifts. The create costs nothing. An account without credit runs four at once, at most 8 vCPU and 16 GiB in all, keeps at most 5 sandboxes, and makes at most 50 a day. Its scheduled jobs wait for credit ([free usage](./included-usage)).

## Paused storage

A paused sandbox keeps its files and memory for **$0.08 per decimal GB per 30-day month**. The sandbox's fixed resource quote holds the actual rate. A stopped sandbox keeps its disk the same way, at the same rate, for as long as a paused one. It is kept until you delete it. Only a delete removes a disk. A sandbox made by an older client (a JavaScript or Python SDK before 0.12.0, Go, Java or Ruby before 0.2.0, or raw HTTP without `x-runtime-client: http/2026-10-04`) is kept the same way in an account with credit, a card saved or a past purchase. If its credit runs out, it is still kept at least 30 days from the stop. In an account with none of these, it is kept free for three days after it stops, with one notice a day before. Then it is deleted. The version counts, not its date. JavaScript 0.11.1 and 0.11.2 and Python 0.11.1 came out after 4 October. They still stop to clean up at the end of a `with` or `await using` block, so they are older clients.

- **What counts:** disk and memory-snapshot blocks the sandbox alone owns. Shared base-image blocks and snapshot safety overhead are left out. Where the filesystem cannot report sharing, allocated blocks are used instead. This can overcount. The same measure bills a running sandbox's disk past its first 10 GiB.
- **What does not:** the provisioned disk allowance, or the sum of live file sizes.
- **When it runs:** compute billing ends when a pause stops the sandbox's processors, before its memory is written to disk. Storage billing begins at that moment, at the size measured once the write finishes. It ends on a confirmed resume or deletion. Compute has no one-minute minimum.

A paused sandbox on a paid account is kept as long as the account has credit, until you delete it, or for 1–365 days if you set them with `:retention`. Those days count from each pause. Using the sandbox ends the count. So with `:retention` at 1, an idle pause is a day from deletion. For dates you set this way, the warning email below goes at most once a day for the account. It lists every sandbox due, and only while its deletion is still due. `null` keeps it while you have credit again. When credit runs out it is kept 30 more days in an account that has bought credit or saved a card, seven in one that has done neither. A notice is sent first. A top-up before then keeps it again. Each pause replaces the previous saved state. On an account without credit, a paused sandbox is kept seven days for free. `:retention` on a sandbox made without credit returns `retention_unavailable`. Its days cannot be set. Once the account holds credit, a sandbox paused without credit is kept as a paid one is. Its storage is billed from the end of its seven free days. The resource's `pausedExpiresAt` (null while it is kept as long as you have credit) and its paused-storage receipt give its actual terms.

A pause with an end date that you ask for, or one at the end of a time limit or of credit, posts an account notice with the date its saved state is kept until. The notice is posted within about five minutes, so a sandbox woken sooner may get none. An idle pause, and one kept as long as you have credit, posts none. Every paused sandbox with an end date gets a warning a day before its saved state is deleted. Its storage is still charged from the moment it paused, as above.

## Snapshots, images and volumes

Storage has been charged since 23 September 2026. An item made before then is charged only from that date.

| What you keep                                | Rate                                                                                                            | Charged on                                                                            |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [Snapshot](./javascript#snapshots-and-forks) | **$0.08 per decimal GB per 30-day month**, 119 microdollars per GiB-hour | The bytes the snapshot alone stores; a block two of your snapshots share counts once  |
| [Image](./javascript#custom-images)          | **$0.08 per decimal GB per 30-day month**, 119 microdollars per GiB-hour | Whole image file; qualified and enabled copy accounting counts verified extra storage |
| [Volume](./javascript#volumes)               | **153 microdollars per GiB-hour**, about $0.11 per GiB per 30-day month           | The full size you create it with, written or not                                      |

Where deferred compression has been qualified and enabled, a memory capture can be ready for same-server starts while `compressionPending: true`. Raw preparation files are Runtime overhead. Snapshot billing uses the final verified compressed allocation from its ready time, within existing prepaid bounds. A paused source uses its final measured size from the original freeze, but only if it is still paused when that measurement arrives. Waking or deleting it before then does not charge the unmeasured parked interval. See [snapshot storage](./storage#snapshots-survive-their-server).

Where copied-image accounting has been qualified and enabled, an identical image copy verified in your account on the same server adds only its extra storage to billing and quota. The shared base and each verified extra allocation count once while a ready copy still holds them. Deleting the base's owner moves it to a remaining ready copy. An extra allocation moves only to a proven descendant of the copy that added it. Retained capacity is freed only after the last files holding it are removed. Deleting and recreating owners preserves accrued charges. It does not reset the meter. Until that accounting is enabled, all images keep full-file accounting. Changed images and unverified copies keep it afterward too.

The snapshot and image rate is paused storage's rate, rounded down to whole microdollars. The volume rate is the reserved disk rate. A volume holds its whole size on its server from the moment you create it.

Building an image is free. Without credit, it counts toward the free usage, unless it fails through a fault of ours. The snapshot a fork takes for itself, and deletes, is also free. A snapshot is kept as long as you have credit, with no end date (7 days without credit), unless you choose 1 to 365 days. A snapshot's copy off its server is part of the snapshot and costs nothing more. Volume backups cost **$0.02 per decimal GB per 30-day month**. A backup made before this price keeps $0.012 until 7 November 2026. Backups are charged on `storedBytes` after a backup is copied and checked ([storage and backups](./storage)). Every volume is backed up off its server daily, unless you turn that off.

The [free usage](./included-usage) stores your first three images and your first 10 GiB of volumes free, for as long as you keep them. They are never charged, even after you add credit. Deleting one frees its place. Snapshots are not part of that free storage.

How much an account stores is limited in GiB: 500 GiB in all and 250 GiB of snapshots with credit, and 50 GiB and 20 GiB without. Past a limit, nothing is deleted. New snapshots, images, backups and volumes are refused until there is room ([limits](./limits#storage)).

An item's rate is fixed when you make it. A new price reaches items that already exist only from a date announced ahead, here and in the [changelog](./changelog). Its rate now is under `rates` in `GET /v1/usage`: `storage.stored` for a snapshot or a volume backup, `storage.reserved` for an image and `storage.provisioned` for a volume.

Storage is paid an hour at a time from your balance. The hold covers the most the item can be charged for that hour. The charge is what it used, and the rest is released. Each hour settles within a minute of its end, usually within seconds, and appears in the [usage export](./api#export-settled-usage) from then on.

## Network products

Inbound traffic is free. Each account's first **100 GiB of outbound traffic a month** is free. After that, it costs **$0.02 per decimal GB**. Outbound traffic is what your sandboxes send to the internet, over the connections they open (TCP and UDP). For sandboxes created from 5 October 2026, it also covers what they serve through previews, custom domains and TCP ports, including a desktop's live view. Everything a sandbox receives is not counted. Neither is traffic to your own network over a WireGuard tunnel, traffic to your other sandboxes by name, or your code's calls to Runtime's own API at `http://runtime.internal`. What a sandbox created before 5 October 2026 serves stays free for its life. A sandbox without credit has free traffic, and it uses none of the allowance.

The allowance is shared by all of an account's sandboxes. It starts again on the first of each month, UTC. Traffic is charged from your balance each time a sandbox's compute settles. That happens while it runs, in windows of up to an hour, each settled after it ends. It also happens when it stops or pauses, and whenever you read the [usage export](./api#export-settled-usage), which first settles each running sandbox paid from credit through about a minute ago. Traffic is never held in advance, and it never takes the balance below zero. The rate is fixed in each sandbox's quote, as `egress.outbound` in `rates` for what it sends and `egress.served` for what it serves. `GET /v1/usage` returns the month so far under `outbound`: what was sent, what the allowance covered, and what the rest cost. At $0.02, 1 TB past the allowance costs $20.

A paid sandbox moves up to 500 GiB a day, in and out together. An account without credit moves 1 GiB a day across all its sandboxes. [The network](./sandbox-environment#the-network) has the speeds.

A dedicated IPv4 address costs **$5 per 30-day month**. A WireGuard tunnel costs **$5 per 30-day month**, including up to 16 peers. These are prorated to funded time. Each resource's rate is fixed in its quote. Dedicated IPv6, custom domains (up to 50) and TCP ports are included.

If credit or another spending permission prevents renewal, address and tunnel traffic stops. The reservation stays yours until you release it. Unpaid time is never billed later. A dedicated address never silently switches to a shared outbound address. See [networking](./networking) for funding status and access.

## Pay with stablecoins

Credit can be bought in USDC on Base, Solana or Tempo, from any wallet. `runtime billing topup 50` prints an address per network and the exact amount to send. `--wait` waits until the credit lands. `runtime billing status <id>` says whether the payment arrived. A top-up is $10 to $10,000, and a new account buys at most $500 in its first week.

An agent working with no person can open its own account this way. There is no sign-in, no browser and no card, and no free trial. The account gets its key only once its payment lands. Until a person takes the account over, it earns no [welcome match](#welcome-match) and no referral reward. Payments made after a takeover earn them as they do for anyone.

```bash no-run
npx withruntime billing topup 20 --new-account --accept-terms --wait
```

- `--accept-terms` agrees to the [terms](https://withruntime.com/legal/terms) for whoever the agent acts for.
- It prints a claim code, shown once. It is the only way to the account's key, so keep it secret. `runtime billing claim <code> --wait` fetches the key if the first response was lost.
- `--wait` saves the key on that machine once the money lands. The CLI, SDKs and MCP use it from then on.
- A person can take the account over later at [withruntime.com/account/claim](https://withruntime.com/account/claim) with the claim code.

Over HTTP, with no CLI:

1. Make a claim code: `rtclaim_` and 43 base64url characters from 32 random bytes. Holding it before the first response means a retry finds the same account and opens no second one.
2. `POST https://withruntime.com/api/wallet/topups` with `{"usd": 20, "acceptTerms": true, "claimCode": "rtclaim_…"}` returns 201 with an address per network and the exact amount. Send exactly that amount to one of them.
3. `POST https://withruntime.com/api/wallet/claim` with `{"claimCode": "rtclaim_…"}` returns 202 until the payment lands, then 200 with `apiKey`, once. Store it as `RUNTIME_API_KEY`.

With MCP and no shell, `npx -y withruntime mcp` offers `runtime_wallet_open` and `runtime_wallet_claim` before it is connected. The claim saves the key, and Runtime's tools appear. A remote MCP client with no key connects to `https://api.withruntime.com/mcp?signup=wallet` for the same two tools. Its claim returns the key once, for `Authorization: Bearer <key>` on `https://api.withruntime.com/mcp`.

Every SDK has the two calls: `openWalletAccount` and `claimWalletAccount` in JavaScript, `withruntime.wallet` in Python, `OpenWalletAccount` and `ClaimWalletAccount` in Go, `WithRuntime::Wallet` in Ruby and `Wallet` in Java.

## Auto top-up

Auto top-up adds credit from a saved card when your balance falls below a line you pick, so sandboxes never stop for an empty balance. Turn it on at [Usage & billing](https://withruntime.com/account/billing#auto-top-up). It starts with these settings: when credit falls below $10, add $20, up to $500 in a calendar month (UTC). You can change any of them. The line can be set to any amount from $10. The monthly maximum can be any amount from $100. The amount runs from $20 to $10,000, and $500 in an account's first week, as for any top-up. That is also the most an account adds in 24 hours. The card is saved on Stripe's page. Runtime never sees its number.

- Each automatic top-up earns **5% more as credit** once its charge has gone through. For example, add $20 and you get $21. The extra is granted credit, never cash, and it is used after the month's free usage.
- While auto top-up is on with a saved card, the account runs **200 sandboxes at once** instead of 100, with twice the vCPUs, memory and disk across them. Turning it off returns new starts to 100. Sandboxes already running keep running. A limit set for your account by support or a pilot stays as it is.
- Only one charge runs at a time. The line is checked every minute, and a charge is never repeated for the same fall below the line. Tax is added as on any top-up.
- If the bank declines a charge or asks to confirm it, auto top-up turns itself off, and Usage & billing says why. Nothing that is running stops. Turn it on again, or save another card. Removing the card also turns it off.
- If an automatic top-up is refunded or charged back, its extra credit goes back too, up to what is unspent. A refund is smaller by any of the extra already spent.

Owners, admins and billing members can change it, and so can a key one of them made: `runtime billing auto-top-up on --below 25 --amount 50 --monthly 1000`, `billing.autoTopUp.set()` in the SDK, or `PUT /v1/billing/auto-top-up`. A figure left out keeps the one saved. `runtime billing auto-top-up off` turns it off. `runtime_account_get` in MCP shows it. Only a person can save the card.

## When your balance runs out

While your sandboxes run on paid credit, each owner of the account is told when the balance will last under five days at this month's pace. Each owner is also told when the balance has run out. Each notice is sent once, and again after the next top-up. The notices go to the account inbox and by email. Usage & billing shows the same warning. The account's webhooks are told at the same two moments, with `credit.low` and `credit.empty` ([events](./observability)). `GET /v1/limits` returns the credit left and the days it lasts (`credit.runwayDays`), so an agent can add credit in time. An account opened with a wallet has no person to email, so this is how it hears.

Storage charges stop at zero, and your balance never goes below it. You never owe money. Nothing is lost immediately:

- A stopped or paused sandbox's disk is kept for **30 days** in an account that has bought credit or saved a card. Any other item, and every item in an account that has done neither, is kept for **seven days**. An account notice tells you the date, and a second notice warns you a day before it. Notices go to your account inbox (`runtime_notices` in MCP). The day-before warning is also emailed to the account's owners, from Runtime, in one email for everything it covers.
- Add credit within those days, and charging starts again from then. The days it went unpaid are written off. They are never charged, now or later.
- Once those days pass unpaid, the item is deleted. A volume that a sandbox still uses is deleted once that sandbox lets it go.

Paused sandboxes follow the same rule.

## When a payment is under review

If a card's bank reports a top-up as possibly not the cardholder's, or the card also paid for an account that was suspended or charged back, spending is held while we review it. A request that would spend returns `account_blocked` (402) with that reason. Usage & billing says a payment is under review. Your balance, sandboxes, volumes and images are kept. Nothing is refunded or taken. Spending resumes when the review clears. Write to support@withruntime.com to speed it up. One card paying for two of your accounts is fine on its own.

## Per 1,000 runs

The standard example: 2 vCPUs, 4 GiB, 60 seconds of running time per run, 20 CPU-seconds of work per run, and 1,000 completed runs. A CPU-second is one core busy for one second. Two cores busy for ten seconds use 20 CPU-seconds.

```
CPU:    1,000 × 20 / 3,600 × $0.025 = $0.138889
Memory: 1,000 × 60 / 3,600 × 4 × $0.0075 = $0.500000
Total:  $0.638889, approximately $0.64 per 1,000 runs
```

At 100,000 runs a month, that is $63.89. The figure assumes the CPU floor does not exceed measured CPU. It leaves out taxes, paid disk retention, network charges if any, free credits and retries. Count startup and dependency setup in running time when they are inside the billable interval.

## Published rate comparison

The same example at each provider's published rates, checked 25 October 2026. Each provider's comparison page gives its own date.

| Provider                                                        | CPU and memory for 1,000 runs |              Runtime saves |
| --------------------------------------------------------------- | ----------------------------: | -------------------------: |
| **Runtime**                                                     |          **$0.64** |                          — |
| Northflank, published CPU and memory rates (4 GB)               |           $1.11 |      42% |
| Cloudflare Sandbox, published rates (2 vCPU, 6 GiB, 12 GB disk) |           $1.35 |      53% |
| Prime Sandboxes, published rates (5 GiB disk)                   |                $1.52 |           58% |
| Fly Machines, `performance-2x` with 4 GB, `iad`                 |         $1.53 |    58% |
| Morph, 2 MCUs an hour                                           |                $1.67 |           62% |
| Vercel Sandbox, published `iad1` rates (4 GB)                   |               $2.12 |          70% |
| Freestyle, published rates (32 GiB disk)                        |            $2.25 |       72% |
| Fly Sprites, published rates (4 GB of memory in use)            |          $2.40 |     73% |
| CodeSandbox SDK, a Nano VM (2 cores, 4 GB)                      |          $2.48 |     74% |
| E2B, published per-second rates                                 |                  $2.76 |             77% |
| Daytona, published CPU and memory rates                         |              $2.76 |         77% |
| Blaxel, 4 GB of memory while active                             |               $3.45 |          81% |
| Modal Sandboxes, published rates (1 physical core)              |                $3.97 |           84% |
| AWS Lambda MicroVMs, Arm, US East (a 4 GB baseline)             |      $4.20 | 85% |
| Runloop, a `MEDIUM` devbox (2 CPUs, 4 GB, 8 GB disk)            |              $5.33 |         88% |

Each row's working is on its comparison page:
[E2B](./e2b-alternative), [Daytona](./daytona-alternative),
[Vercel](./vercel-sandbox-alternative), [Modal](./modal-sandbox-alternative),
[Cloudflare](./cloudflare-sandbox-alternative), [Fly.io](./fly-alternative),
[CodeSandbox](./codesandbox-alternative), [Morph](./morph-alternative),
[Northflank](./northflank-alternative), [Runloop](./runloop-alternative),
[Blaxel](./blaxel-alternative), [AWS Lambda MicroVMs](./aws-lambda-microvms-alternative),
[Freestyle](./freestyle-alternative) and [Prime Sandboxes](./prime-sandboxes-alternative).

- E2B and Daytona alike charge $0.0504 per vCPU-hour and $0.0162 per GiB-hour for every allocated vCPU.
- Vercel charges $0.128 per active CPU-hour and $0.0212 per provisioned GB-hour in `iad1`. Other regions differ.
- Modal charges $0.1419 per physical core-hour and $0.0240 per GiB-hour, on whichever is higher of request and use.
- Cloudflare needs at least 3 GiB per vCPU, so its row is priced at 6 GiB.
- Northflank charges $0.01667 per allocated vCPU-hour and $0.00833 per GB-hour. It is the one row where a job that keeps every CPU busy costs less than on Runtime.
- Morph charges $0.05 per MCU-hour. 2 vCPUs and 4 GB is 2 MCUs.
- CodeSandbox charges 10 credits an hour at $0.01486 for a Nano VM.
- Blaxel charges $0.0000115 per GB-second of active time, with CPU included.
- Runloop charges $0.108 per CPU-hour, $0.0252 per GB-hour and $0.00034236 per GB-hour of disk.
- AWS Lambda MicroVMs charge $0.0000276944 per vCPU-second and $0.0000036667 per GB-second of the baseline size while a MicroVM runs, on Arm in US East.
- Freestyle charges $0.04032 per vCPU-hour, $0.0129 per GiB-hour of memory and $0.000086 per GiB-hour of storage, all on the allocation.
- Prime Sandboxes charge $0.02 per vCPU-hour, $0.0125 per GiB-hour of memory and $0.0002 per GiB-hour of disk while running. Rates are published through 22 December 2026.

Plan fees, storage, network, free credits and negotiated prices are left out of every row.

Sources: [E2B pricing](https://e2b.dev/pricing),
[Daytona pricing](https://www.daytona.io/pricing),
[Vercel Sandbox pricing](https://vercel.com/docs/sandbox/pricing),
[Modal pricing](https://modal.com/pricing),
[Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/),
[Fly.io pricing](https://fly.io/pricing/),
[Together: CodeSandbox SDK](https://docs.together.ai/docs/together-code-sandbox-legacy),
[Morph Cloud pricing](https://cloud.morph.so/web/pricing),
[Northflank pricing](https://northflank.com/pricing),
[Runloop pricing](https://www.runloop.ai/pricing),
[Blaxel pricing](https://blaxel.ai/pricing),
[AWS Lambda pricing](https://aws.amazon.com/lambda/pricing/),
[Freestyle pricing](https://www.freestyle.sh/pricing),
[Prime Sandboxes overview](https://docs.primeintellect.ai/sandboxes/overview).

## Security and team features

Everything here is free on every account. There is no enterprise plan, no seat fee and no add-on to buy. A company pays the same rates as one person.

- **Single sign-on** over SAML or OIDC with Okta, Microsoft Entra ID, Google Workspace or any SAML 2.0 or OpenID Connect provider, which an owner can require of everyone else ([single sign-on](./single-sign-on)).
- **Directory sync** over SCIM. Your directory adds people, gives them roles from its groups, and removes them, revoking their keys, the moment they leave.
- **Roles:** owner, admin, developer and billing, for as many people as you need ([teams](./teams#roles)).
- **An audit log** of every change to members, keys, money and security settings, with who, when and from which address. It is kept at least 400 days, downloadable as CSV and readable over the API ([audit log](./teams#audit-log)).
- **Two-step sign-in** with a passkey or an authenticator app, which an owner can require ([two-step sign-in](./security#two-step-sign-in)).
- **Spending and access controls:** read-only keys, a daily spending limit per key, and compartments that keep one team's keys out of another team's work ([read-only keys and daily limits](./security#read-only-keys-and-daily-limits)).
- **A data processing addendum** that is part of the terms for every account ([data processing addendum](/legal/dpa)), and the [uptime promise](#uptime-promise) for every paid account.

The [security and compliance](./trust) page is the summary a security review asks for. For a questionnaire, write to security@withruntime.com.

## Uptime promise

Paid accounts are promised 99% API uptime every calendar month. It is measured by the check from outside our servers that the [status page](/status) publishes. If a month falls short, every paid account receives 10% of that month's charges back as service credit in the first week of the next month. No request is needed. The credit is added automatically, the account's owners are emailed, and the billing page lists it. The full terms are in the [Uptime Promise](/legal/sla).

**A server that fails is not charged for.** If the server a sandbox runs on stops responding to Runtime, the sandbox is charged only up to the last moment it responded. Time a server holds a sandbox frozen because it cannot reach Runtime is not charged either, for memory or CPU.

## Welcome match

Credit your organization adds within 30 days of signing up is matched with credit, up to $1,000 in total. There is nothing to claim. Add credit at [Usage & billing](https://withruntime.com/account/billing#add-credit), and the match lands beside it. Home and the billing page show how much of the $1,000 is used and when the offer ends.

- Every payment in those 30 days counts, not only the first. Add $20 and then $500, and you get $520 more. Add $800 and then $500, and you get $1,000 more. Credit added after day 30 is not matched.
- The credit lands when each payment settles, whether you pay by card or through Link. Paid through a wallet that tells us neither the card nor the Link account, it lands once someone at Runtime has checked it.
- The match is granted credit. It is used after the month's free usage, and it expires 12 months after it is given.
- It does not stack with a [referral](./referrals). If you signed up through a referral link, the referral matches your payments instead, the same $1,000 over the same 30 days, and it is never smaller.
- One payer, one match: a card or Link account whose payment was matched for another organization is not matched again.
- If a payment is refunded or charged back, its matching credit goes back too, up to what is unspent. A refund of that payment is smaller by any of its matching credit already spent. The rest of the match stays. What was taken back can be matched again within the 30 days.

Moving from E2B, Daytona, Vercel Sandbox, Modal, Cloudflare, Fly or Blaxel? `runtime switch --from e2b` records where you came from, so `runtime compare` and Runtime know what you left. Your credit is matched as everyone's is. `runtime switch` on its own shows the match: how much is used and left, and how long you have.

## Check it on your own workload

Once you have run on Runtime, `runtime compare` prices your own sandboxes both ways:

```bash check
runtime compare --from e2b
```

It takes your settled sandboxes from the last 30 days (`--days` up to 90). It prices them at the rates you were quoted. It also prices the same vCPUs, memory and running time at the rival's published rates from the table above. Sandboxes that free usage paid for are priced at the standard rates. That is what the same work costs on paid credit, and the output says how many there were. Then it says what you save, and about how much that is a month. With no sandboxes yet, it prices an example and says so. It compares compute only. Storage, network, plan fees and free allowances are left out. The same figures come from `GET /v1/usage/compare` and the `runtime_account` MCP tool with action `compare`, in microdollars.

To compare a workload you have not moved yet, ask your agent:

“Compare my last 1,000 completed runs with Runtime. Use the same measured job behavior, include my current discounts and required features, show all inputs, and separate estimated savings from measured savings.”


---

<!-- https://withruntime.com/docs/prime-sandboxes-alternative -->

# Runtime vs Prime Sandboxes

Runtime and Prime Sandboxes both give every sandbox a microVM with its own kernel. For an agent that mostly waits on a model, Runtime costs **58% less**. Runtime can also pause and fork today.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $1.52 on Prime Sandboxes**. At 100,000 runs a month, that is $63.89
against $151.67, **$88 a month saved**.

Comparing more than two providers? [Prime Sandboxes alternatives](/compare/prime-sandboxes-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Prime bills the vCPUs, memory and disk a
  sandbox is given for as long as it runs. Runtime measures the CPU your code
  actually uses. Time spent waiting on a model costs only a small floor, a twentieth of a vCPU. Even with both CPUs busy the whole minute, the example
  job costs $1.33 on Runtime and $1.52 on Prime.
- **Waiting costs storage, not compute.** Left idle for 300 seconds, a Runtime sandbox pauses by
  itself with its memory kept. While paused, it pays $0.08 per GB (10⁹ bytes) a
  month until a request wakes it.
- **A written uptime promise.** Paid accounts get 99% API uptime a month,
  measured from outside. If a month falls short, 10% of that month's charges
  is returned as credit automatically ([Uptime Promise](/legal/sla)).
- **Cheaper memory.** $0.0075 per GiB-hour, against Prime's $0.0125. Memory
  is most of what an agent sandbox costs while it waits.
- **Pause and fork with memory.** A paused Runtime sandbox keeps its memory and
  running processes while you have credit. A fork copies a running sandbox into
  up to 100 copies. Prime's checkpoints and forks save the
  filesystem only: processes start fresh and nothing in memory carries over.
- **Prices that do not lapse.** Prime's published rates hold through
  22 December 2026. Runtime's rates are fixed in each resource's quote. There is
  no plan fee: prepaid credit from $10.
- **Secrets stay outside the sandbox.** Code inside sees a placeholder. The
  real key is added at the egress proxy, only on HTTPS to the hosts you allow
  ([security](./security)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.
- **Guardrails for agents.** Read-only keys, a daily spending limit per key and
  `maxTotalCostMicros` on each sandbox keep an agent inside its budget. Every
  write takes an idempotency key.

**Also included:** a code interpreter, network allow and deny lists, custom
images, volumes backed up daily, private previews, a Linux desktop, metrics,
webhooks, OpenTelemetry export, S3, R2 and GCS bucket mounts, identity tokens for AWS and Google Cloud, and free single sign-on. Paid
accounts add custom domains, TCP ports, dedicated outbound addresses and
WireGuard private networks. See [products](./products).

## At a glance

Prime's figures come from its sandbox documentation and launch post. Last checked
25 October 2026.

|                      | Runtime                                                        | Prime Sandboxes                                    |
| -------------------- | -------------------------------------------------------------- | -------------------------------------------------- |
| Isolation            | Firecracker microVM, own kernel                                | Hardware-virtualized microVM, own guest kernel     |
| CPU billing          | $0.025 per vCPU-hour of measured CPU, with a small floor | $0.02 per vCPU-hour while running     |
| Memory billing       | $0.0075 per reserved GiB-hour                          | $0.0125 per GiB-hour while running   |
| Disk while it runs   | Included                                                       | $0.0002 per GiB-hour; 5 GiB by default |
| Sizes                | Up to 16 vCPUs and 64 GiB paid, chosen apart | Up to 16 vCPUs, 64 GiB and 128 GiB of disk         |
| Pause and fork       | Files, memory and processes; forks of a running sandbox        | Filesystem checkpoints and forks; no memory        |
| Concurrent sandboxes | 100 on a paid account                           | 1,024 per account to start                         |
| Plan fee             | None; prepaid credit from $10                        | None; rates published through 22 December 2026     |
| Free start           | 100 free hours of a 1 GB machine in the first 30 days, no card             | None published                                     |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds. This is an agent that spends most of its time
waiting for a model. Prime's sandbox keeps its default 5 GiB disk.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025          = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075     = $0.50
         Total                                            $0.64

Prime    CPU    1,000 × 60 s / 3,600 × 2 × $0.02       = $0.67
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0125     = $0.83
         Disk   1,000 × 60 s / 3,600 × 5 × $0.0002     = $0.02
         Total                                            $1.52
```

- **Saving:** 58%, or $0.88 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $151.67 on Prime.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $1.52 on Prime. At this size, Runtime is cheaper however busy the
  sandbox is.

Network, taxes and free allowances are excluded from both. On Runtime, inbound
traffic is free. Each account's first 100 GiB out a month is free, then
$0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Prime calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

An RL rollout that sets up an environment once and runs many episodes from it
is a good fit for a fork. Install once, then start every episode from the same
running machine.

```ts check
import { Sandbox } from "withruntime";

await using base = await Sandbox.create();
await base.exec("pip install --quiet numpy");
const episodes = await base.fork({ count: 4 }); // four running copies, memory included
await Promise.all(episodes.map((episode) => episode.stop()));
```

## When Prime Sandboxes may fit better

- **Thousands running at the same time from day one.** An account starts at 1,024 active
  sandboxes and 4,096 vCPUs. A paid Runtime account runs 100, and raises it on request.
- **Training on Prime Intellect.** Prime Sandboxes are built for agentic RL
  training on Prime's own platform. Prime Tunnels reach inference running
  on its cluster nodes.

## Sources

Checked 26 October 2026.

- [Prime Sandboxes overview](https://docs.primeintellect.ai/sandboxes/overview)
- [Prime Sandboxes launch](https://www.primeintellect.ai/blog/sandboxes)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/products -->

# Your Runtime Cloud account

One account owns every Runtime Cloud resource, its agent connections and its prepaid credit.

One key, one API, one SDK and one CLI reach every product. They share the same
resource shape, errors, idempotency, pages and labels. The console at
withruntime.com/account shows what you can use today. An SDK method is not a
promise that another product is available.

## Products

| Product             | What it is                                                                                       | Status    |
| ------------------- | ------------------------------------------------------------------------------------------------ | --------- |
| Sandboxes           | Linux microVMs: commands (kept 14 days by name), processes, terminals, files, pause and wake     | Available |
| Code interpreter    | A notebook-style session inside a sandbox in Python, JavaScript, TypeScript, R, Java, Bash or Go | Available |
| Network rules       | Per-sandbox internet, allow and deny lists; every port with a kept top-up                        | Available |
| Secrets             | API keys sandboxes use without seeing, added by the egress proxy                                 | Available |
| Images              | Custom sandbox images from a recipe, any image or a Dockerfile, versioned and tagged             | Available |
| Volumes             | Persistent disks attached to sandboxes, backed up off their server daily                         | Available |
| Snapshots           | Saved sandboxes, disk and memory, to start and fork from                                         | Available |
| Previews            | An HTTPS address for a port in a sandbox, private by default                                     | Available |
| Desktop             | A Linux desktop in a sandbox, driven by clicks and keys                                          | Available |
| Metrics             | Each sandbox's measured CPU and memory over time, on its own page too                            | Available |
| Webhooks            | Signed lifecycle events POSTed to your URL, with retries and a log                               | Available |
| OpenTelemetry       | Events as logs and CPU and memory as metrics, pushed over OTLP/HTTP                              | Available |
| Bucket mounts       | Your S3, R2 or GCS bucket as a directory in a sandbox                                            | Available |
| Custom domains      | Your own hostname for a sandbox port, with HTTPS; a kept top-up                                  | Available |
| TCP ports           | A public TCP port to a sandbox port; a kept top-up                                               | Available |
| Dedicated addresses | A dedicated outbound IPv4 address, with IPv6; accounts with credit                               | Available |
| Private networks    | The tunnel: WireGuard from your network to your sandboxes, up to 16 peers; a kept top-up         | Available |
| Identity tokens     | Signed tokens a sandbox uses to reach AWS, Google Cloud and others without stored keys           | Available |
| Single sign-on      | Sign in through your company's OIDC or SAML provider; SCIM adds and removes people; free         | Available |

**A fork or a snapshot keeps a sandbox's files, memory and running processes.**

- A snapshot stays on the server of the sandbox it came from. Forks and
  sandboxes started from it run there too. It is also copied off that server,
  so it survives losing it ([storage and backups](./storage)).
- A sandbox with volumes cannot be snapshotted.
- A snapshot or a fork of a running sandbox usually holds its memory as it was
  when the request arrived. The sandbox stops immediately and stays stopped until
  its memory is written to disk, then runs again. Several snapshots and forks
  on one server at the same time take their turns at the disk while their sandboxes are
  stopped. A sandbox whose time limit or funded time ends soon, on a busy
  server, keeps running until its turn at the disk instead, and stops then.
  Its snapshot, or its fork's copies, hold that later moment.
- To install dependencies once and start many sandboxes from them, build a
  [custom image](./javascript#custom-images) and create each sandbox from it.

Start with [getting started](./start). Then check
[the sandbox environment](./sandbox-environment) and [security](./security)
against your workload.

New products join the same namespaces as they launch: `runtime.<product>` in
the SDKs, `runtime <product> <command>` in the CLI, `/v1/<products>` in the API
and `runtime_<product>_<verb>` in MCP.

## The console

The sidebar holds everything. At its top is your account. Its menu switches
account and holds Refer & earn, Support, the documentation, Runtime's status and
Sign out. Under it are **Search or create**, **Home**, then **Sandboxes**,
**Images** and **Volumes**. At its foot are **Usage & billing**, with your credit
(or the free usage left) beside it, and **Settings**. New accounts begin with a
focused connection flow until their first sandbox has started.

- **Home** is today's report. **Needs you** comes first when something does. That
  includes a sandbox that failed to start or wake, or credit or free usage about to
  run out (credit five days ahead at this month's pace). Next are the few things a
  person still does by hand: connect another agent, open a terminal in a
  running sandbox, make a key and start a sandbox. Then come sandbox
  time today, hour by hour beside the same hour yesterday, counted in your
  browser's time zone. Also shown are this month's spend by product and where it is heading.
  Then the last five things that happened. Last, the account in lines: credit and how
  long it lasts, what runs now and how many started today, your images and
  volumes, and who started today's sandboxes.
- **Agents & API keys**, the first page of **Settings**, lists every key in two
  groups. **Agents** are connected
  from an agent tool such as Claude Code, Cursor or Codex. Each shows the tool and
  machine it connected from. **API keys** are made for a script, CI or a
  dashboard. Each says when it last started something, what it may do and its
  daily spending limit. Beside the list are today's starts hour by hour, by who
  started them, and each key's spend over the last 24 hours against its limit.
  **Needs you** names a key whose
  limit is refusing its starts, and a full-access key that has started nothing
  for 30 days. Nothing is revoked for you.
- **Search or create**, or ⌘K (Ctrl+K), opens one search box. It goes to any
  page or resource and starts anything. Each start shows the CLI command and SDK call
  that does it, ready to copy.
- **Sandboxes** describes today's runs as a whole. It shows how many started, how many
  failed, how long they typically live and what they cost. It also shows starts per hour
  beside yesterday, how long the runs that ended lived, and tables by who
  started them and by image. A create Runtime refused leaves no sandbox. That covers an image that does not
  exist, a limit, or credit run out. Such a refused create is counted here too,
  with the reason and the image asked for. **Needs you** says when failures
  rise above your usual rate, when creates are being refused, or when
  sandboxes run far longer than yours usually do. The list opens on those
  running now. Today's failures are one tab away, with their reasons in words.
  Search finds any sandbox by name or ID, from any day.
- A **sandbox's page** says how it ended, how long it lived, who started it and
  from which image. For a sandbox that did not end by request, it says why and what to
  do. Its life is drawn start to stop. **Copy for my agent** copies what
  happened, ready to paste. **Start one the same** copies the command that makes
  an identical one. While it runs, its tabs are Overview, Terminal, Files,
  Activity and Settings. **Terminal** is a shell in the browser
  ([how it signs in](./security#the-browser-terminal)).
- **Images** leads with a failed build and the line it broke on. It also leads with a name
  or tag your agents keep asking for that no image has. Then come today's
  starts, the share from your own images and the typical start time. Next is starts a
  day by image, beside the last 14 days of builds. Last is a row for each image, with its
  starts today, start time, failures, versions kept and cost. An image nobody
  started in 30 days offers the command that deletes it. An image's page shows
  every version with its tags and the build log, live while it builds.
- **Volumes** leads with a volume nearly full or behind on its backups. Then
  it shows how many sandboxes used your volumes today. It also shows cost a day by volume beside the
  sandboxes that used each, for the last 14 days. Last is a row for each volume,
  with how full it is, how many used it today and who, and its last backup. A
  volume's page shows how full it is, where it is attached and its backups.
  Both give the commands that change them.
- **Usage & billing** opens on your credit, with adding credit in place and the
  referral offer at its foot. Then comes the month in a line. It shows what the same sandboxes would have cost at the provider you came
  from (E2B when we do not know) over the last 30 days, at its published rates.
  It also shows daily spend by product, with where the month is heading, beside daily spend
  by who started it. Last, it shows what each meter came to, with its rate, beside each key's
  spend over the last 24 hours against its daily limit. Its ledger lists
  purchases, referral credit and the welcome match, refunds and the free usage. A card
  purchase links to its Stripe receipt.
- **Settings** holds Agents & API keys, webhooks, members, single sign-on, the
  audit log and two-step sign-in, in groups in the sidebar.

The website acts on a sandbox with the same rights as your API keys. Owners and
admins may stop, pause, wake, snapshot, fork and open a terminal in any of the
account's sandboxes. Developers can do so in the sandboxes their own agents started.
Billing members add credit and act on no sandbox.

What Usage & billing counts:

- Spend is settled service usage, not a count of payments or reserved credit.
- Charges use integer microdollars: one million equals one US dollar.
- Daily and monthly summaries use UTC.
- `npx withruntime usage` and `GET /v1/usage` give the same figures. Each
  resource's immutable quote and the [pricing guide](./pricing) say what it
  meters.

An agent connection has its own identity and revocable credential. Keys cover
all Cloud products, including products enabled later. They last until revoked.
Browser sign-out does not revoke them. See
[security and access](./security) before connecting an agent.

An account can have several people. Each is an owner, admin, developer or billing
member. The account keeps an audit log of changes to members, keys, credit and security
settings. See [teams and the audit log](./teams).

## Labels and names

Sandboxes, images, volumes and snapshots take a `name` and up to 32 `labels`,
and their lists filter by them:
`npx withruntime sandboxes ls --label team=search`,
`GET /v1/sandboxes?label=team:search`. Use them for tenants, jobs and cost
attribution.


---

<!-- https://withruntime.com/docs/python -->

# Python SDK

One Python client for every Runtime Cloud product, sync and async, method for method.

`withruntime` needs Python 3.9 or later. The `python3` that comes with a Mac is
enough. It uses only the standard library. It imports in about 30 ms and keeps
its connections open between calls.

```bash no-run
pip install withruntime
```

This guide describes `withruntime` 0.45.1. `pip show withruntime` shows the
version you have. A method named here that yours lacks means an older version.
Run `pip install -U withruntime` to update it.

**The client finds its key by itself.** It uses `RUNTIME_API_KEY` when that is
set. Otherwise, it uses the connection this machine saved. Any `npx withruntime`
command sets up that connection, with one browser approval.

On a server, store a key from https://withruntime.com/account/keys in
`RUNTIME_API_KEY`, from your secret manager. Never put it in source code, a URL
or a command-line argument. With no key anywhere, the first call fails with
`missing_api_key`, and the error says how to get one.

One plural word names each product, as in the CLI, the API and MCP. A name
renamed on 6 October 2026 keeps working for 30 days after the rename ships. Each
use raises a `FutureWarning` with the new name. After that, it fails with
`name_retired`, and a hint names the new one.

| Product                      | Old name                               |
| ---------------------------- | -------------------------------------- |
| `runtime.sandboxes`          | `runtime.sandbox`                      |
| `runtime.snapshots`          | `runtime.snapshot`                     |
| `runtime.images`             | `runtime.image`                        |
| `runtime.volumes`            | `runtime.volume`                       |
| `runtime.jobs`               | `runtime.job`                          |
| `runtime.domains`            | `runtime.domain`                       |
| `runtime.ports`              | `runtime.port`                         |
| `runtime.ips`                | `runtime.address`, `runtime.addresses` |
| `runtime.networks`           | `runtime.network`                      |
| `runtime.networks.wireguard` | `runtime.tunnel`                       |

## Hello, sandbox

Write a file that totals three invoice amounts, then run it; the total is 750.

```python
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n")
    result = sbx.exec("python3 /workspace/invoice.py")
    print(result.exit_code, result.stdout)  # 0, "750\n"
```

`Sandbox.create()` takes no required arguments and returns once the sandbox is
running. Leaving the `with` block deletes it, even after an exception; create it
with `keep=True` to stop it instead and keep its disk.

With no arguments you get the free usage while it lasts, the default region, and
2 vCPU, 4 GiB of memory and a 4 GiB disk, running while it works and pausing
itself when idle, with no time limit. A paid sandbox
can have up to 16 vCPUs and 64 GiB; one without credit, 2 vCPU and
4 GiB.

The free usage is spent first, then prepaid credit, with nothing for you to
choose. `funding` is accepted and ignored.
Every field is optional and takes snake_case names:

```python
from withruntime import Runtime

runtime = Runtime()  # RUNTIME_API_KEY, or this machine's connection
sbx = runtime.sandboxes.create(
    name="tests-42",
    labels={"team": "search", "job": "42"},
    vcpu=2,
    memory_mib=4096,
    disk_mib=8192,
    timeout_seconds=900,
    on_lease_end="stop",
    network={"internet": True, "allow": ["pypi.org", "*.pythonhosted.org"]},
)
print(sbx.id, sbx.info["funding"], sbx.info["endsAt"])
sbx.stop()
```

A sandbox needs no time limit: it runs while it works and pauses itself when
idle, until you stop it or credit or the [free usage](./included-usage) runs out.
`timeout_seconds` (60 to 86,400, 24 hours) sets a limit when you want one. In that
case, it pauses or stops, as `on_lease_end` says, busy or not. `sbx.info["endsAt"]` is
when it will stop or pause by itself, or `None` when it never will.

`env` sets variables for every command, background process, terminal, SSH
session and image start command in the sandbox, for its whole life. A command's
own `env` takes precedence over them. Values are never shown again. `sbx.info`
and every later response carry only `envNames`. `update(env=...)` changes them.
A value sets a variable, and `None` removes one. The change applies to commands
started after it. At most 32 variables and 32 KiB.
Forks keep them ([API](./api#sandboxes)).

```python check
from withruntime import Runtime

runtime = Runtime()
sbx = runtime.sandboxes.create(env={"QUEUE_URL": "https://queue.example.com", "MODE": "worker"})
print(sbx.info["envNames"])  # ['MODE', 'QUEUE_URL']
sbx.update(env={"MODE": "drain", "QUEUE_URL": None})
sbx.delete()
```

The async client is the same with `await`:

```python
import asyncio
from withruntime import AsyncRuntime


async def main():
    async with AsyncRuntime() as runtime:
        async with await runtime.sandboxes.create() as sbx:
            results = await asyncio.gather(*(sbx.exec(f"echo {i}") for i in range(10)))
            print([r.stdout.strip() for r in results])


asyncio.run(main())
```

## Run commands

A string runs under `bash -c`. A list runs the program directly, with no shell.
Use a list for untrusted arguments.

**A server, a watcher or anything that should keep running goes in
[`spawn`](#background-processes), not `exec`.** Everything an `exec` starts,
`nohup … &` and `setsid` included, ends when its command returns. A result holds
all of the command's output (see below).

```python
import os
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.exec("mkdir -p app && echo 'print(1 + 1)' > app/main.py")
    run = sbx.exec(
        ["python3", "main.py"],
        cwd="/workspace/app",
        env={"API_TOKEN": os.environ.get("API_TOKEN", "")},
        timeout_ms=120_000,
    )
    if run.exit_code != 0:
        print(run.stderr)
```

- `env` is how secrets reach a command. It is never echoed back, and journals
  record a hash, not the value. Never put a secret in the command line itself.
- `stdin` gives the command input, then closes it.
- `user="root"` runs the command as root, with no `sudo` in front: its `env`,
  `PATH` and working directory stay the same and `HOME` is `/root`. The
  default, `"sandbox"`, is the user `runtime`. `spawn` and `terminal` take it
  too, and a process's `user` says which it runs as.
- The default timeout is 60 seconds, or what the sandbox's time limit has left
  when that is less. When the output streams (`on_stdout`, `on_stderr` or
  `exec_stream`), the default is 24 hours. The maximum is 24 hours. A command
  with no `timeout_ms` is never refused for the time limit. A timeout is a
  result (`timed_out=True`, with the output so far), not an exception.
- `check=True` raises `CommandError` on a non-zero exit.
- A command that the sandbox's out-of-memory killer ended has `out_of_memory` set
  on its result and its process. The value holds the code, processes killed, the
  sandbox's size, a message and a hint. With `check=True`, `CommandError` is
  raised with the code `out_of_memory`. `None` means it was not ended for memory
  ([when a program runs out of memory](./sandbox-environment#when-a-program-runs-out-of-memory)).
- A result holds all of `stdout` and `stderr`, up to 256 MiB of each; with
  `on_stdout` or `on_stderr` there is no limit.
  `stdout_bytes` and `stderr_bytes` give the bytes each stream wrote.
  `max_output_bytes=n` keeps at most `n` bytes of each stream; `stdout_truncated`,
  `stderr_truncated` and `truncated` are then `True` for a stream that was cut.
  Otherwise they are `False`.

Stream output as it happens with callbacks, or iterate the events:

```python
import sys
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.exec("for i in 1 2 3; do echo line $i; sleep 1; done", on_stdout=sys.stdout.write)
    for event in sbx.exec_stream("npm --version"):
        if event["type"] == "stdout":
            print(event["data"], end="")
        elif event["type"] == "exit":
            print("exit", event["exit_code"])
```

`exec_stream` events expose snake_case fields, including `process_id`,
`exit_code`, `timed_out`, `duration_ms`, `stdout_truncated`,
`stderr_truncated`, `dropped_bytes` and `resume_at`, when the event carries
that value. The earlier camelCase keys still work, with the same values.

While you read a command's stream, the command waits for you instead of losing
output, from its first byte. The sandbox keeps the latest 1 MiB. A reader that is
away for more than 10 seconds, while more than that came out, loses the oldest
part. That reader gets a `truncated` event, and the result has both truncation
flags set to `True`. From withruntime 0.7.0, a stream whose connection drops
after the command started picks up again from the right byte. If it cannot, it
raises `ConnectionError` with `details["processId"]`, and the command may still
be running. Ctrl-C, or cancelling the task, during a streamed `exec` sends the
command SIGTERM.

## Background processes

```python
from withruntime import Sandbox

with Sandbox.create() as sbx:
    server = sbx.spawn("python3 -m http.server 8000", cwd="/workspace")
    print(server)  # Process(id=..., sandbox_id=..., command=..., state='running', exit_code=None)

    repl = sbx.spawn(["python3", "-i", "-q"], stdin="pipe")
    repl.write("print(sum([125, 250, 375]))\n")
    repl.write("exit()\n", eof=True)
    print(repl.wait().stdout)

    for process in sbx.processes():
        print(process["id"], process["state"], process["command"])
    server.kill("SIGTERM")
```

`process.write()` tracks accepted input offsets and keeps concurrent writes in
order. When the process accepts only part of the input, later chunks match its
capacity; when its input pipe is full, the SDK waits briefly before retrying
without advancing the offset. An empty EOF write closes input after earlier queued writes finish.

`process.output(cursor=0)` yields every event from the start until the process
exits. A process outlives your connection. Get it back with `sbx.process(id)`.
The sandbox keeps each process's latest 1 MiB of output. A reader that was away
while more than that came out gets a `truncated` event saying how many bytes are
gone, and `wait()` sets both truncation flags. A process that prints more than
1 MiB should write to a file.

## An interactive terminal

```python
from withruntime import Sandbox

with Sandbox.create() as sbx:
    term = sbx.terminal(cols=120, rows=40)
    term.write("echo hello from the terminal\n")
    term.write("exit\n")
    while (chunk := term.recv()) is not None:
        print(chunk.decode(errors="replace"), end="")
```

## Files

```python
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.files.write("/workspace/data/input.csv", "a,b\n1,2\n")
    text = sbx.files.read_text("/workspace/data/input.csv")
    data = sbx.files.read("/workspace/data/input.csv")  # bytes
    print(sbx.files.exists("/workspace/data/input.csv"), sbx.files.stat("/workspace/data/input.csv"))
    for entry in sbx.files.list("/workspace", depth=2):
        print(entry["type"], entry["size"], entry["path"])
    print(sbx.files.glob("**/*.csv"))
    sbx.files.mkdir("/workspace/out")
    sbx.files.rename("/workspace/data/input.csv", "/workspace/out/input.csv")
    sbx.files.remove("/workspace/data", recursive=True)
```

`write` makes parent directories and replaces the file atomically. Large files go
in parallel chunks, checked by SHA-256. Under `/workspace`, there is no size limit
beyond the disk. Elsewhere, a file is written with the sandbox user's own rights,
and can be at most 1 MiB. For a larger file, write it to `/workspace`, and move
it with a command. Whole directories travel as one archive:

```python
import pathlib
import tempfile
from withruntime import Sandbox

project = pathlib.Path(tempfile.mkdtemp())
(project / "main.py").write_text("print('hi')\n")

with Sandbox.create() as sbx:
    sbx.files.upload(str(project), "/workspace/project")
    sbx.exec("cd project && python3 main.py > result.txt")
    sbx.files.download("/workspace/project", str(project.parent / "project-out"))
```

An uploaded file keeps its permissions; `write(path, data, mode=0o755)` sets
them (0o644 when left out).

`files.archive(path, gzip=True, exclude=None, user="sandbox")` returns the
folder's tar bytes, gzip-compressed by default. `exclude` holds plain relative
paths, not globs. `files.unarchive(path, data, gzip=None, user="sandbox")`
merges archive bytes into the destination and detects gzip when omitted. Pass
`user="root"` explicitly for root-owned trees; this requires passwordless
`sudo` inside the sandbox.

```python check
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.files.write("/workspace/project/report.txt", "total: 750\n")
    archive = sbx.files.archive("/workspace/project")
    sbx.files.unarchive("/workspace/restored", archive)
    print(sbx.files.read_text("/workspace/restored/report.txt"))
```

A directory download keeps the links inside the directory. It raises
`unsafe_archive` for any entry or link that would reach outside it. So nothing
in a sandbox can write elsewhere on your machine. The download also checks links
against files already in the destination, before publishing. Invalid checksums,
malformed path metadata and incomplete tar end markers are refused. Compressed
archives are unpacked in bounded pieces. This adds no limit on the total
downloaded directory size.

From `withruntime` 0.7.0, reads are checked. The API sends every file's length
before its bytes, and a small file's SHA-256. If a file arrives short, `read`
reads it again. If it is still short, `read` raises `download_incomplete` rather
than return part of it. `read` has no size limit. For a file too big to hold in
memory, `read_stream` yields the bytes as they arrive, and raises if they end
short. `download` streams to disk through a partial file. That file is renamed
into place only once it is whole:

```python no-run
with open("dataset.tar", "wb") as out:
    for piece in sbx.files.read_stream("/workspace/dataset.tar"):
        out.write(piece)
```

`upload` and `download` of a directory move one tar archive through the API's
folder routes. Those routes pack and unpack it with `tar` inside the sandbox.
Any language can call them with a plain PUT or GET ([files in the API guide](./api#files)).
A downloaded folder is unpacked as it arrives. Its size is limited only by your
disk. It lands in place only once it has all arrived.

A sandbox holds at most 4 uploads and 4 downloads at a time. More wait for
`transfer_limit` to clear. Each frees its slot when it ends. A download left
unread for a minute gives its slot to the next one.

### Watch files

`files.watch` streams changes under a directory: create, write, remove, rename
(with the old path) and chmod. Repeated writes to one file inside a batch come
as one event with a count. It is E2B's `watch_dir`, with filters, and a watch
survives a pause: `events()` stops with `exit_reason == "paused"`, and calling
it again after the sandbox wakes carries on from the same place.

```python check
from withruntime import Sandbox

with Sandbox.create() as sbx:
    watch = sbx.files.watch("/workspace", recursive=True, exclude=["node_modules", ".git/**"])
    sbx.exec("echo hi > /workspace/note.txt")
    for event in watch.get_new_events(wait_ms=2000):  # or: for event in watch.events()
        print(event["type"], event["path"])
    watch.stop()
```

A sandbox runs at most four watches. Each ends after `timeout_ms` (one hour by
default). A flood of changes is capped at 5,000 events a second. Such a flood is
reported as an `overflow` notice in `watch.notices`, and is never dropped silently.

`webhook=True` has Runtime read the watch and send its changes to your
account's [webhooks](./observability#events) as `sandbox.files.changed`
events, so nothing has to read it here; `timeout_ms=0` keeps it running until
stopped. It never keeps a sandbox that pauses itself awake.

```python check
from withruntime import Sandbox

with Sandbox.create() as sbx:
    watch = sbx.files.watches.start("/workspace/app", recursive=True, webhook=True, timeout_ms=0, id="sync")
    sbx.files.watches.stop("sync")
```

## Pause, wake, extend

```python check
from withruntime import Sandbox

sbx = Sandbox.create(timeout_seconds=600)  # a ten-minute limit
sbx.exec("echo state > /workspace/state.txt")
sbx.pause()  # memory and files are kept; compute billing stops
again = Sandbox.connect(sbx.id)
again.wake(timeout_seconds=1200)  # a new limit, from the wake
again.extend(600)  # moves the limit ten minutes on
again.stop()
```

A sandbox created without `timeout_seconds` has no limit, so `wake()` needs no
argument. `extend()` returns immediately and changes nothing.

`pause()` returns once the sandbox's processors have stopped, which is where
compute billing ends; the host then writes its memory to disk, and a wake or
snapshot asked for meanwhile waits for that write.

A paused sandbox also wakes by itself when a request needs it: an `exec`, a
file, process, terminal, desktop or code-interpreter call, or a visit to one of
its shared ports. The wake is billed like any wake, from the moment it runs
again, and it again runs while it works. A sandbox with a time limit gets a
fresh one of its own `timeout_seconds`, or keeps the one it paused with when
that ends later. Turn it off with `auto_wake=False` at create or
`sbx.update(auto_wake=False)`. A call to a paused sandbox then fails with
`sandbox_paused` until you call `wake()`.

A sandbox that paused for being idle also wakes when a process in it is due on
a timer, such as a `sleep 600` loop
([timers](./sandbox-environment#timers-wake-an-idle-sandbox)). To keep request
wakes and turn this off, use `wake_on_timers=False` at create or
`sbx.update(wake_on_timers=False)`.

A sandbox pauses itself after **300 seconds** in which nothing happens in it: no
request, no command or terminal still running, no open preview, port, SSH or
tunnel connection, no network traffic, and its processes using under a fortieth
of a vCPU. The next request wakes it. `idle_pause_seconds` sets the idle time:
60 to 86,400 seconds, or 0 for never. A `persistent` sandbox has none unless you
set it.

```python check
from withruntime import Sandbox

sbx = Sandbox.create(idle_pause_seconds=600)
sbx.update(idle_pause_seconds=1800)  # 0 turns it off
sbx.stop()
```

### Keep a sandbox running

A sandbox with no time limit keeps running while it works, with nothing to
renew. `persistent=True` goes further: it keeps a paid sandbox running until
you stop it, idle or not, for as long as the account has credit. Its disk is
billed and kept, as for any sandbox, so after a stop `sbx.restart()` starts it
again. `update(persistent=False)` makes it an ordinary sandbox again;
`delete()` removes it. `keep_alive()` moves a time limit on from your process, for a
sandbox created with `timeout_seconds`, keeping ten minutes ahead, until
`stop()` or the function it returns; on one with no limit it only watches.

```python check
from withruntime import Sandbox

server = Sandbox.create(persistent=True, max_total_cost_micros=50_000_000)
server.update(persistent=False)  # back to an ordinary sandbox

worker = Sandbox.create(timeout_seconds=3600)  # a one-hour limit, moved on below
release = worker.keep_alive(margin_seconds=1800)
release()
worker.stop()
```

## Sandboxes by name

A name is unique in the account while its sandbox can still run: running,
paused, or stopped and persistent. A key in a
[compartment](./security#compartments) has its compartment's own names. `Sandbox.get_or_create(name)` returns that
sandbox. It wakes the sandbox if paused, and restarts it if stopped and persistent.
Otherwise, it creates one with the fields you pass. `sbx.info.get("reused")` is
`True` when it found one. A create with a name another sandbox holds fails with
`name_taken`.

```python check
from withruntime import Sandbox

dev = Sandbox.get_or_create("dev", idle_pause_seconds=900)
dev.exec("git pull || true")
```

## Find sandboxes again

```python
from withruntime import Runtime

runtime = Runtime()
for sbx in runtime.sandboxes.list(labels={"team": "search"}, state=["running"]):
    print(sbx.id, sbx.info["name"], sbx.state)
```

Every list returns a page: `page.data`, `page.has_more`, `page.next_page()`,
`page.to_list()`, and a `for` loop walks every item on every page.

`runtime.sandboxes.stop_all(labels={"team": "search"})` stops every live
sandbox with all those labels, eight at a time, and returns
`{"stopped": [...], "failed": [...]}`: one failure does not stop the rest. It
needs at least one label. `runtime.sandboxes.delete_all(labels={"team": "search"})`
deletes for good every sandbox with all those labels, stopped ones too, the
same way, and returns `{"deleted": [...], "failed": [...]}`.

## Delete a sandbox

`sbx.delete()`, or `runtime.sandboxes.delete(sandbox_id)` without reading it
first, removes a sandbox for good in any state: it stops it, deletes its disk
and paused memory, revokes its previews and ports, frees its name and takes it
out of every list. Its snapshots, usage and audit entries stay. Deleting it
again returns the same `{"id", "status": "deleted", "deletedAt"}`; any other
call to it then raises `NotFoundError`. `stop()` is the one to use when you may
want a persistent sandbox's disk back.

## Errors and retries

```python
from withruntime import NotFoundError, RuntimeAPIError, Sandbox

try:
    Sandbox.connect("00000000-0000-4000-8000-000000000000")
except NotFoundError:
    print("no such sandbox")
except RuntimeAPIError as error:
    print(error.code, error.hint, error.request_id)
```

The classes match the JavaScript SDK (`no_capacity` is a `ServiceUnavailableError`;
`no_credit_running_limit` and a `quota_exceeded` on what runs concurrently are a
`RateLimitError`, and a `quota_exceeded` on what is kept a `ConflictError`): `AuthenticationError`,
`PermissionDeniedError`, `NotFoundError`, `ConflictError`,
`InvalidRequestError`, `RateLimitError`, `ServiceUnavailableError`,
`AccountBlockedError` (from 0.7.0), `ConnectionError` and `CommandError`, all
subclasses of `withruntime.RuntimeAPIError`. `RuntimeAPIError` and
`RuntimeConnectionError` name the SDK errors without hiding Python's built-in
`RuntimeError` and `ConnectionError`. The old exports remain aliases of the
same classes, so existing catches keep working. Every write carries an idempotency
key, made for you. Transport failures, and every response that says `retryable: true`,
are retried after its `Retry-After`, with the same key. So a retry never makes
two sandboxes or runs a command twice. A wait over 60 seconds is not slept on.
The error is returned immediately, with `retry_after_ms`. A response that ran
nothing (`guest_busy`, `busy`, `rate_limited`, `sandbox_starting`) is sent again
until the call's deadline. Without a deadline, it is sent again for five minutes, past `max_retries`.
Interrupted complete response bodies are retried with the same key too;
streamed output is never replayed after it reaches your code. A failed body
read or retry delay carries the original `error.idempotency_key`.

Pass your own `idempotency_key` to make a retry safe across process restarts.
For 24 hours, a create or a command sent again with the same key and the same
input returns the first one's result instead of doing it twice. The same key
with different input is refused with `idempotency_key_reused`.

```python
from uuid import uuid4

from withruntime import Runtime

job = uuid4().hex  # your job's own id: keep it for every retry of this job

with Runtime() as runtime:
    with runtime.sandboxes.create(idempotency_key=f"job-{job}-sandbox") as sbx:
        sbx.exec(["python3", "-c", "print(42)"], idempotency_key=f"job-{job}-step-1")
```

**A create, wake or restart waits for room.** When all four slots without credit are taken (`no_credit_running_limit`), the
account is at its limit (`quota_exceeded`), or the region is full
(`no_capacity`), `sandboxes.create` waits. It sends the same request again, for
up to two minutes. A burst of CI jobs past the limit queues instead of failing.
A sandbox's `wake` and `restart` wait the same way when their own server is
full (`no_capacity`). A sandbox stays on its server, so the wake is sent again
with the same idempotency key until room frees. A `fork` waits the same way
when no server has room for a copy.

- When the wait runs out, the refusal is raised as it came.
- Set `wait_for_capacity` (seconds) on the client or on one create, wake or
  restart. `0` fails immediately, as in `sbx.wake(wait_for_capacity=0)`.
- From withruntime 0.7.0, `on_capacity_wait(refusal, seconds)` on one create is
  called before each wait,
  to tell a person why nothing has happened yet.

```python
from withruntime import Runtime

# A CI job that may queue for ten minutes behind the others.
with Runtime(wait_for_capacity=600) as runtime:
    with runtime.sandboxes.create() as sbx:
        # One create that should fail at once instead.
        with runtime.sandboxes.create(wait_for_capacity=0) as now:
            print(sbx.id, now.id)
        # One that says why it is waiting (withruntime 0.7.0).
        with runtime.sandboxes.create(
                on_capacity_wait=lambda refusal, seconds: print(refusal.message, "Waiting.")) as told:
            print(told.id)
```

## Read-only keys and daily limits

An owner, admin or developer can make a read-only key and set a daily spending
limit on a key, on the
[API keys](https://withruntime.com/account/keys) page. A key reads both, and it
can change neither. `runtime.limits` needs withruntime 0.3.1 or later:

```python check
from withruntime import Runtime

with Runtime() as runtime:
    limits = runtime.limits.get()
    print(limits["access"])  # "full", "read" or "selected"
    left = limits["daily"]["remainingMicros"]
    if left is not None and int(left) < 1_000_000:
        print("less than $1 left in this 24-hour window")
```

Past the limit, a create, wake, extension or renewal fails with a
`RuntimeAPIError` whose `code` is `spending_limit_reached` (HTTP 402), and it is
not retried. A read-only key asking to change anything gets
`PermissionDeniedError`. See [security](./security).

Cap one sandbox's whole life with `max_total_cost_micros`, in millionths of a
dollar. When it has cost that much, it stops, and `stopReason` reads
`lifetime_cap`:

```python check
from withruntime import Runtime

with Runtime() as runtime:
    # At most 50 cents over this sandbox's whole life.
    sbx = runtime.sandboxes.create(max_total_cost_micros=500_000)
    sbx.stop()
```

## Secrets your sandboxes never see

Store an API key once with `runtime.secrets`, naming the hosts it may go to.
Every sandbox of the account then has an environment variable of that name
(or `env`) that holds a placeholder. The host's proxy swaps in the real value on
HTTPS requests to those hosts. The value is sealed and never returned:

```python check
import os

from withruntime import Runtime

with Runtime() as runtime:
    runtime.secrets.set("OPENAI_API_KEY", value=os.environ["OPENAI_API_KEY"],
                        hosts=["api.openai.com"])
    runtime.secrets.set("GITHUB_TOKEN", value=os.environ["GITHUB_TOKEN"],
                        hosts=["api.github.com"], header="Authorization",
                        format="token {value}",
                        rules=[{"methods": ["GET", "HEAD"], "paths": ["/repos/acme/*"]}])
    for secret in runtime.secrets.list():  # names, hosts and placeholders, never values
        print(secret["name"], secret["hosts"])
    page = runtime.secrets.list(limit=10, after="GITHUB_TOKEN")  # one page, by name
    runtime.secrets.delete("GITHUB_TOKEN")
```

With `header`, the proxy sets that header on every request to the hosts, with
`format` placing the value. With `rules`, on accounts with credit, only the requests a
rule allows by method and path carry it: a path is exact or ends in `/*`.
Replacing a secret keeps its placeholder, so
running sandboxes use the new value. See
[security](./security#secrets-sandboxes-never-see) for the limits and what is
never rewritten.

With `env="GITHUB_TOKEN"`, sandboxes see the placeholder in that variable instead of
the secret's name, so secrets scoped (`only`) to different sandboxes can
share one, such as a `GITHUB_TOKEN` for each repository; a store that would
give one sandbox two of them is refused.

## Images, volumes and snapshots

```python check
from withruntime import Runtime

runtime = Runtime()
image = runtime.images.build(name="data", recipe={"pip": ["pandas"], "apt": ["jq"]},
                             on_log=lambda line: print(line["text"]))
volume = runtime.volumes.create(size_mib=10_240, name="cache")
with runtime.sandboxes.create(image=image["id"],
                              volumes=[{"volume_id": volume["id"], "path": "/data"}]) as sbx:
    print(sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'").stdout)

# A sandbox with volumes cannot be snapshotted, so these use one without.
with runtime.sandboxes.create(image=image["id"]) as base:
    forks = base.fork(count=2)  # copies as it is now, running
    for fork in forks:
        fork.stop()
    snapshot = base.snapshot(name="with-pandas", retention_days=7)
    with runtime.sandboxes.create(snapshot=snapshot["id"]):
        pass
    runtime.snapshots.delete(snapshot["id"])
```

`images.build` waits until the image is ready; `images.create` queues it and
returns. A Dockerfile build takes `dockerfile` and `context_dir`, the folder
`docker build` would read, with its `.dockerignore`; multi-stage builds,
`COPY --from`, `ARG` and heredocs work. Each build of a `name` is its next
version and takes the tag `latest`, or the `tags` you give, and `image=` on a
create takes an id, `name`, `name:tag` or `name@version`. `start` sets what a
sandbox from the image runs and when its create returns
(`{"command": ..., "ready_port": 8000}`). `images.versions(name)`,
`images.resolve(ref)`, `images.tag(ref, tag)`, `images.untag(ref, tag)`,
`images.follow_logs(id, on_log)` and `images.registries.set(registry,
username=..., password=...)` for private images do the rest; see
[custom images](./images). `sbx.switch_image("data:v2")` moves
a running sandbox to a new build, keeping its id, `/workspace` (its home),
volumes, environment and previews; its processes restart and the rest of its
old disk is lost ([move a sandbox to a new version](./images#move-a-sandbox-to-a-new-version)).
A volume lives on one server and is backed up off it
daily; `volumes.backup(id)` and `volumes.restore(backup_id)` make and restore a
backup ([storage and backups](./storage)). `sbx.mounts.add(provider="s3", bucket=..., path=..., secret=...)`,
`list()` and `remove(path)` mount your own bucket without the sandbox holding
its key ([mount your own bucket](./storage#mount-your-own-bucket)). Images, volumes and kept snapshots are charged as storage
([pricing](./pricing#snapshots-images-and-volumes)).

Forks and snapshots:

- Copies run on what the account's new sandboxes run on, as a create does;
  `funding` is accepted and ignored.
- Copies keep the source's size and CPU (reserved CPU, or a raised floor) and
  are billed as a create with those would be. A copy without credit must fit the limits without credit.
- The snapshot a fork takes is deleted when the fork ends, whether every copy
  started or not, and is not billed, unless `keep_snapshot=True`.
- If a copy fails, the error's `details["startedSandboxIds"]` names the copies
  that did start; they keep running until stopped. A retry with the same
  idempotency key returns the same error.
- If a fork stops partway and left its source paused, the source stays paused,
  and an account notice says so and how to wake it.
- Copies start on the source's server while it has room, and on another server
  once the snapshot is copied there when it is full. A kept snapshot is stored on its source server and
  copied off it, encrypted, after its final compressed form is ready. It survives loss of the server once
  `backedUp` is `True`, meaning that copy has been checked
  ([storage and backups](./storage)).
- Snapshots default to `mode="memory"`, keeping files, memory and running
  processes. `base.snapshot(mode="disk")` keeps only the root filesystem;
  each copy boots fresh without the saved processes, at the `vcpu`,
  `memory_mib` and `disk_mib` you pass (a disk at least the saved size). A
  copy of a memory snapshot is always the snapshot's size. Both modes pause a
  running source until capture finishes, then wake it; an already paused
  source stays paused. A disk snapshot's pause first waits for the sandbox
  to write out what it holds in memory: a few seconds at most while it writes.

Where deferred compression has been qualified and enabled, a memory
snapshot can be `"ready"` with `compressionPending` set to `True`
and start copies on the same server before background compression finishes.
Temporary raw files are not charged; snapshot billing uses the final verified
compressed allocation. The off-server copy waits for that final form, so
`backedUp` is false while compression is pending. See
[snapshot storage](./storage#snapshots-survive-their-server).

If a snapshot was captured but waking its source fails, the error keeps the
original failure and `details["snapshotId"]`, `details["sourceSandboxId"]` and
`details["sourceWakeError"]`. Read that saved snapshot and wake the source
explicitly before taking another capture; a failed recovery does not erase the
snapshot id.

See [JavaScript](./javascript#custom-images) for what each does; the Python
methods are the same in snake_case.

## Code interpreter and network rules

The interpreter runs Python, JavaScript, TypeScript, R, Java, Bash and Go.
Each language keeps its state between cells, except Go, which keeps its
functions, types and imports and runs each cell as a program. R plots and
matplotlib charts come back as PNG images; pandas and R data frames as tables.
R, Java and Go are installed in the sandbox the first time you use them
(30 to 90 seconds, once), or bake them into an image with `apt`.
A package `pip install` run from a cell or from `sbx.exec` makes its imports
available in a context that is already running, even in the cell that installed it.

```python check
from withruntime import Runtime

runtime = Runtime()
with runtime.sandboxes.create() as sbx:
    sbx.interpreter.run("import math\nx = math.pi")
    cell = sbx.interpreter.run("round(x * 2, 3)")
    print(cell["results"][0]["data"]["text/plain"])
    frame = sbx.interpreter.run("df <- data.frame(a = 1:3); df", language="r")
    print(frame["results"][0]["data"]["application/vnd.runtime.table+json"])

    sbx.network.set(internet=True, allow=["pypi.org", "*.pythonhosted.org"])
    print(sbx.network.get())
```

Feedback and support are on the client too: `runtime.feedback.submit(...)` and
`runtime.support.message(...)`; see [feedback and support](./feedback-and-support).

## Previews and the desktop

```python check
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.spawn("python3 -m http.server 3000")
    preview = sbx.previews.create(3000)  # private: the link carries its token
    print(preview["urlWithToken"])

    sbx.desktop.start(width=1280, height=800)  # ready in about a second
    sbx.desktop.open("https://example.com")
    sbx.desktop.click(640, 400)
    with open("screen.png", "wb") as file:
        file.write(sbx.desktop.screenshot())

    recording = sbx.desktop.recordings.start(fps=10, max_mib=256)
    sbx.desktop.type("hello")
    sbx.desktop.recordings.stop(recording["id"])
    with open("demo.mp4", "wb") as file:
        file.write(sbx.desktop.recordings.download(recording["id"]))
```

A preview is private by default: open `urlWithToken`, or send `token` as the
`x-runtime-preview-token` header. `visibility="public"` gives an address anyone
can open, on a paid sandbox only; a sandbox without credit's previews stay private.
Within 60 seconds after the sandbox is created or wakes, a request to a port
that is not listening yet waits up to 10 seconds for the server to start; after
that it returns 502 with `x-runtime-preview-error: port_closed`.

`embed_origins=["https://app.example.com"]` on `sbx.previews.create` names the sites that
may show the preview in an iframe (up to 16); any other site's
iframe is refused. `sbx.previews.rotate(3000)` refuses every token issued for
the port so far and returns a new one; `sbx.previews.delete(3000)` stops sharing it. A preview's
address is under `runtimehost.com`, the domain for everything sandboxes serve,
kept apart from Runtime's own site.
See [JavaScript](./javascript#share-a-port) for what each does.

Native `previews.create` and `previews.get` accept `expires_at` as a
timezone-qualified ISO timestamp, a minute to a week ahead. It rounds down
to a whole second; with `ttl_seconds`, the earlier deadline wins. A session's
expiry also limits its preview reads. Use the returned `tokenExpiresAt` as
the actual deadline. The matching server feature is required: an older server
refuses the absolute field rather than falling back to a relative lifetime.

## A browser over CDP

`sbx.browser.start()` runs Chromium in the sandbox and returns `cdpUrl`, the
private address Playwright's `connect_over_cdp`, browser-use and Stagehand
connect to. Chromium comes from the host, so a start in a new sandbox takes
about 1 to 2 seconds and installs nothing:

```python check
from withruntime import Sandbox

with Sandbox.create(vcpu=1, memory_mib=2048) as sbx:
    cdp_url = sbx.browser.start()["cdpUrl"]
    # playwright: browser = p.chromium.connect_over_cdp(cdp_url)
```

For a page without a browser start, keep spare browsers paused. A paused
sandbox is charged only for its storage, and wakes with Chromium running. Run `spare.pause()` after `browser.start()`. Then, for each
page, run `spare.wake()`, open a new browser context and the page, and run
`spare.pause()` again.
Open each page in its own context so nothing passes between pages. Heavy apps
need 2 GiB; 1 GiB suits light pages and scraping at half the memory charge.
[JavaScript](./javascript#spare-browsers-paused) has the same in TypeScript.

## A sandbox from a browser

A session lets your own frontend reach one sandbox directly, without a key in
the browser. Make it on your server and hand the page the token and the
sandbox id; the page uses them with the JavaScript SDK
(`Sandbox.fromSession({ token, sandboxId })`) or the HTTP API:

```python no-run
session = sbx.sessions.create(origins=["https://app.example.com"], ttl_seconds=900)
token, sandbox_id = session["token"], session["sandboxId"]
```

A session runs commands, uses files and reaches previews of that one sandbox,
and nothing else. It lasts 1 hour unless asked and
24 hours at most; `sbx.sessions.revoke(session_id)` ends it immediately, and
revoking the key that made it ends all of them. Python code can use one too:
`Sandbox.from_session(token, sandbox_id)`. [A sandbox from a
browser](./javascript#a-sandbox-from-a-browser) has the rest.

## MCP servers in a sandbox

Runtime does not run catalog MCP servers for you. To run an MCP server in a
sandbox, start it as a process and share its port with a preview. The server
must serve MCP over Streamable HTTP. Your agent then connects to the preview
URL, at the path your server serves MCP on (often `/mcp`), and sends the
preview token in the `x-runtime-preview-token` header.

```python
from withruntime import Runtime

runtime = Runtime()
sbx = runtime.sandboxes.create()
sbx.spawn("python3 server.py --port 8000", cwd="/workspace/my-mcp")
preview = sbx.previews.create(8000)
print(preview["url"], preview["token"])  # the address and the token to send
```

The server runs as the sandbox's user, behind the sandbox's network rules. It
can use [secrets the sandbox never sees](./security#secrets-sandboxes-never-see).

## Domains, TCP ports, addresses, the tunnel and your own proxy

They need a kept top-up, and a dedicated address credit; see [networking](./networking).

```python check
from withruntime import Runtime

runtime = Runtime()
sbx = runtime.sandboxes.create(name="web")
domain = runtime.domains.add("app.example.com", sandbox_id=sbx.id, port=3000)
print(domain["records"])  # the TXT and CNAME to set; then runtime.domains.verify(...)
db = runtime.ports.open(sandbox_id=sbx.id, port=5432)
print(db["connect"])  # "203.0.113.10:23456"
ip = runtime.ips.reserve()
runtime.networks.wireguard.create()
office = runtime.networks.wireguard.add_peer("office", routes=["10.0.0.0/16"])
print(office["config"])  # a wg-quick file
runtime.networks.upstream_proxy.set("http://proxy.example.com:3128", secret="PROXY_AUTH")
```

`runtime.networks.upstream_proxy`, from `withruntime` 0.12.0
(`runtime.network.upstream_proxy` from 0.7.0),
sends every sandbox's outbound connections through your own proxy; `get()` and
`remove()` read and undo it. See
[your own proxy](./security#your-own-proxy).

## Metrics and webhooks

```python check
from withruntime import Runtime, Sandbox, verify_webhook

sbx = Sandbox.create()
latest = sbx.metrics(range="15m")["latest"]  # CPU and memory, measured

runtime = Runtime()
hook = runtime.webhooks.create(url="https://example.com/hooks/runtime")
# In the endpoint: verify_webhook(raw_body, headers["runtime-signature"], hook["secret"])
print(latest, verify_webhook.__name__)
```

`runtime.events.list()` reads lifecycle events and `runtime.otel.create()`
pushes events and metrics to an OpenTelemetry endpoint. See
[metrics and webhooks](./observability).

## Account API calls

```python check
from withruntime import Runtime

with Runtime() as runtime:
    counts = runtime.usage_requests("7d")
    print(counts["calls"], counts["errorPercent"])
    for row in counts["operations"]:
        print(row["operation"], row["serverErrors"])
```

`usage_requests()` defaults to `"24h"`; `"7d"`, `"30d"` and `"90d"` select
longer windows. Counts are exact decimal strings, and `errorPercent` is `None`
when no calls were counted. `AsyncRuntime` has the same method, awaited. A key
needs the `usage` scope, read-only access or all-products access. See
[account API calls](./observability#account-api-calls).

## Export settled usage

```python check
from withruntime import Runtime

with Runtime() as runtime:
    cursor = None
    while True:
        page = runtime.usage_export(
            "2026-09-01T00:00:00Z", "2026-10-01T00:00:00Z", cursor=cursor
        )
        print(page["csv"], end="")
        cursor = page["nextCursor"]
        if cursor is None:
            break
    print(page["finalThrough"])
```

The range includes settlements at `since` and excludes those at `until`;
pending holds are excluded. Concatenate each page's CSV unchanged; the header
is on the first only. `finalThrough` is the time before which no more charges
will settle (the range is final once it reaches `until`), and a row's `final`
is `True` once its resource is deleted and can be charged nothing more.
`AsyncRuntime` has the same method, awaited. See
[export settled usage](./api#export-settled-usage).

## Identity tokens

Inside a sandbox, `Sandbox.identity_token("sts.amazonaws.com")` returns a
short-lived OIDC token naming the sandbox, to trade for AWS or Google Cloud
credentials without a stored key. It needs no API key. See
[identity tokens](./identity-tokens).

## Single sign-on

An owner sets up single sign-on (SAML or OIDC) and directory sync (SCIM) on
the [Single sign-on](https://withruntime.com/account/single-sign-on) page;
both are free. A key made by an owner or admin reads it with
`runtime.sso.get()`: each identity provider, its domain and whether it is
verified, whether single sign-on is required, and the directory sync's users
and group roles. See [single sign-on](./single-sign-on).

## Coming from E2B, Daytona, Vercel Sandbox or Blaxel

Their supported Python sandbox calls keep the same call shapes on Runtime
after changing the import,
in `withruntime` 0.4.0 and later for E2B and 0.5.0 and later for Daytona and
Vercel Sandbox, and 0.8.1 and later for Blaxel:

```python no-run
from withruntime.e2b import Sandbox  # was: from e2b import Sandbox
from withruntime.daytona import Daytona  # was: from daytona import Daytona
from withruntime.vercel import sandbox  # was: from vercel import sandbox
from withruntime.blaxel import SandboxInstance  # was: from blaxel.core import SandboxInstance
from withruntime import modal  # was: import modal (0.23.0 and later)
```

The adapters translate supported calls to Runtime's native sandbox, with the
provider defaults described in each mapping. Unsupported options are refused
before allocation, and the mapping names the supported alternatives. To move to Runtime's own calls, see [migration](./migrate).

## Configuration

```python
from withruntime import Runtime

with Runtime(max_retries=4, timeout=120) as runtime:
    print(runtime.me()["orgId"])
```

`RUNTIME_API_URL` points the client at another API origin. Code inside a
Runtime sandbox calls Runtime's API at `http://runtime.internal`
([Runtime's API from inside a sandbox](./sandbox-environment#runtime-s-api-from-inside-a-sandbox)).
A client holds at most 48 connections at a time (`max_connections`), calls and
streams such as a command's output together, and keeps 8 of them for calls;
past that, calls and streams wait their turn instead of failing. One address
may hold 64 connections to the API until it has used a valid key, and more
after ([limits](./api#limits)).

Before 0.3.0 the package was `withruntime-cloud`, imported as `runtime_cloud`.
That name stopped at 0.5.1 and gets no new releases: install `withruntime` and
`import withruntime` for everything since.


---

<!-- https://withruntime.com/docs/referrals -->

# Referrals

Share your link. When someone signs up with it:

- **They get** every credit they add in their first 30 days matched, up to
  $1,000 in total, as everyone does with the [welcome match](./pricing#welcome-match).
- **You get** the same: as much as they are matched, payment by payment, up to
  $1,000 for each person you bring.
- **Then, for 12 months,** you earn 10% of what they spend from credit they
  paid for, as credit.
- **Each person you bring earns its own share,** with no limit on how many.

| They add in their first 30 days |          You get | They get, on top |
| ---------------------------------------------- | ---------------: | ---------------: |
| $10                      | $25 | $25 |
| $50, then $450                                 |             $500 |             $500 |
| $2,000                                         | $1,000 | $1,000 |

Someone who then spends $500 a month from credit they paid for earns you
$50.00 a month for 12 months.

The details:

- Your link is `https://withruntime.com/r/<code>`. `https://withruntime.com/?ref=<code>` works too. Owners, admins and billing
  members find it on [Home](https://withruntime.com/account) and under
  **Refer & earn** on [Usage & billing](https://withruntime.com/account/billing).
  The **Refer & earn** item in the account menu also opens it. You can also get
  it with the API, an SDK, the CLI or MCP (below). The code belongs to your
  organization and never changes.
- Showing someone what you built? A preview link is a good way. The response to
  creating one says so. Runtime adds nothing to the pages a preview serves: no
  badge, no banner.
- The link has to be followed before they sign up. It is remembered
  for 30 days in a cookie that holds only the code. It carries through
  Google and email sign-in.
- Each payment they make in their first 30 days is matched on both
  sides, until each side has $1,000 from that person. The first one of
  $10 or more gives each side at least $25. Payments after
  day 30 are not matched. Free usage never counts. Each match is paid when Stripe confirms the card or Link account
  behind the payment, usually within seconds of it. The payment's own credit
  never waits. When that payment, or one of yours, went through a wallet that
  tells us neither, the match is paid once someone at Runtime has checked it.
- Your share is worked out from what they spend from credit they paid
  for. It is never worked out from matched, referral, startup or any other granted credit, or
  the month's free usage. It is added as credit on the 1st of each month
  (UTC) for the month before, for 12 months from their first matched
  payment. While they have a payment in dispute, no share is added for them.
  Once the dispute is won, the share catches up. Once it is lost, the
  next month's share is not added (that use was paid with the disputed
  money), and the months after it are. While none of their matched payments
  stands (all refunded or disputed), no share is added for them.
- The page your link opens says "You're invited", with the offer and the way
  to sign up. It never names who invited them: your company's name is not on
  it.
- A referral and the [welcome match](./pricing#welcome-match) never both pay.
  Someone who signed up with your link gets the referral's match. It is the
  same $1,000 over the same 30 days, and never smaller.
- You can earn up to **$50,000 of referral credit per calendar year** (UTC),
  matches and shares together. Past that, the person you referred still gets
  their credit. Yours is recorded as over the cap.
- Referring yourself does not count. That includes your own organization, another
  address of yours, and an address on the same company email domain. A shared
  provider such as gmail.com is not one company. It also includes an organization that shares
  a member with yours, now or before, directly or through a third organization.
  It includes someone who has paid with a card or Link account your
  organization has paid with, or the other way round. This is checked again at
  every payment and every month's share, so it holds whatever changes after
  sign-up. A code that does not count never stops anyone signing up.
- If a matched payment is partly refunded, its match is worked out again on
  what stands, and both sides give back the difference. If it is disputed, or
  less than $10 of the first one stands, both sides' match of that payment
  is taken back. Their other payments keep theirs. Either way, only
  what is still unspent is taken, so a refund is smaller by any referral credit
  already spent on either side. Credit you already spent stays counted against
  your $1,000 from that person and your yearly cap. A payment
  refunded and made again is not matched for you twice. While such a refund is being paid out, the
  credit it will take back is held on both sides and cannot be spent.
- A lost dispute also takes back the share paid since that payment, at most
  10% of the disputed amount. A refund takes back no share, because the share was paid
  on credit they had already spent.
- Referral credit is spent like any other credit. It cannot be exchanged for
  cash or refunded.

## Read your link and what it earned

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

const runtime = new Runtime();
const r = await runtime.referrals.get();
console.log(r.link, r.signedUp, r.paid, r.earnedMicros);
```

```python check
from withruntime import Runtime

r = Runtime().referrals.get()
print(r["link"], r["capRemainingMicros"])
```

```sh no-run
npx withruntime referrals
```

In Go it is `client.Referrals.Get(ctx)`, in Java `runtime.referrals().get()`
and in Ruby `runtime.referrals.get`. Over HTTP it is `GET /v1/referrals`. Over MCP, it is the
`runtime_account` tool's `referrals` action. Each returns the same
fields:

| Field                             | Meaning                                                             |
| --------------------------------- | ------------------------------------------------------------------- |
| `code`, `link`                    | Your code and the link to share                                     |
| `signedUp`                        | People who signed up with your link                                 |
| `pending`                         | Of those, the ones that have not made a first payment yet           |
| `paid`, `capped`                  | Referrals with a payment matched, and how many the yearly cap cut   |
| `payingCompanies`                 | People you referred with a matched payment still standing           |
| `rewardMicros`, `maxRewardMicros` | The least on a first payment, and the most per person, each side    |
| `windowDays`                      | Days after sign-up in which payments are matched                    |
| `shareBasisPoints`, `shareMonths` | Your share of their paid spending (1000 is 10%), and for how long   |
| `reversed`                        | Referrals whose every matched payment was refunded or disputed      |
| `earnedMicros`                    | Referral credit you kept, all time: matches and share               |
| `shareEarnedMicros`               | Of that, the share                                                  |
| `earnedThisYearMicros`            | What counts against this year's cap                                 |
| `capRemainingMicros`              | What you can still earn this year                                   |
| `referredBy`                      | Whether your own organization joined through a link, and its credit |

Money is integer microdollars in strings: `"25000000"` is $25.


---

<!-- https://withruntime.com/docs/reservations -->

# Book room for a burst

Batch work comes in bursts. A run of evals, RL rollouts or browser sessions
may need hundreds of sandboxes at nine tonight, not a steady few. Book the room
ahead, and you are told immediately whether you have it. Inside the window, your
creates are never refused `no_capacity` or `quota_exceeded`, up to what you
booked. You create sandboxes as usual. There is nothing to name.

- **Up to 10,000 sandboxes** of one size, in one region.
- **A window of up to 24 hours**, starting now or within 14 days.
- **Confirmed or declined immediately.** A decline says why, the most sandboxes
  that window can take, and the nearest window that takes them all.
- **Sandboxes you run bill as usual**, per second. Booked room that none of them
  uses costs a quarter of the memory rate, $0.001875 per GiB-hour,
  with no CPU charge. Cancel at least an hour before the start, and it costs
  nothing. See [What it costs](#what-it-costs).

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

const runtime = new Runtime();
const booking = await runtime.reservations.create({
  sandboxes: 300,
  vcpu: 1,
  memoryMiB: 2048,
  startsAt: "2026-10-18T03:00:00Z",
  endsAt: "2026-10-18T05:00:00Z",
});
if (booking.status === "declined") {
  console.log(booking.message, booking.largestSandboxes, booking.nearestWindow);
}
```

```python check
from withruntime import Runtime

runtime = Runtime()
booking = runtime.reservations.create(
    sandboxes=300, vcpu=1, memory_mib=2048,
    starts_at="2026-10-18T03:00:00Z", ends_at="2026-10-18T05:00:00Z",
)
```

```bash no-run
npx withruntime reservations book --sandboxes 300 --vcpu 1 --memory 2048 --from 21:00 --to 23:00
```

`--from` and `--to` take a time in your own time zone (today, or tomorrow
once it has passed), an ISO time, or `now`. The API is
`POST /v1/reservations`. MCP's tool is `runtime_reservations`.

## Standing room for a pool

A pool keeps sandboxes ready and replaces each one after use. Examples are a warm pool of
CI machines, or a fleet of agents forked from one snapshot. Its replacements are
creates like any other, so on a busy server, one can be refused. Standing room
is held from now until you cancel it. A replacement inside it is never
refused for room or limits.

- **Name the snapshots** your pool forks from. The room is held on the
  servers holding them, where their forks start, at their size.
- **`forKey`** keeps it for the sandboxes of the key that booked it. The
  rest of your account's work never takes the pool's room.
- **Keep a few more than the pool runs.** A deleted sandbox gives its room
  back once its server has stopped it, a moment later. The spare room lets
  the replacement start immediately.
- **`inUse`** says how many of its sandboxes run now, read live.

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

const runtime = new Runtime();
const pool = await runtime.reservations.keep({
  sandboxes: 40,
  snapshots: ["3f6a0d2e-9b1c-4f7a-8e5d-2c4b6a8d0e1f"],
  forKey: true,
});
console.log(pool.status, pool.inUse, pool.unusedPerHourMicros);
// A new snapshot: the room moves to its servers when it all fits there.
await runtime.reservations.update(pool.id, { snapshots: ["7b2e4c6a-1d3f-4a5b-9c8d-0e2f4a6b8c1d"] });
```

```python check
from withruntime import Runtime

runtime = Runtime()
pool = runtime.reservations.keep(sandboxes=40, snapshots=["3f6a0d2e-9b1c-4f7a-8e5d-2c4b6a8d0e1f"], for_key=True)
```

```bash no-run
npx withruntime reservations keep --sandboxes 40 --snapshot 3f6a0d2e-9b1c-4f7a-8e5d-2c4b6a8d0e1f --for-key
```

The API is `POST /v1/reservations` with `standing: true` and no `startsAt` or
`endsAt`. `POST /v1/reservations/{id}:update` changes how many sandboxes it holds, or
its snapshots. The room moves, or grows, only when all of it fits now.
Otherwise, the response is `503 no_capacity` with what fits, and nothing
changes. Snapshots of one standing booking are all one size.

Room that none of its sandboxes uses costs what a booking's does: a quarter of the
memory rate, **$0.001875 per GiB-hour**. It is charged every hour it is
held. `unusedPerHourMicros` is the most that comes to in an hour. Cancel it
and the charge stops immediately. It is held while it is paid for. Once your
balance can't cover a day of it unused, or your account is held back, it is
let go, and the room goes back to everyone. Sandboxes you run keep running.
Standing room is decided as a booking is,
against what is free on its servers now and the margin of every hour of the
day.

## What a booking holds

The size you book is the size you will create: `vcpu`, `memoryMiB` and
`diskMiB` of each sandbox. By default, that is 2 vCPU, 4096 MiB and
4096 MiB, a create's defaults. Room is held for that many sandboxes of that
size on the region's servers.

In the window:

- Your account's limits on sandboxes running at the same time, their vCPUs, memory and disk
  rise by what you booked. The [Limits page](https://withruntime.com/account/limits)
  and `GET /v1/limits` show the raised numbers.
- The room is kept from every other account, and your creates go there
  first. Every sandbox you run in the region counts toward it.
- Past the window's half, room you are not using goes back to everyone in
  quarters. The sandboxes you are running are always kept.

At the end, nothing is stopped. Sandboxes still running keep running, and new
creates meet your usual limits again. Cancel a booking you no longer need
(`runtime.reservations.cancel(id)`, `DELETE /v1/reservations/{id}`). Its room
goes back immediately, and what runs keeps running.

## What it costs

Sandboxes you run in the window bill as they always do, per second, at the
usual rates. Room you booked that none of your sandboxes uses costs a quarter
of the memory rate: **$0.001875 per GiB-hour** of the booked
sandboxes' memory, with no CPU charge.

- It is measured each minute the window is live: the sandboxes the booking
  holds room for, less the sandboxes you run in the region.
- Past the window's half, unused room goes back to everyone in quarters. Room
  that has gone back costs nothing.
- Cancel at least an hour before the start, and it costs nothing. Cancel later,
  and the unused room is charged until an hour after the start, or until you
  cancel if that is later.
- It is charged from your balance every hour of the window and when it ends.

The confirmation says the rate (`unusedRateMicros`, per GiB-hour) and the
most the booking costs if none of its sandboxes run (`unusedMaxMicros`).
`unusedChargedMicros` shows what it has cost so far. For 300 sandboxes of
2 GiB booked for 2 hours:

| What runs                        | Booked room charged |
| -------------------------------- | ------------------- |
| All 300, the whole window        | Nothing             |
| 150 of them, the whole window    | $0.77               |
| None                             | $1.83               |
| Nothing; cancelled 2 hours ahead | Nothing             |

If none run, it costs at most $2.25: every booked sandbox's
memory unused the whole window (300 × 2 GiB × 2 hours × $0.001875).
Room going back past the half brings it to $1.83.

## When a booking is declined

A declined booking is a normal result, not an error. `status` is `declined`, and
`reason` says why.

| `reason` | What it means                                                                                                                               | What to do                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `room`   | That window has no more room without taking what other customers need                                                                       | Book `largestSandboxes`, or the `nearestWindow` it names                                     |
| `share`  | One account books at most a quarter of the region's spare room at the same time                                                             | Book `largestSandboxes`, or split the burst over windows                                     |
| `usage`  | Three of your bookings in the last 30 days used under a fifth of what they held, so bookings are smaller for now                            | Book what you will run                                                                       |
| `credit` | The balance doesn't cover `estimateMicros` beside your other bookings' (with auto top-up on, what you paid more than a week ago counts too) | Book `largestSandboxes`, or add credit in [Billing](https://withruntime.com/account/billing) |

An account whose sandbox limits Runtime set lower, a pilot, or an account
held back by a dispute or an abuse report can't book. It gets `403`. Write to
support@withruntime.com. An account can ask at most 20 times in ten minutes.
Past that, it gets `429`.

`estimateMicros` is the most the booking can cost: every sandbox running the
whole window. Any mix of running and unused costs less. It is not charged.
Your balance covers it, beside the estimates of your other bookings not yet
ended. With auto top-up on, what you have paid and kept for more than a week
counts toward it too, so a new card alone doesn't raise your limits.

## How room is decided

Each region keeps a margin for everyone else. The margin is the most its customers ran
outside bookings in the same hours over the last two weeks, plus a fifth. A
booking never takes the margin, and never stops, moves or pauses anyone's
sandbox. That is why a booking is a promise we can keep, and why a busy hour
may decline one that a quiet hour confirms.

## Reading bookings

`runtime.reservations.list()` (`GET /v1/reservations`) lists your bookings and
declines, newest first. Each has `phase` (`upcoming`, `active` or `ended`),
`inUse` (sandboxes you run in the region now, up to the booked number) and
`peakInUse`. The console's [Limits page](https://withruntime.com/account/limits)
shows your active and upcoming bookings.


---

<!-- https://withruntime.com/docs/ruby -->

# Ruby SDK

One Ruby client for every Runtime Cloud product.

The `withruntime` gem needs Ruby 3.2 or later and uses only the standard
library. It is safe to share between threads and keeps its connections open.

```bash no-run
gem install withruntime
```

**The client finds its key by itself.** It uses `RUNTIME_API_KEY` when that is
set, and otherwise the connection this machine saved (any `npx withruntime`
command connects it, with one browser approval).

On a server, put a key from https://withruntime.com/account/keys in
`RUNTIME_API_KEY`, stored in your secret manager. Never put it in source code, a
URL or a command-line argument. With no key anywhere, `WithRuntime::Client.new`
raises `WithRuntime::AuthenticationError` whose `code` is `missing_api_key`
and whose `hint` says how to get one.

## Hello, sandbox

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
begin
  sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n")
  puts sbx.exec("python3 /workspace/invoice.py", check: true).stdout
ensure
  sbx.stop
end
```

`create` returns once the sandbox is running. With no arguments, you get the free
usage while it lasts, the default region, and 2 vCPU, 4 GiB of memory and a
4 GiB disk. The sandbox runs while it works and pauses itself when idle. It has
no time limit unless you set one with `timeout_seconds:` (60 to 86,400). The
free usage is spent first, then prepaid credit. `funding:` is accepted and
ignored. Every field is optional, in snake_case:

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create(
  name: "tests-42",
  labels: { team: "search", job: "42" },
  vcpu: 2,
  memory_mib: 4096,
  disk_mib: 8192,
  timeout_seconds: 900,
  on_lease_end: "stop",
  network: { internet: true, allow: ["rubygems.org", "*.githubusercontent.com"] }
)
puts sbx.id, sbx.info.funding, sbx.info.ends_at
sbx.stop
```

A response can be read by snake_case name (`sbx.info.memory_mib`) or by the
API's own key (`sbx.info["memoryMiB"]`). A field newer than the SDK is always
there. A string key in a request (`"newField" => 1`) is sent as written.

## Run commands

A string runs under `bash -c`. An array runs the program directly, with no
shell. Use an array for untrusted arguments.

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
sbx.exec("mkdir -p app && echo 'print(1 + 1)' > app/main.py")
run = sbx.exec(["python3", "main.py"], cwd: "/workspace/app", env: { API_TOKEN: ENV.fetch("API_TOKEN", "") }, timeout: 120)
warn run.stderr unless run.exit_code.zero?
print run.stdout

sbx.exec("for i in 1 2 3; do echo line $i; sleep 1; done", on_stdout: ->(text) { print text })
sbx.exec_stream("node --version") do |event|
  print event["data"] if event["type"] == "stdout"
end
sbx.stop
```

- `env:` passes secrets to a command. Runtime never echoes them back. Never put
  a secret in the command line.
- `stdin:` gives the command input, then closes it.
- `user: "root"` runs the command as root, with no `sudo` in front, keeping its
  `env:` and `PATH`; `HOME` is `/root`. `spawn` and `terminal` take it too.
- The default timeout is 60 seconds; the maximum is a day. A timeout is a
  result (`timed_out` is true, with the output so far), not an exception.
- `check: true` raises `WithRuntime::CommandError`, with the exit code and
  output, on a non-zero exit or a timeout.
- With `on_stdout:`, `on_stderr:`, or a timeout over a minute, the command
  streams. The result keeps everything it printed. When the server ends a long
  stream, the stream resumes by itself. No output is dropped.

## Background processes

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
server = sbx.spawn("python3 -m http.server 8000", cwd: "/workspace")
repl = sbx.spawn(["python3", "-i", "-q"], pipe_stdin: true)
repl.write("print(21 * 2)\n", eof: true)
print repl.wait.stdout
sbx.processes.each { |process| puts "#{process.id} #{process.state} #{process.command}" }
server.kill("SIGTERM")
sbx.stop
```

A process outlives your connection. Get it back with `sbx.process(id)`.
`write` tracks input offsets, so a retried write is never typed twice.

## Files

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
sbx.files.write("/workspace/data/input.csv", "a,b\n1,2\n")
print sbx.files.read_text("/workspace/data/input.csv")
sbx.files.list("/workspace", depth: 2).each { |entry| puts "#{entry.type} #{entry.size} #{entry.path}" }
sbx.files.mkdir("/workspace/out")
sbx.files.rename("/workspace/data/input.csv", "/workspace/out/input.csv")
sbx.files.upload("./lib", "/workspace/project/lib")
sbx.files.download("/workspace/out", "./out")
sbx.stop
```

`write` creates parent directories and replaces the file atomically. A file over
1 MiB goes in parallel chunks, each checked by SHA-256. `stat` returns `nil` for
a path that does not exist. `upload` and `download` move a whole directory as
one gzipped archive. Pass `mode: 0o755` to write an executable. Pass `mode: 0`
for no permission bits. `chmod(path, mode)` changes an existing file. A
caller-supplied `idempotency_key:` also makes a complete large-file write safe
to repeat. Each upload phase keeps its own stable key. On an older guest,
setting a mode also needs the exec grant for its chmod fallback.

### Links

A link is a secret URL that anyone can open, with no API key. A GET downloads
the file. Range requests work, so videos play and downloads resume. A PUT with
the raw body uploads the file atomically. A link expires in 1 hour by default,
and at most 7 days. `revoke_links` ends every link made for the sandbox.
Revoking the key that made a link also ends its links.

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
sbx.files.write("/workspace/report.csv", "a,b\n1,2\n")
down = sbx.files.download_url("/workspace/report.csv", filename: "report.csv", expires_in_seconds: 600)
up = sbx.files.upload_url("/workspace/incoming.bin", max_bytes: 10 * 1024 * 1024)
puts down["url"], down["expiresAt"], up["url"]
sbx.files.revoke_links
sbx.stop
```

## Pause, wake, fork and snapshot

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
sbx.pause # memory and files are kept; compute billing stops
again = runtime.sandboxes.get(sbx.id)
again.wake(timeout_seconds: 1200)
again.extend_lease(600)

copies = again.fork(count: 2)
copies.each(&:stop)
snapshot = again.snapshot(name: "ready", retention_days: 7)
runtime.sandboxes.create(snapshot: snapshot.id).stop
runtime.snapshots.delete(snapshot.id)
again.stop
```

A fork copies a sandbox as it is now, with its files, memory and running
processes. It runs on its server while that server has room, and on another
server when it is full. See [JavaScript](./javascript) for what forks and
snapshots keep and how they are billed. If a copy fails, the error's
`details["startedSandboxIds"]` names the copies that did start. Ruby's own
`extend` is taken, so a time limit moves on with `extend_lease(seconds)`. A
sandbox with no time limit has nothing to move. `sbx.keep_alive` moves the time
limit on from your process until `stop`. `runtime.sandboxes.get_or_create(name, **fields)`
returns the sandbox with that name, woken or restarted, or creates it.

## Share a port

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
sbx.spawn("python3 -m http.server 3000")
preview = sbx.previews.create(3000)
puts preview.url, preview.token # send the token as x-runtime-preview-token
sbx.stop
```

A preview is private by default. `visibility: "public"` shares it with anyone
who has the address. It works on a paid sandbox only. A sandbox without credit
keeps its previews private. Addresses are under `runtimehost.com`.

## Images, volumes, network rules and secrets

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
image = runtime.images.build(name: "data", recipe: { pip: ["pandas"], apt: ["jq"] }) { |line| puts line.text }
volume = runtime.volumes.create(size_mib: 10_240, name: "cache")
sbx = runtime.sandboxes.create(image: image.id, volumes: [{ volume_id: volume.id, path: "/data" }])
print sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'").stdout
cell = sbx.interpreter.run("import math\nround(math.pi * 2, 3)")
puts cell.results.first.data["text/plain"]
sbx.network.set(internet: true, allow: ["pypi.org", "*.pythonhosted.org"])
sbx.stop

secret = runtime.secrets.set("OPENAI_API_KEY", value: "sk-...", hosts: ["api.openai.com"])
puts secret.placeholder # what sandboxes see in $OPENAI_API_KEY
```

`images.build` waits until the image is ready. It raises with code
`image_failed` when the build fails. `images.create` queues the build and
returns. A Dockerfile build takes `dockerfile:` and `context_dir:`, the folder
`docker build` would read, with its `.dockerignore`. Only the parts the server
does not have yet are uploaded. See [custom images](./images). A volume lives
on one server. Volume backups can restore its data onto another host.
`sbx.desktop` drives a Linux desktop in the sandbox.

## Domains, TCP ports and private networking

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
runtime.domains.add(hostname: "app.example.org", sandbox_id: sbx.id, port: 8080)
p runtime.domains.get("app.example.org") # DNS records to install, then verify
runtime.domains.verify("app.example.org")
port = runtime.ports.open(sandbox_id: sbx.id, port: 5432)
p port
runtime.ports.close(port.id)
runtime.domains.remove("app.example.org")
sbx.stop
```

`runtime.ips.reserve(family: 4)` reserves a dedicated address. `list` and
`release(id)` manage it. The SDK keeps returned funding fields and integer money
as the API sends them. `runtime.networks.wireguard` manages the account's
WireGuard network with `create`, `get`, `delete`, `add_peer`, `rotate_peer` and
`remove_peer`. Save a generated peer's `config` securely, even when
`config_ready` is false. Its private key is returned once. Calls that generate a
private key are not retried automatically. `runtime.sso.get` reads the
organization's SSO state.

## Backups, mounts, MCP and recordings

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
volume = runtime.volumes.create(size_mib: 1024)
backup = runtime.volumes.backup(volume.id, name: "before-import", retention_days: 7)
runtime.volumes.set_backup_policy(volume.id, daily: true, retention_days: 7)
runtime.volumes.set_backup_policy(volume.id, every_minutes: 60, keep: { hourly: 24, daily: 7 })
runtime.volumes.set_backup_policy(volume.id, no_schedule: true)
restored = runtime.volumes.restore(backup.id, name: "restored")
p runtime.volumes.backups(volume_id: volume.id).data
runtime.volumes.delete_backup(backup.id)
runtime.volumes.delete(restored.id)
runtime.volumes.delete(volume.id)
```

`sbx.mounts.add(provider: "s3", bucket: "data", path: "/data", secret: "S3_KEY")`
mounts an object store. `list` and `remove(path)` manage mounts. The named
secret stays on Runtime.

`sbx.desktop.recordings.start(fps: 10)` returns a recording. Use `get(id)`,
`list`, `stop(id)`, `download(id)` for MP4 bytes, and `delete(id)` to manage it.

## Watch files

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.create
watch = sbx.files.watch("/workspace", recursive: true)
begin
  watch.events.each { |event| puts "#{event.k}: #{event.path}" }
ensure
  watch.stop
  sbx.stop
end
```

The reader follows continuation messages and keeps `watch.cursor`. Overflow
and lost-event notices reach your block. `watch.close` cancels only the active
reader. Another thread can call it while HTTP headers, a body or a retry delay
is pending. `watch.stop` also removes the watch in the guest and prevents new
readers. A paused sandbox ends the current stream.

## Terminal and local port forwarding

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
sbx = runtime.sandboxes.get("your-sandbox-id")
terminal = sbx.terminal(cols: 100, rows: 30)
begin
  terminal.write("printf 'hello\n'\n")
  print terminal.read
  terminal.resize(cols: 120, rows: 40)
ensure
  terminal.close
end
forward = sbx.port_forward(8080)
begin
  puts "Local server: http://#{forward.host}:#{forward.port}"
ensure
  forward.close
end
```

A terminal exposes `read`, `write`, `resize`, `process_id`, `exit_code` and
`close`. `sbx.open_tunnel` shares one authenticated connection across
`connect(port)` and `ssh(public_key)` streams. Each stream supports `read`,
`write`, `close_write` and `close`. After `close_write`, the stream can still
read the response. `port_forward` binds to `127.0.0.1` and a free port by
default. Pass `host:` and `local_port:` to choose them. Closing it releases its
listener and active connections.

Read responses while you write large requests. An unread stream buffers at most
1 MiB. Overflow closes that stream with `tunnel_receive_overflow`. Other streams
stay usable. Closing a terminal or tunnel wakes blocked readers and writers.
WebSockets use the same API key and origin. They support an HTTP CONNECT proxy
and verify TLS certificates.

## Metrics, events and webhooks

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
hook = runtime.webhooks.create(url: "https://example.com/hooks/runtime")
secret = hook.secret # shown once; keep it

# In your endpoint, with the raw body and the Runtime-Signature header:
begin
  event = WithRuntime::Webhooks.verify("{}", "t=0,v1=0", secret)
  puts event.type
rescue WithRuntime::WebhookVerificationError => e
  puts "refused: #{e.message}"
end
runtime.events.list(type: "sandbox.stopped").each { |event| puts "#{event.created_at} #{event.type}" }
```

`sbx.metrics(range: "15m")` returns the sandbox's measured CPU and memory, and
`runtime.otel.create(endpoint: ...)` pushes events and metrics to an
OpenTelemetry endpoint. See [metrics and webhooks](./observability).

## Errors and retries

```ruby
require "withruntime"

runtime = WithRuntime::Client.new
begin
  runtime.sandboxes.get("00000000-0000-4000-8000-000000000000")
rescue WithRuntime::NotFoundError
  puts "no such sandbox"
rescue WithRuntime::Error => e
  puts e.code, e.hint, e.request_id
end
```

Every error is a `WithRuntime::Error` with `code`, `message`, `hint`,
`request_id`, `status` and `details`. Its subclasses are
`AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
`ConflictError`, `InvalidRequestError`, `RateLimitError`,
`ServiceUnavailableError`, `ConnectionError` and `CommandError`. They are the
same classes as in the JavaScript, Python, Go and Java SDKs. `no_capacity`
raises `ServiceUnavailableError`. `no_credit_running_limit`, and a
`quota_exceeded` on what runs at the same time, raise `RateLimitError`. A
`quota_exceeded` on what is kept raises `ConflictError`.

Every write carries an idempotency key. The client makes it for you and keeps it
across its own retries. Transport failures, and every response that says
`retryable: true`, are retried after its `Retry-After`. Retries stop at the
maximum number of retries. Each retry uses the same key, so a retry never makes
two sandboxes or runs a command twice. A wait over 60 seconds is not slept on.
The error returns immediately, with `retryAfterMs`. A response that ran nothing
(`guest_busy`, `busy`, `rate_limited`, `sandbox_starting`) is sent again until
the call's deadline.
Without a deadline, it is sent again for five minutes, past the maximum.
`retryable?` says whether trying the same call again may work.

**A create, wake or restart waits for room.** When all four slots
without credit are taken (`no_credit_running_limit`), the account is at its
limit (`quota_exceeded`), or the region is full (`no_capacity`),
`sandboxes.create` waits and sends the same request again, for up to two
minutes. Pass `wait_for_capacity:` (seconds) to the client or to one create,
wake or restart. Zero fails immediately, as in `sandbox.wake(wait_for_capacity: 0)`.
A sandbox stays on its server, so a wake or restart refused with `no_capacity`
is sent again with the same idempotency key until room frees. A fork waits the
same way when no server has room for a copy, as in `sandbox.fork(wait_for_capacity: 0)`
to fail immediately.

An owner, admin or developer can make a read-only key and set a daily spending
limit on a key at [API keys](https://withruntime.com/account/keys).
`runtime.limits.get` reads both. Past the limit, a create, wake or extension
raises with code `spending_limit_reached`, and it is not retried.

## Configuration

```ruby
require "withruntime"

runtime = WithRuntime::Client.new(
  api_key: ENV.fetch("MY_RUNTIME_KEY"),
  timeout: 120,
  max_retries: 4,
  wait_for_capacity: 600
)
puts runtime.me.org_id
p runtime.request("GET", "/v1/volumes") # any endpoint, same rules
```

- `RUNTIME_API_URL` points the client at another API origin, as `base_url:`
  does.
- Code inside a Runtime sandbox calls Runtime's API at `http://runtime.internal`
  ([Runtime's API from inside a sandbox](./sandbox-environment#runtime-s-api-from-inside-a-sandbox)).
- The client is safe to share between threads. It keeps its connections open
  and holds at most 32 calls in flight (`max_connections:`).
- It honours `HTTPS_PROXY` and `NO_PROXY`.
- Money is integer microdollars: 1,000,000 is one US dollar.
  `runtime.usage.available` is the account's balance as an exact decimal
  string.
- `runtime.usage_export(since:, until:, cursor:)` reads one page of settled
  usage over a UTC range, with its server CSV. Follow `next_cursor` until it is
  nil. `final_through` is the time before which no more charges will settle. A
  row's `final` is true once its resource is deleted and can be charged nothing
  more ([export settled usage](./api#export-settled-usage)).


---

<!-- https://withruntime.com/docs/runloop-alternative -->

# Runtime vs Runloop

Runtime runs agent code in microVMs, like Runloop's devboxes, and costs **88% less** for an agent that mostly waits on a model.

**The saving:** 1,000 one-minute runs of a 2 vCPU, 4 GiB sandbox cost **$0.64 on
Runtime and $5.33 on Runloop**. At 100,000 runs a month that is $63.89 against
$532.56, **$469 a month saved**.

If you are weighing more than two, [Runloop alternatives](/compare/runloop-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **You pay for the CPU you use.** Runloop bills a devbox's CPUs and memory for
  as long as it runs. Runtime measures the CPU your code actually uses, so time
  spent waiting on a model costs only a small floor, a twentieth of a vCPU.
- **Idle time bills only storage.** A Runtime sandbox pauses itself after 300 seconds with no activity, keeps its memory and processes, and runs its next command when a request wakes it. While paused, it pays $0.08 per GB (10⁹
  bytes) of saved state a month.
- **An uptime promise with automatic credit.** Paid accounts are promised
  99% API uptime each month; a month below it returns 10% of that
  month's charges as credit, with no claim to file ([Uptime Promise](/legal/sla)).
- **Lower rates on every meter.** $0.025 per vCPU-hour against Runloop's
  $0.108 per CPU-hour, and $0.0075 per GiB-hour of memory against $0.0252 per
  GB-hour. Even with both CPUs busy the whole time, the example job costs $1.33
  on Runtime and $5.33 on Runloop.
- **Pause keeps memory, on every account.** A paused Runtime sandbox wakes
  with its processes still running, kept while you have credit. A suspended Runloop
  devbox keeps only its disk, its processes must be restarted, and suspend and
  resume come with Runloop's Pro plan.
- **Forks of a running sandbox.** Copy a sandbox with its memory and running
  processes, and try several things from exactly that point.
- **No plan fee.** Runloop's Pro plan is $250 a month plus usage. Runtime is
  prepaid credit from $10, with 100 free hours of a 1 GB machine in the first 30 days.
- **Teams at no extra charge.** Single sign-on over SAML or OIDC (Okta,
  Microsoft Entra ID, Google Workspace), SCIM, roles and an audit log come with
  every account ([single sign-on](./single-sign-on)).
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file, and the [MCP server](./mcp) reuses the same
  connection.

**Also included:** a code interpreter, network allow and deny lists, secrets the
sandbox never sees, custom images, volumes backed up daily, private previews, a
Linux desktop, metrics, webhooks, OpenTelemetry export, S3, R2 and GCS bucket
mounts and identity tokens for AWS and Google Cloud.
Paid accounts add custom domains, TCP ports, dedicated outbound addresses and
WireGuard private networks. See [products](./products).

## At a glance

Runloop's figures come from its public pricing and documentation, checked
25 October 2026.

|                 | Runtime                                                        | Runloop                                                 |
| --------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
| Isolation       | Firecracker microVM, own kernel                                | microVM, with a container inside                        |
| CPU billing     | $0.025 per vCPU-hour of measured CPU, with a small floor | $0.108 per CPU-hour while the devbox runs |
| Memory billing  | $0.0075 per reserved GiB-hour                          | $0.0252 per GB-hour                     |
| Disk            | Included while running                                         | $0.00034236 per GB-hour                       |
| Plan fee        | None; prepaid credit from $10                        | Basic free; Pro $250 a month plus usage |
| Free start      | 100 free hours of a 1 GB machine in the first 30 days, no card             | $50 of credit, no card              |
| Suspend, resume | Pause keeps files, memory and processes                        | Suspend keeps the disk; processes restart               |

## Cost for the same job

Take 1,000 runs of a 2 vCPU, 4 GiB sandbox. Each run lasts 60 seconds and
keeps the CPU busy for 20 CPU-seconds: an agent that spends most of its time
waiting for a model. On Runloop that is the `MEDIUM` devbox: 2 CPUs, 4 GB and
8 GB of disk.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025           = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075      = $0.50
         Total                                             $0.64

Runloop  CPU    1,000 × 60 s / 3,600 × 2 × $0.108       = $3.60
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0252      = $1.68
         Disk   1,000 × 60 s / 3,600 × 8 × $0.00034236 = $0.05
         Total                                             $5.33
```

- **Saving:** 88%, or $4.69 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $532.56 on Runloop.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on Runtime
  against $5.33 on Runloop.

Plan fees, storage while suspended, network, taxes and free credit are left out
of both. On Runtime, inbound traffic is free, and each account's first 100 GiB
out a month is free, then $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for Runtime's
terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Runloop calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  await box.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  console.log((await box.exec("python3 /workspace/invoice.py", { check: true })).stdout);
} finally {
  await box.stop();
}
```

## When Runloop may fit better

- **Evaluation.** Runloop evaluates models against your own workload and
  generates RL rollouts checked by running them.
- **Your own cloud.** Runloop deploys into your cloud account.

## Sources

Checked 23 September 2026; plan features checked 27 September 2026.

- [Runloop pricing](https://www.runloop.ai/pricing)
- [Devbox sizes](https://docs.runloop.ai/docs/devboxes/configuration/sizes)
- [Devbox lifecycle](https://docs.runloop.ai/docs/devboxes/lifecycle)
- [Runloop](https://www.runloop.ai/)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/sandbox-environment -->

# The sandbox environment

Every sandbox is a Firecracker microVM. It has its own Linux kernel and disk. Python, Node.js, Bun, git and a compiler are ready to use.

This page covers what is in the image, who you are inside it, and what it can reach. Anything missing installs in one command. Or you can install it once, for every sandbox, in a [custom image](./javascript#custom-images).

## What is installed

The image is Ubuntu 24.04.5 LTS (noble) for amd64, on a 6.18 kernel.

| Kind              | What                                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| Python            | Python 3.12 (`python3` and `python`), `pip` and `pip3`, `venv`, and uv 0.12.17 (`uv`, `uvx`)                   |
| Python data tools | NumPy 1.26.4, pandas 2.1.4 and matplotlib 3.6.3, included in the current default image                         |
| JavaScript        | Node.js 24.21.0 (`node`, `npm`, `npx`), with `pnpm` and `yarn` through Corepack; Bun 1.4.0 (`bun`)             |
| Build             | `gcc`, `g++`, `make` (build-essential)                                                                         |
| Source and fetch  | `git`, `curl`, `wget`, `ssh`, `zip`, `unzip`, `xz`                                                             |
| Search and data   | `rg` (ripgrep), `fd`, `jq`, `sqlite3`                                                                          |
| System            | `sudo`, `adduser` and `useradd`, `chronyd`, `sshd` (for [SSH and editors](./editors)), `ip`, `iptables-legacy` |
| Agent sandboxing  | `bwrap` (bubblewrap). Codex runs its commands under it. It is in the default image from its next build         |

**Anything else installs the usual way:** `sudo apt-get install -y ...`, `pip install ...`, `npm install ...`, or `uv pip install ...`. A new sandbox has no apt package lists yet. Run `sudo apt-get update` once before the first `apt-get install`. To start every sandbox with your dependencies already there, build a [custom image](./images).

- **bubblewrap:** until the default image includes `bwrap`, run `sudo apt-get update && sudo apt-get install -y bubblewrap` to add it. Codex, and other agents that sandbox their own commands with it, then work as on any Linux machine.
- **Java, Go and Rust:** install Ubuntu's packages with `sudo apt-get install`. For a newer release, use the language's own installer, such as `rustup` for Rust. To have one in every sandbox, build a custom image whose recipe installs it. Or start the image from a public image that already has it.
- **Docker:** `sudo enable-docker` installs Docker Engine, Buildx and Compose. The first `docker` command starts it for you. See [Docker](#docker) below.
- **A Dockerfile:** run it with Docker in a sandbox. Or build it as a custom image and start sandboxes from that image. Multi-stage builds, `COPY --from`, heredocs and `.dockerignore` work as in Docker.
- **Browsers:** they are not in the image, so its disk stays small. Playwright's Chromium installs in two commands:

```bash no-run
sudo npx playwright install-deps chromium
npx playwright install chromium
```

## Who you are

- Commands run as the user `runtime` (uid 1000), in `bash`. `USER` and `LOGNAME` say so.
- `HOME` is `/workspace`, which is also the default working directory. Files there belong to you.
- `sudo` works without a password. You are root inside your own sandbox. To run one command as root, without typing `sudo`, give it `user: "root"`. This works for exec, background processes and terminals. In the CLI, use `--root`. To run every command as root, create the sandbox with `user: "root"` (`--user root` in the CLI). Or set it later with `:update`. Its commands, background processes and terminals then run as root. The exception is a command that names `user: "sandbox"`. A fork, or a copy of its snapshot, also runs as root. Files written through the files API and SSH logins stay `runtime`'s. Root cannot change what the sandbox may reach. Root cannot change how much CPU and memory it has, or what it costs. The host enforces those, outside the sandbox.
- `PATH` starts with `/workspace/.local/bin`, then `/usr/local/bin`, `/usr/bin` and `/bin`. `LANG` is `C.UTF-8`.
- Variables you set with `env` at create, or change with `:update`, are in every command. They are also in every background process, terminal, SSH session and the image's start command. They stay for the sandbox's whole life, under each command's own `env` ([API](./api#sandboxes)). Their values are never shown back. `:update` works on a paused or stopped sandbox too. A change reaches commands and processes started after it. A program already running keeps the values it started with, even through a pause and wake. Restart it to pick up a change.

`pip install` works without a virtual environment. As `runtime`, it installs to `/workspace/.local`, whose `bin` is first on `PATH`. Under `sudo`, it installs to `/usr/local`. The image's `/etc/pip.conf` sets `break-system-packages`. So the Ubuntu rule against installing into the system Python (PEP 668) does not stop you. Use `python3 -m venv` or `uv` when you want isolation.

`npm install -g` and `bun add -g` put their commands in `/workspace/.local/bin` too. So a tool such as `claude` or `codex` runs by name as soon as it is installed. With npm, `sudo` is optional. `pnpm` and `yarn` fetch the version that a project's `packageManager` names. They do this the first time they run.

## The machine's identity

A sandbox is not booted when it starts. It is a copy of a machine that booted once. Most of what a machine calls its own identity is made new for each copy. Not all of it is.

- `/etc/machine-id` belongs to the sandbox. It is made when the sandbox first starts, and kept for its whole life. That includes pauses, wakes, stops and restarts. A fork, or a sandbox created from a snapshot, gets a new one. Use it when a program needs an ID for the machine it runs on.
- `/dev/urandom`, `getrandom` and every program started in the sandbox get fresh randomness. Programs already running when a fork or snapshot was taken keep their own state. See [randomness in copies](./storage#randomness-in-copies).
- The kernel's boot ID (`/proc/sys/kernel/random/boot_id`) and boot time (`uptime`, `btime` in `/proc/stat`) belong to the machine that booted. So sandboxes made from the same image can share them. The kernel cannot change them without a reboot. `restart` gives a sandbox its own. Do not use the boot ID to tell sandboxes apart.
- The hostname is `runtime-guest` in every sandbox.

## Disk, CPU and memory

- **Disk:** `diskMiB` includes the system image and installed packages. In a measurement on 24 September 2026, the current default 4 GiB sandbox had about 2.5 GiB available. If you install a lot, request a larger disk. The smallest disk is 3072 MiB, the size of the image file.
- **Disk speed:** a sandbox shares its server's drives with the sandboxes beside it, in proportion. It has no fixed ceiling of its own. It gets at least about 40 MB/s each way. It gets up to about 1 GB/s when its neighbors are quiet. One busy sandbox cannot starve the others. A pause writes its memory ahead of everyone's traffic. So it stays quick on a busy server.
- **CPU:** shared by default. It has a guaranteed floor (`cpuFloorMillis`, 50 thousandths of a vCPU unless you ask for more). It can burst up to `vcpu` cores. `cpu: "reserved"` sets that same floor on every vCPU (`vcpu` x 1000). You pay for the CPU the sandbox uses. A paid sandbox has up to 16 vCPUs. Without credit, it has up to 2.
- **Processor:** AMD EPYC (x86-64, Zen). AVX, AVX2 and FMA are guaranteed on every server. Code that requires them, such as MuJoCo, can count on them. A paused sandbox or a snapshot wakes only on a server that shows it the same processor features. So a running process never loses one. AVX-512 is not offered.
- **Memory:** what you ask for, up to 64 GiB on a paid sandbox and 4 GiB without credit.

### When a program runs out of memory

A sandbox that runs out of memory stays up. Linux's out-of-memory killer ends the program that uses the most memory. The rest keeps running. Your programs share the sandbox's memory, minus a reserve for its own services. The reserve is a sixteenth of the memory, at least 128 MiB and at most 256 MiB. So while programs fill the memory, commands, file reads and kills still get a response. A program ended this way exits with -9 (137 from a shell). It often prints nothing. Runtime says why. The command's result, its process (read, get or list) and the stream's `exit` event carry `outOfMemory`:

```json
{
  "exitCode": -9,
  "outOfMemory": {
    "code": "out_of_memory",
    "processesKilled": 1,
    "memoryMiB": 512,
    "message": "The sandbox ran out of its 512 MiB of memory, and Linux's out-of-memory killer ended 1 process of this command.",
    "hint": "Give the program more memory: create the sandbox with memoryMiB 1024 or more, or resize this one while it is paused (POST /v1/sandboxes/{id}:resize with memoryMiB). Or make the program use less."
  }
}
```

`processesKilled` counts the program and anything it started. So a shell whose child was killed says so too. A result without `outOfMemory` was not ended for memory. Each such command also sends the account event `sandbox.out_of_memory` ([observability](./observability#events)). Your backend hears of it even after the sandbox is gone. With `check: true` (`check=True` in Python), the call raises `CommandError` with the code `out_of_memory` and the hint. The CLI prints the message and the hint after the command's output. `runtime sandboxes ps` marks the process "(out of memory)".

See [pricing](./pricing) for what each costs.

## The network

A sandbox has no network card. All outbound traffic goes through a proxy on the host. The image sets the environment variables that every tool needs to find the proxy:

```text
HTTP_PROXY=http://127.0.0.1:10800   http_proxy=http://127.0.0.1:10800
HTTPS_PROXY=http://127.0.0.1:10800  https_proxy=http://127.0.0.1:10800
NO_PROXY=localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
NODE_USE_ENV_PROXY=1
```

The private ranges in `NO_PROXY` are your own Docker containers. They are reached directly.

`sudo` keeps these settings. Programs that ignore proxy settings also work. Names resolve inside the sandbox. Their TCP connections go to the same proxy on their own. In a paid sandbox, `git clone git@github.com:...`, `psql`, database drivers, gRPC and `ssh` need no setup. A sandbox without credit reaches ports 443 and 80 only. So there, clone over HTTPS (`git clone https://github.com/...`).

A paid sandbox reaches any public host on any port, once your account has made a purchase. A sandbox without credit reaches ports 443 and 80. For both, private and internal addresses are refused. Mail ports (25, 465 and 587) are closed unless support enables them for your account. A few ports are never reachable: telnet, Windows RPC, NetBIOS and SMB, and IRC. TCP leaves the sandbox. A paid sandbox also sends UDP to any public address and port ([outbound UDP](./networking#outbound-udp)). DNS is resolved inside the sandbox.

**Bandwidth.** Downloads are fast for everyone. Uploads are limited, and more strictly without credit, because spam and floods use uploads. Downloads have no speed limit. Each server's link is shared between the sandboxes using it. While the link is full, a paid sandbox gets four times a sandbox without credit's share. A sandbox paid for with credit uploads at up to 500 Mbit/s. After its first 10 GiB at that speed, it uploads at 200 Mbit/s. It earns the burst back at that rate while it sends less. A sandbox without credit uploads at up to 10 Mbit/s. A paid sandbox (any account with credit, bought or given) can move 500 GiB a day, in and out together. The window is 24 hours, and it starts with the sandbox's first byte. An account without credit can move 1 GiB a day. That amount is shared by all its sandboxes. Each sandbox's bytes count until its own window ends, even once it is deleted. Connections to your own sandboxes by name (`<name>.sandbox.internal`) are not uploads: they count toward neither the upload limits nor this daily amount ([networking](./networking)). Past the daily amount, open connections close. New requests get `429 Too Many Requests` with `X-Runtime-Egress: quota-exhausted`. For the shared amount of an account without credit, the header is `quota-exhausted:account`. This lasts until the window ends. Credit added to an account without credit moves its running sandboxes to the paid amount. What they have used is kept. Inbound traffic is free. Each account's first 100 GiB out a month is free. After that, outbound traffic costs $0.02 per GB (10⁹ bytes) ([pricing](./pricing#network-products)).

**Connections.** A sandbox of an account that keeps a top-up holds up to 512 outbound connections open at the same time for each vCPU, up to 4,096. Any other sandbox holds 64. Every sandbox opens up to 20 new connections a second. It can open a first 128 at the same time (40 without a kept top-up). A sandbox starts reaching up to 120 different hosts and ports a minute. So an agent can hold hundreds of connections to the APIs it uses. A scan stays slow. Past a rate, a new connection waits up to 30 seconds for its turn. It does not fail. For example, 500 connections opened at the same time to one host all connect within about 20 seconds. Past a limit, a new connection gets `503 Service Unavailable` with `Retry-After: 1`. The limit appears in `X-Runtime-Egress`, such as `too many open connections (512 of 512)` or `too many new connections (20 a second)`. It is never a reset. First, though, a connection silent for a minute or more is closed to make room. A sandbox holds about 1,000 outbound connections at the same time, even when its limit is higher. Past that, and whenever the sandbox cannot reach Runtime's proxy, a new connection gets `503 Service Unavailable` with `X-Runtime-Egress: proxy unreachable (<reason>)`, such as `proxy unreachable (connection reset by peer)`. Each limit a sandbox meets also sends the account event `sandbox.network.limited`, at most once an hour per limit ([observability](./observability#events)). `GET /v1/sandboxes/{id}/network` shows a sandbox's limits. Reuse connections (HTTP keep-alive pools) rather than opening one per request.

Each sandbox has its own rules. Set them at create (`network`), or at any time after. They apply immediately, to open connections too:

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create({
  network: { internet: true, allow: ["pypi.org", "*.pythonhosted.org"] },
});
await sbx.network.set({ internet: true, deny: ["example.com"] });
await sbx.network.set({ internet: false });
console.log(await sbx.network.get());
```

- `internet: false` refuses every outbound connection. With an `allow` list, it is allow-list only. The sandbox reaches the listed destinations and nothing else. It is stored and shown as `internet: true` with that list. This holds at create and on `network.set` alike.
- `allow` narrows the sandbox to a list, on every port it may use. The list takes domains, `*.domain` for every name under one, addresses, or CIDR ranges.
- `deny` always wins.
- `connect` adds `host:port` pairs beyond the web ports, such as your own database or `github.com:22`. Use it when `allow` narrows a paid sandbox and the pair is not in the list.
- `sbx.network.get()` says `openPorts: true` for a sandbox that reaches every port.
- A sandbox without credit, on the [free usage](./included-usage#without-credit), reaches ports 80 and 443 only. A `connect` rule on it is refused with `connect_not_allowed` (403). The message says which limit it met. Once the account has a kept top-up, its paid sandboxes reach every port. Topping up is the account owner's decision.

To give code in a sandbox an API key it can use but never read, store it as a secret. See [Security](./security#secrets-sandboxes-never-see).

The rules apply to root inside the sandbox too.

### Runtime's API from inside a sandbox

Code in a sandbox can call Runtime's API. So an agent in one sandbox can start, run and stop others. Inside a sandbox, the API is at `http://runtime.internal`. Every Runtime SDK (JavaScript, Python, Go, Java and Ruby) uses it on its own. Calls for `https://api.withruntime.com` go there. An API origin you set yourself is left as it is. Give the sandbox a key as usual, as a secret or in `env`:

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

// Inside a sandbox, with RUNTIME_API_KEY set.
const runtime = new Runtime();
await using child = await runtime.sandboxes.create();
console.log((await child.exec("echo hello from a child")).stdout);
```

Any HTTP client works the same way, through the proxy settings above:

```bash no-run
curl -H "Authorization: Bearer $RUNTIME_API_KEY" http://runtime.internal/v1/me
```

- The sandbox's host sends each request on to `https://api.withruntime.com` over HTTPS. The hop from your code to the host is plain HTTP. It never crosses a network. It runs over the sandbox's own private channel to its host, which no other sandbox can reach.
- It is the same API with the same key. Your account's limits, roles and rate limits apply. Errors carry the same request IDs.
- Paths under `/v1/` are served, and `/mcp` for [Runtime's MCP server](./mcp).
- In a Docker container inside the sandbox, set `RUNTIME_API_URL=http://runtime.internal`.
- A sandbox holds up to 32 API requests open at the same time. Past that, a request gets `429` with `X-Runtime-Egress: api-busy`. Retry it. API requests count toward the sandbox's new-connection rate, bandwidth and daily amount. They are never charged as outbound traffic.
- The sandbox's own rules apply. With `internet: false` and no `allow` list, or with an `allow` list that leaves out `api.withruntime.com`, requests are refused. The header is `X-Runtime-Egress: internet-off` or `rule-not-allowed`.

Nothing on the internet can connect in to a sandbox. These are the ways in. You open each one yourself:

- A preview: an HTTPS address for one port that you share on purpose. It is private, with a token, by default. Search engines never index it. See [JavaScript](./javascript#share-a-port) or `npx withruntime sandboxes preview`.
- A connection from your own computer. `runtime sandboxes ssh` and `runtime sandboxes port-forward` reach any port on the sandbox's loopback. They go through Runtime's API, with your key. They need nothing set up. See [SSH and editors](./editors).
- For an account with a kept top-up: a custom domain, a public TCP port, or a WireGuard tunnel from your own network into your sandboxes (`runtime networks wireguard`, the private network). See [networking](./networking).

A sandbox with none of these accepts no connections from anyone but you. For a sandbox created from 5 October 2026, what it sends back through a preview, a custom domain or a TCP port counts as outbound traffic. What visitors send in is free ([pricing](./pricing#network-products)).

To start a server that keeps responding, use `spawn` (`runtime sandboxes spawn`, `sbx.spawn`), not `exec`. Everything an `exec` starts ends when its command does. That includes `nohup … &`.

## Docker

```bash no-run
sudo enable-docker          # once per sandbox; the first docker command runs it too
docker run --rm hello-world
docker compose up -d
```

- `enable-docker` installs Docker Engine, Buildx and Compose from Ubuntu's archive, and starts them. After that, `docker` works as the sandbox user, without `sudo`.
- Docker starts on the first `docker` command after a boot. So a sandbox that runs no containers spends nothing on it.
- Images and containers live on the sandbox's disk. For a sandbox that runs containers, set more disk than the default, such as `diskMiB: 8192`.
- Containers reach the web with no proxy settings. Their outbound connections go through the sandbox's relay. This is the same path as a program in the sandbox that ignores `HTTP_PROXY`. Docker Hub images come through Google's public mirror, `mirror.gcr.io`, first.
- Compose services, and containers on one Docker network, reach each other by name, as anywhere.
- A published port (`-p 8080:80`) listens inside the sandbox. `runtime sandboxes port-forward <id> 8080` brings it to your machine. A preview shares it.
- To start every sandbox with Docker installed, build a custom image whose recipe runs it: `commands: ["enable-docker --no-start"]`.

## FUSE filesystems

FUSE is built into the kernel, and `/dev/fuse` is in every sandbox. So sshfs, rclone, bindfs, s3fs, gcsfuse, squashfuse or your own FUSE program can mount as the sandbox user. `sudo` is not needed:

```bash no-run
sudo apt-get update && sudo apt-get install -y fuse3 sshfs
mkdir -p ~/remote && sshfs me@example.com:/srv ~/remote
fusermount3 -u ~/remote
```

- **`allow_other`** lets other users, such as root or a container, see the mount. It is refused until you add `user_allow_other` to `/etc/fuse.conf`. Or mount with `sudo`.
- **A bucket:** for S3, R2 or Google Cloud Storage, use [Mount your own bucket](./storage#mount-your-own-bucket). It keeps the key out of the sandbox.
- **Lifetime:** a mount is a process in the sandbox. It lasts through a pause and a wake, and ends when the sandbox stops.

## Time and lifetime

- The clock follows the host's clock. It is set again after every wake.
- A sandbox runs while it works. It pauses itself when idle (`idlePauseSeconds`). It runs until you stop it, or until credit or the [free usage](./included-usage) runs out. Then it pauses or stops, as `onTimeout` says. It has no time limit unless `timeoutSeconds` sets one (60 to 86,400). `extend` moves that limit. A pause keeps its memory and processes.
- A stop keeps the disk. It is billed as [paused storage](./pricing#paused-storage), until you delete the sandbox. `restart` starts it again, with its memory gone. A stop is still not a backup. Copy out what you need to keep.
- A deleted sandbox is gone. `DELETE /v1/sandboxes/{id}`, `sandbox.delete()` or `runtime sandboxes rm <id>` stops it and deletes its disk and paused memory, in any state. Its snapshots stay.

### Pause, stop or delete

|                             | Pause                                                                  | Stop                                                                   | Delete                               |
| --------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------ |
| Memory and running programs | Kept                                                                   | Gone                                                                   | Gone                                 |
| Files on its disk           | Kept                                                                   | Kept                                                                   | Gone                                 |
| Comes back with             | `wake`: it carries on where it was                                     | `restart`: it boots fresh from its disk                                | Nothing; create a new one            |
| Happens on its own          | When idle, and by default when its time, credit or free usage runs out | When its time, credit or free usage runs out, with `onTimeout: "stop"` | The same, with `onTimeout: "delete"` |
| Billed                      | [Paused storage](./pricing#paused-storage) for its memory and disk     | Paused storage for its disk                                            | Nothing; its snapshots stay billed   |

Pause when you will come back to the same work and want its programs still running. Stop when only the files matter. Delete when you are done.

### Timers wake an idle sandbox

A sandbox that pauses because it is idle wakes by itself when a process in it is due. At the pause, Runtime reads the sandbox's pending timers and records the soonest one: a `sleep`, a `poll`, `select`, `epoll_wait` or futex wait with a timeout, a `timerfd`, `alarm` or `setitimer`, or a POSIX timer (`timer_create`). The sandbox wakes about one second before that timer is due, as a request would wake it. So an agent that checks CI every ten minutes, or a loop that runs `sleep 600`, runs when it is due, and the sandbox costs nothing in between.

- Only a timer that was pending for the whole idle time counts. A process that wakes every few seconds or every minute and does nothing new, such as a database's background writer or `cron`, did that while the sandbox was idle, and does not wake it again.
- A sandbox with no pending timer stays paused until a request wakes it.
- A timer wake is an ordinary wake. It is billed as one, and the sandbox pauses again after `idlePauseSeconds` with nothing happening.
- Timers do not wake a sandbox that you paused, that paused at the end of its time limit, its credit or its free usage, or that has `autoWake: false` or `wakeOnTimers: false`. Timers of the init system (systemd timer units) and of Runtime's own services in the sandbox do not wake it either.
- A wake that is refused, for example for lack of credit, is tried again every 30 seconds while the sandbox stays paused. A wake for an API key or agent that has since been revoked is not retried. A sandbox deleted at the end of its paused retention is not woken.
- To keep request wakes and turn off timer wakes, set `wakeOnTimers: false` at create, or later with `POST /v1/sandboxes/{id}:update`. A fork keeps its source's setting. Turning it back on applies from the sandbox's next idle pause. In the SDKs this is `wakeOnTimers: false` (TypeScript), `wake_on_timers=False` (Python), `wake_on_timers: false` (Ruby), `WakeOnTimers` (Go) and `wakeOnTimers(false)` (Java). In the CLI it is `--no-wake-on-timers` at create, or `runtime sandboxes update <id> --wake-on-timers off`. Turning it off also cancels a timer wake that is already planned.
- Only a timer due within 29 minutes of the pause wakes the sandbox, and only while the paused sandbox is kept in memory. After 30 minutes, or sooner when its server needs the memory, a paused sandbox is moved to disk, and its processes' clocks resume where they paused. A timer due later does not wake it, and it stays paused until a request wakes it.


---

<!-- https://withruntime.com/docs/sandbox-lifecycle -->

# Sandbox states and actions

A sandbox is always in one of seven states. The `state` field of every read names it, and `actions` lists what you can do from there: each listed action changes the sandbox. An action not listed changes nothing (a pause of a paused sandbox returns it as it is) or returns `409`, with the same list in `details.actions`. A wait for a state (`GET /v1/sandboxes/{id}?waitFor=running`) returns as soon as the sandbox is there, or as soon as it cannot get there without a new action, such as a sandbox you stopped.

This page is generated from the sandbox's lifecycle in the code.

## States

| State | You can | It moves by itself to |
| --- | --- | --- |
| `starting` | `stop`, `delete` | `running`, `stopping`, `stopped` |
| `running` | `pause`, `stop`, `restart`, `delete` | `starting`, `pausing`, `paused`, `stopping`, `stopped` |
| `pausing` | `wake`, `stop`, `delete` | `paused`, `stopping`, `stopped` |
| `paused` | `wake`, `stop`, `delete` | `starting`, `resuming`, `stopping`, `stopped` |
| `resuming` | `stop`, `delete` | `running`, `pausing`, `paused`, `stopping`, `stopped` |
| `stopping` | `delete` | `stopped` |
| `stopped` | `restart`, `delete` | nothing: it has ended |

`restart` on a stopped sandbox needs its disk kept (`diskKept`); on a running one it reboots it. A job's run lists no `restart`. While Runtime moves a sandbox between servers, only `pause` is listed.

When the server a sandbox runs on is lost, its memory is lost with it. A disk with a copy on another server (`diskKept: true`) is kept. A sandbox that was running is stopped with `stopReason: host_lost`, then Runtime restarts it from that disk on another server. One that was paused stays paused; its next wake starts it from its disk (`memoryRestored: false`).

## Every move

| From | To | Made by | Why |
| --- | --- | --- | --- |
| `starting` | `stopping` | your action | stop |
| `starting` | `running` | Runtime | its machine started |
| `starting` | `stopping` | Runtime | its machine was lost as it started and not put back |
| `starting` | `stopping` | Runtime | its start failed |
| `starting` | `stopping` | Runtime | no room came while it waited |
| `starting` | `stopping` | Runtime | its time or cost limit |
| `starting` | `stopped` | Runtime | its host was lost |
| `starting` | `stopped` | Runtime | its machine ended on its own |
| `starting` | `stopped` | Runtime | its moved pause could not be restored |
| `running` | `stopping` | your action | stop |
| `running` | `pausing` | your action | pause |
| `running` | `stopped` | Runtime | a primary lost with its host took over its machine |
| `running` | `starting` | Runtime | its machine was lost as it started |
| `running` | `stopping` | Runtime | its machine was lost as it started and not put back |
| `running` | `stopping` | Runtime | no room came while it waited |
| `running` | `pausing` | Runtime | idle pause |
| `running` | `stopping` | Runtime | its time or cost limit |
| `running` | `paused` | Runtime | its machine was frozen under it |
| `running` | `stopped` | Runtime | its host was lost |
| `running` | `stopped` | Runtime | its machine ended on its own |
| `pausing` | `stopping` | your action | stop |
| `pausing` | `resuming` | your action | wake |
| `pausing` | `starting` | your action | wake |
| `pausing` | `stopping` | Runtime | its machine was lost as it started and not put back |
| `pausing` | `stopping` | Runtime | no room came while it waited |
| `pausing` | `stopping` | Runtime | its time or cost limit |
| `pausing` | `paused` | Runtime | its machine froze |
| `pausing` | `stopped` | Runtime | its host was lost |
| `pausing` | `stopped` | Runtime | its machine ended on its own |
| `paused` | `stopping` | your action | stop |
| `paused` | `resuming` | your action | wake |
| `paused` | `starting` | your action | wake |
| `paused` | `stopping` | Runtime | its machine was lost as it started and not put back |
| `paused` | `stopping` | Runtime | no room came while it waited |
| `paused` | `stopping` | Runtime | its time or cost limit |
| `paused` | `resuming` | Runtime | a process's timer |
| `paused` | `starting` | Runtime | a process's timer |
| `paused` | `stopped` | Runtime | its host was lost |
| `paused` | `stopped` | Runtime | its machine ended on its own |
| `resuming` | `stopping` | your action | stop |
| `resuming` | `stopping` | Runtime | its machine was lost as it started and not put back |
| `resuming` | `stopping` | Runtime | no room came while it waited |
| `resuming` | `paused` | Runtime | no host can hold it |
| `resuming` | `pausing` | Runtime | its wake was given up |
| `resuming` | `stopping` | Runtime | its time or cost limit |
| `resuming` | `running` | Runtime | its machine woke |
| `resuming` | `stopped` | Runtime | its host was lost |
| `resuming` | `stopped` | Runtime | its machine ended on its own |
| `resuming` | `paused` | Runtime | its moved pause could not be restored |
| `stopping` | `stopped` | Runtime | its machine froze |
| `stopping` | `stopped` | Runtime | its host was lost |
| `stopping` | `stopped` | Runtime | its machine ended on its own |
| `stopped` | `starting` | your action | restart |
| `stopped` | `starting` | Runtime | started again over its disks after its host was lost |
| `stopped` | `running` | Runtime | it took over a standby's running machine |


---

<!-- https://withruntime.com/docs/security -->

# Isolation and account boundaries

Runtime uses Firecracker microVMs on Runtime-operated dedicated servers.

- Each sandbox has its own Linux kernel, disk and guest environment.
- CPU, memory, disk, network rules, time limits and billing are enforced on the host, outside the guest.
- Host credentials, control sockets and provider credentials never reach customers.
- Our own servers run tests of guest separation, selected private-address refusals, restart recovery and time limits that end on the host.
- A fork, or a create from a memory snapshot, copies each running program's random-number state. Make keys and tokens after the copy. See [randomness in copies](./storage#randomness-in-copies).

## Keys and secrets

**Keep keys in server-side secret storage, one per agent or application.**

- A key covers every Cloud product, including products enabled later. It lasts until revoked.
- A key can never do more than the role of the member who made it allows. Runtime reads that role on every request (see [teams](./teams)).
- Never put a key in a public prompt, URL, browser bundle, repository, command-line argument or diagnostic log.
- A framework adapter does not expand what the key is allowed to do.
- If a key turns up in public, Runtime may revoke that one key. The account's owners are emailed why. The audit log shows that Runtime revoked it, and the reason. Every other key keeps working.

Pass a command its secrets through `env`, never in the command line. Runtime never echoes `env` values back. Its journals and request records keep only a hash of them. A command line is not protected that way. Anything running in the sandbox can read it.

**Runtime keeps a command's program name, never its arguments.** For each command run through the API, the SDKs, the CLI or MCP, Runtime records the program (`python3`, from `python3 train.py --token …`). It also records the exit code, how long the command ran, when it started, which key or person ran it, and in which sandbox. Arguments, the rest of the command line and environment values are never stored. Arguments can carry a secret typed inline. A terminal is recorded as its shell and nothing typed in it. A code interpreter cell is recorded as its language (`python-cell`), never its code. Runtime keeps the record for 14 days. It shows on the sandbox's page in your account.

## Read-only keys and daily limits

**Both are optional.** Without them, a key reaches every product. Its use is limited only by your prepaid balance.

- **Read-only key.** Choose **Read only** when you create a key at [API keys](https://withruntime.com/account/keys), or pass `--read-only` to `runtime keys create`. It sees the whole account. That includes every sandbox and its state, spec and cost, the images, volumes, snapshots, previews and network rules beside them, account notices, the balance, and its own access and limit. It also covers products added later. It cannot create, start, stop, pause, wake, run a command, write a file, change anything or spend anything. It does not see inside sandboxes (files, command output), job runs or secrets. A private preview reaches it without its token. Use it for monitoring, dashboards and CI checks.
- **Daily spending limit.** Set one on any key that can spend. Set it when you create the key, or later from its row. The limit is the most that key's agent may commit in any 24 hours. It counts what is already charged and what running sandboxes are about to use. It counts everything the agent's sandboxes cost, including renewals and parked storage. An account-wide key's limit also counts what it asks for on another key's sandbox. That covers a wake, an extension or a restart. It also covers the renewals that carry that sandbox to the end of its `timeoutSeconds`. When a create, wake, extension or renewal would pass the limit, the request fails with `spending_limit_reached` (HTTP 402). Nothing is charged. A running sandbox keeps the time it is already funded for. A sandbox whose next renewal would pass the limit stops or pauses at the end of that time. Room returns as older spending leaves the 24-hour window.

An owner, admin or developer of the account can create a key of either kind:

- They create one at [API keys](https://withruntime.com/account/keys), or approve one in the browser that `runtime keys create` asked for from a terminal (see below).
- The member who made a key, or an owner or admin, sets, changes or removes its limit. They can do this only on the website.
- A key acts on what its own agent made. Only an owner or admin can make a key **account-wide**, so it sees and uses everything in the account. An account-wide key is allowed only for a key of an owner or admin. It lapses if that person becomes a developer ([keys in a team](./teams#keys-in-a-team)).
- A key can read its own access and limit with `GET /v1/limits`, `runtime limits` or the `runtime_account` tool's `limits` action.
- No key can raise, remove or set a limit. A full-access key of an owner or admin can make keys that have no more than it has ([run a swarm](./teams#run-a-swarm)).
- The [audit log](./teams#audit-log) records every key made, revoked or limited, and every connection approved. Each entry names who did it and from where.

A sandbox can also carry `maxTotalCostMicros`. This is the most it may cost over its whole life. When it reaches that cost, the sandbox stops, with `stopReason` `lifetime_cap`.

Set a limit above what the agent's paused sandboxes cost in a day. If storage for a paused sandbox cannot be paid for, it is treated like storage on an empty balance. You are notified by an account notice. The account's owners also get an email a day before. After seven days unpaid, it is deleted.

## Compartments

**A compartment separates a group of keys from the rest of the account.** Use one per customer of your platform, or for an agent whose sandboxes no other key may reach.

- An owner or admin makes one at [API keys](https://withruntime.com/account/keys). Choose **One compartment** under **Sees** when you make a key. Then pick a compartment, or name a new one. More keys can join it the same way.
- A key in a compartment lists, creates, runs commands in, forks, snapshots, pauses, wakes and deletes these: sandboxes, snapshots, images, volumes, previews, ports, jobs, job secrets, Apps and Functions. It acts only on those that its compartment's keys made. It can use nothing else.
- It deploys an App or Function from an image only. A deploy that names a `build` returns 403 `outside_compartment`. Builds and repositories return the same error.
- It cannot give an App or Function a name that one of the account's own Apps holds. Creating or renaming it returns 409 `name_taken`.
- It may set an App's `releaseWatch` to `alert` or `rollback`, but never `off`. Turning it off would stop the owners hearing of a release that got worse. Turning it off returns 403 `forbidden`.
- Anything outside its compartment returns 404 `not_found`, the same as an id that does not exist. No key outside the compartment reaches in either. That includes read-only keys. The only exception is an account-wide key, which sees everything in the account.
- Each compartment has its own sandbox names. `getOrCreate("main")` in one compartment never returns another compartment's `main`. A name held by another compartment never returns `name_taken`.
- An image name belongs to the compartment (or the rest of the account) that first built it. Nobody else can add a version to it or move its tags. A build by another compartment with that name returns 409 `name_taken`.
- A fork, or a create from a snapshot, stays in the compartment of the key that made it. A resource never moves between compartments. A key's compartment is set when the key is made and never changes.
- A key in a compartment cannot reach the account's own settings. These are billing, keys, domains, dedicated addresses, the account's networks, egress secrets, registry logins, webhooks, telemetry export, the audit log, builds and repositories. Those return 403 `outside_compartment`. The key can read who it is with `GET /v1/me`. Its `compartment` field names its compartment.
- A compartment's sandboxes are not in the account's private network or its WireGuard peers. The account's egress rules, egress secrets, your own proxy and signed requests still apply to them.
- No key can make a compartment. A compartment can be deleted only when it holds nothing. Deleting one that holds something returns 409 `compartment_not_empty`. Its keys stop working when it is deleted.
- The [audit log](./teams#audit-log) records each compartment and every key put in one.

## Network access

**Every outbound connection goes through a proxy on the host.** Programs that use `HTTP_PROXY` and programs that open raw sockets follow the same rules. Nothing in the guest can go around it, root included.

- A paid sandbox of an account with a kept top-up reaches any public host on any port. A sandbox without credit reaches ports 443 and 80.
- Some ports are never reachable: telnet, Windows RPC, NetBIOS and SMB, and IRC. Mail ports open only when support enables mail for your account.
- Private and internal addresses are refused. Code that retries one, such as a cloud SDK looking for credentials at the metadata address, is only refused.
- The proxy watches every sandbox, with credit or without, for traffic that only abuse makes. That includes trying one internal address after another. It includes a port scan, or a sweep of addresses that do not answer. It includes a cryptocurrency mining pool, and mail sent straight to many mail servers. The thresholds sit far above what test suites, builds, package installs, crawlers within the limits, CI and load tests against your own servers do. A sandbox that crosses a threshold loses its network on every server it runs on. Your inbox (`GET /v1/notices`) says what was seen and what was done. On an account that has paid, the sandbox keeps running, with its processes and files untouched, and a person reviews it before anything more is done: they lift the hold, which turns its network back on, or confirm it, which pauses the sandbox. An account that has paid is never suspended for it. An account that has never paid is suspended for any of them. Your files are never out of reach: you can always read or download a held sandbox's files with `GET /v1/sandboxes/{id}/files/content` or `GET /v1/sandboxes/{id}/files/archive`, which wake it if it is paused, and it can be woken or started. Until the hold is lifted, its network is off for outbound and inbound traffic (previews, custom domains, TCP ports and private networks), and a command, terminal, file write, snapshot or fork of it, or a start from a snapshot of it, returns `sandbox_halted`. Connections to Runtime's own servers are refused and count as probing; SSH to their public addresses counts toward its own limit of 10 different servers in ten minutes. If you think a hold is a mistake, write to support with the sandbox id. Traffic that looks like a flood, repeated attempts on the closed mail ports, or full CPU beside a mining pool's website is only recorded for a person to look at.
- Services that exist only to catch a security test's call-back are refused to every sandbox and image build. Examples are `oast.live`, `interact.sh` and Burp Collaborator. To test Runtime itself, see [report a vulnerability](#report-a-vulnerability).
- Each sandbox's rules can narrow this further. They bind root inside the sandbox too. See [the sandbox environment](./sandbox-environment).
- Code in a sandbox reaches Runtime's own API only at `http://runtime.internal`. It uses an API key, like any other caller. The host sends each request on to the public API over HTTPS. It reaches nothing else of its own. See [Runtime's API from inside a sandbox](./sandbox-environment#runtime-s-api-from-inside-a-sandbox).
- Each sandbox has limits on concurrent connections, upload speed and bytes per day. It shares its server's link fairly with the other sandboxes, so one sandbox cannot crowd out the others. A paid sandbox uploads at up to 500 Mbit/s. Its sustained rate is 200 Mbit/s, after its first 10 GiB. It moves 500 GiB a day. A sandbox without credit uploads at up to 10 Mbit/s. It moves 1 GiB a day for the whole account. Uploads are limited because they are what spam and floods use. Downloads are not ([the sandbox environment](./sandbox-environment#the-network)).

Inbound connections need a preview, a proved custom domain, an allocated TCP port or an authorized private tunnel. Each reaches only the sandbox port and account it was granted.

A preview is private, with an expiring token, unless you make it public. A paid sandbox of an account with a kept top-up can make it public. A sandbox without credit's previews are always private. While an account is blocked, or every purchase it made is refunded in full, its public previews need the token, like private ones. They are public again once it pays.

Preview addresses are under `runtimehost.com`, never under `withruntime.com`. So sandbox content never shares an origin with your account.

A preview signed in by its cookie accepts a WebSocket, or a request that changes something, only from two places. One is its own address. The other is a site you allow to embed it. A request that changes something uses any method except GET, HEAD and OPTIONS. From any other page, another preview included, it returns `origin_not_allowed` (403). Code that sends the preview token in its header or query is not affected.

Rotating a preview token refuses every token issued before it. It also closes connections opened with one. This happens before the call returns. Making a preview private, deleting it, removing a custom domain or closing a TCP port takes effect the same way. So does Runtime taking a site down or suspending an account.

A suspension also pauses the account's running sandboxes. It keeps their memory and disk. None of them starts or wakes until the account is restored.

Public ingress rate tracking fails closed when its tracking table, which has a size limit, is full. Established connections and the separate operator SSH allowance follow their own rules.

When you move a project over, check that its package registries and other destinations are reachable under these terms.

## Secrets sandboxes never see

**Store an API key once. Your sandboxes use it without holding it.** Each secret has a name, a value and the hosts it may go to.

```bash no-run
printf %s "$OPENAI_API_KEY" | runtime secrets set OPENAI_API_KEY --host api.openai.com
runtime secrets ls
```

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

const runtime = new Runtime();
await runtime.secrets.set("GITHUB_TOKEN", {
  value: process.env.GITHUB_TOKEN ?? "",
  hosts: ["api.github.com", "*.githubusercontent.com"],
  header: "Authorization",
  format: "token {value}",
});
```

Or open [Settings → Secrets](https://withruntime.com/account/secrets). It lists every secret by name. For each one, it shows its kind and version, the hosts it may reach, where its value goes, its rules, which sandboxes get it, whether jobs have a copy, and who added it and last changed it. An owner, admin or developer can add a secret, replace its value or delete it there. The value is typed once and never shown again.

A secret is one of two kinds. Use the first whenever you can.

- **Added on the way out** (the default). The machine sees a placeholder. The value is added only to HTTPS requests to the hosts you name. Code in the machine can never read it or leak it. The rest of this section is about this kind.
- **Given to the machine as the real value** (`--exposed`). The machine gets the value itself. Use it for a database password, an SSH key, or anything that is not an HTTPS header. Code in the machine can read it. See [a secret the machine needs itself](#a-secret-the-machine-needs-itself).

- Every sandbox in your account (or only the sandboxes the secret names, see `only` below) has an environment variable named after the secret. It holds a placeholder such as `rtsec_3f9c…`. Code uses it as it would use the key: `Authorization: Bearer $OPENAI_API_KEY`, or an SDK that reads `OPENAI_API_KEY`.
- The host's proxy replaces the placeholder with the value. It does this in the credential header of HTTPS requests to the secret's hosts. The credential headers are `Authorization`, `x-api-key`, `x-goog-api-key`, `api-key`, `xi-api-key`, `x-subscription-token` and `private-token`. A request to any other host carries the placeholder. The placeholder is worthless on its own.
- The value never goes into the URL (its path or query) or into any other header. This holds even for the secret's hosts. There, the placeholder goes out as it is. A hijacked agent might request `https://api.openai.com/v1/$OPENAI_API_KEY`, hoping the server's error page repeats the path. It gets back only the placeholder.
- When a placeholder goes out unreplaced where the proxy can see it, the account gets the event `sandbox.secret_not_applied`. The event says which secret, and why. Examples are plain HTTP, the URL or another header, a request the rules keep out, and HTTPS to an address. See [events](./observability#events). To find why a placeholder arrived unchanged, see [troubleshooting](./troubleshooting#a-secret-s-placeholder-reaches-the-server-unchanged).
- With `header`, the proxy sets that header on every HTTPS request to the hosts. It replaces any value the sandbox sent in that header. Code then needs no placeholder at all. The value goes into that header and nowhere else. Use it for an API that reads its key from another header. When two secrets set the same header on one host, such as a key per team, the request carries one of them. It carries the one whose placeholder the sandbox put in that header. A request that names neither is refused with a 400 that names both. An API that takes a key only in the URL (such as `?key=`) cannot be used with a secret.
- With `rules`, on accounts with credit, the value goes only into requests that a rule allows. A rule allows requests by method and path. Runtime decides this for each request on a connection. A path is exact (`/v1/chat/completions`). Or it is a prefix ending in `/*` (`/repos/acme/*`). A prefix covers the paths under it. It does not cover `/repos/acme` or `/repos/acme/`. A segment that is `*` alone, before the end, matches any one segment. For example, `/repos/acme/app/pulls/*/comments` allows a pull request's comments and nothing else under it. The path is compared as sent, with the query left out. A request whose path a server could read two ways gets no secret that has rules. Such paths have any of these: `.` or `..` segments, a doubled slash (`//`), an escaped slash, letter, digit or dot (`%2F`, `%2e`), a semicolon or a backslash. Other escaped characters stay escaped. A server may read `%3A` and `:` differently. So a client that sends `/v1/models/x%3AgenerateContent` needs a rule written that way too. A request that no rule allows, with the placeholder in a credential header, is not sent. It returns `403 Forbidden` with `X-Runtime-Egress: secret-rule-not-matched`, and over HTTP/1.1 the connection closes. The body names the secret, the method and the path, without the query. A request without the placeholder is sent as it is. A secret can have up to 16 rules, with up to 16 paths each. In the CLI, from `withruntime` 0.7.0, give `--allow "GET,HEAD /repos/acme/*"` once per rule. Or give `--allow /v1/chat/completions` for every method. In the SDKs, use `rules: [{ methods: ["GET"], paths: ["/repos/acme/*"] }]`. An account with no credit gets `payment_required` (402).
- A secret's hosts and rules can be narrowed without its value, from `withruntime` 0.22.0. Run `runtime secrets set NAME --keep-value` with the narrower `--host` and `--allow`. The API is `PUT /v1/egress-secrets/{name}/rules`. The SDK call is `runtime.secrets.narrow(name, { hosts, rules })`. Every SDK has `narrow`. Narrower means the secret can go nowhere it could not go before. Each host must be one its hosts already name, such as `a.example.com` or `*.a.example.com` under `*.example.com`. Each method and path a new rule allows must be one its rules allow now. A secret without rules allows every request, so any rules narrow it. On an account with no credit, giving rules to a secret that had none returns `payment_required` (402). Storing rules does the same. Anything wider is refused with `invalid_request`. The error says what would widen. A new place could learn the value, so widening needs the value. The audit log records the change as an update with `narrowed`. For example, a token that should only fetch one repository over git:

  ```bash no-run
  runtime secrets set GIT_BASIC --keep-value \
    --allow "GET /acme/app.git/info/refs" --allow "POST /acme/app.git/git-upload-pack"
  ```

  A push (`POST /acme/app.git/git-receive-pack`) is then not sent. It returns `403 Forbidden` from Runtime, with `X-Runtime-Egress: secret-rule-not-matched`.

- With `only`, the secret goes to some of your sandboxes instead of all of them. Those are the sandboxes whose labels match a selector, and the sandboxes you name by id. Any other sandbox has no environment variable for the secret. The proxy puts its value into none of that sandbox's requests, even with the placeholder copied in by hand. A selector matches a sandbox whose labels hold every one of its pairs. A sandbox that matches any one selector gets the secret. This includes a sandbox created or labelled later. It has the secret from its first request. A running sandbox gets it from the moment the label change returns. With a key that may read secrets, the update waits until its server holds the change. It then says so with `secretsEnforced: true`. Any other key's relabel reaches the sandbox within 15 seconds. Use it to keep an orchestrator's own credentials away from the sandboxes it starts for others:

  ```bash no-run
  printf %s "$SLACK_APP_TOKEN" | runtime secrets set SLACK_APP_TOKEN --host slack.com --only-label role=hub
  runtime secrets set GITHUB_TOKEN --host api.github.com --only-label role=hub --only-label purpose=agent < token.txt
  runtime secrets set DEPLOY_KEY --host api.example.com --only-sandbox <sandbox id> < key.txt
  runtime secrets scope RUNTIME_API_KEY --only-label role=hub   # an existing secret, no value needed
  ```

  Each `--only-label` is one selector. `role=hub,tier=prod` needs both pairs. `--only-sandbox` names a sandbox by id, up to 100 of them.

  `--only-app <app id>` gives the secret to every copy of an App. Its copies get new ids at every deploy, restart and scale-up. Each copy has the secret from its first request. No other sandbox can join, because only Runtime makes an App's copies.

  The App's deploy names the secrets its copies see as environment variables, with `secrets: ["OPENAI_API_KEY"]`. The deploy needs a key that may reveal secrets. Later deploys by such a key keep them. So do pushes to the connected repository's production branch with unchanged build settings. A key that may only deploy cannot hand its own code the App's secrets. Such a deploy is refused. A copy holds the placeholder, never the value.

  In the SDKs, the form is `only: { labels: [{ role: "hub" }], sandboxes: ["<id>"], apps: ["<app id>"] }`. In Python and Ruby it is a dict. In Go it is `Only: &withruntime.SecretScope{...}`. In Java it is a map. Pass it to `secrets.set` or `secrets.scope`. In the API and MCP tool, use the same `only` object.

  Replacing a secret's value without `only` keeps the scope it has. So a new value never reaches more sandboxes than the old one did. `--all-sandboxes` (`only: {}`) gives the secret to every sandbox again. `runtime secrets scope` (`PUT /v1/egress-secrets/{name}/sandboxes`, `runtime.secrets.scope(name, only)`) changes who gets an existing secret without its value. `runtime secrets ls` shows who gets each one.

  Only the key that made a sandbox can label it. But any key of the account that can make sandboxes can make one with a scope's labels, and so get the secret. A sandbox made by a key in a compartment matches no label, only its id. For a credential that matters, name its sandboxes by id. Only a key that can write secrets can change those. Or keep keys that make sandboxes out of the sandboxes you are guarding.

  A scope is free on every account. An upstream proxy's credential is sent for every sandbox the proxy covers, whatever its scope.

- A secret's name is also the environment variable its sandboxes see. You can give `env` instead. Then sandboxes see the placeholder in that variable. Several secrets may share one variable. Each must be scoped to sandboxes the others do not reach. One example is a GitHub token per repository, each seen as `GITHUB_TOKEN`:

  ```bash no-run
  runtime secrets set GITHUB_TOKEN_WEB --host api.github.com --only-label repo=web --env GITHUB_TOKEN < web.txt
  runtime secrets set GITHUB_TOKEN_API --host api.github.com --only-label repo=api --env GITHUB_TOKEN < api.txt
  ```

  A sandbox labelled `repo=web` sees only `GITHUB_TOKEN_WEB`'s placeholder in `GITHUB_TOKEN`. Its requests carry only that token. In the SDKs and the API, set `env: "GITHUB_TOKEN"` on `secrets.set`. A store or scope change is refused with 409 `conflict` if it would let one sandbox get two secrets of the same variable. That happens when one secret reaches every sandbox, or when a sandbox is in both scopes now. A sandbox labelled into both scopes later sees the first by name. Both secrets reach it, as their scopes say. Replacing a value without `env` keeps the variable. Setting `env` to the secret's own name restores the name. A variable that Runtime sets in every sandbox cannot be a secret's `env`. Neither can one that decides what its programs load or trust. Examples are `PATH`, `LD_PRELOAD`, `SSL_CERT_FILE` and `HTTPS_PROXY`. A sandbox's `secrets` list, `--secret` on a create and `runtime secrets ls` name secrets by name, not by variable.

- A jobs secret (`--jobs`) belongs to the key that stored it. Your other keys cannot use it until you share it. Share it with `runtime secrets share NAME --agent <id>`, or with `--all`. You can always use it yourself. A secret you store on the website is available to every key. A job that binds a secret another key stored stops until that secret is shared.
- With `secrets` on a create, the sandbox names the secrets it may use. It gets only those. This is least privilege from the sandbox's side. An agent whose definition needs one key gets that key and nothing else. So a prompt injection cannot send your deploy key anywhere. That holds even to a host the deploy key allows. The list narrows each secret's `only`. It never widens it. A secret scoped away from the sandbox stays away, whatever the list says. `[]` means none. Leave the field out for every secret that reaches the sandbox, as before.

  ```bash no-run
  runtime sandboxes create --secret ANTHROPIC_API_KEY
  runtime sandboxes create --no-secrets          # no secret at all
  ```

  ```ts check
  import { Sandbox } from "withruntime";

  await using agent = await Sandbox.create({ secrets: ["ANTHROPIC_API_KEY"] });
  console.log(agent.info.secrets); // ["ANTHROPIC_API_KEY"]
  ```

  In the API and the `runtime_sandboxes_create` MCP tool, pass `"secrets": ["ANTHROPIC_API_KEY"]`. In Python, Go, Java and Ruby, use the create's `secrets` option. The list holds at most 64 names. A sandbox outside a secret's list has no environment variable for it. The proxy puts the value into none of its requests, even with the placeholder copied in by hand. You can list a name you have not stored yet. It takes effect once you store that secret. The list is fixed for the sandbox's life. An update cannot change it. A fork, or a copy of a snapshot, keeps its source's list. It may only narrow the list, with `secrets` on the fork. A wider list is refused. The response's `secrets` is the list as stored, read back. If a sandbox's list cannot be confirmed, the sandbox is stopped before anything runs in it. The create returns `secrets_unconfirmed` (500). Create it again. `getOrCreate` with `secrets` refuses a sandbox that already holds the name and may use more than it asks. It returns `secrets_mismatch`. Reading a sandbox shows its list as `secrets`, or `null` when it names none. Each server holds the list before the sandbox's first request.

- The value is sealed to the servers' key when you store it. No API, tool or command returns it. A sandbox never holds it, not in its environment, its memory or its disk. So a prompt injection or a stolen sandbox cannot leak it. A [real value](#a-secret-the-machine-needs-itself) is the one exception: the machine holds it.
- Plain HTTP never carries a secret. Request bodies are never rewritten. Requests to a secret's hosts go over HTTP/2 when your client and the host both offer it. Then a program's calls to one host share one connection. Otherwise they go over HTTP/1.1. WebSockets and gRPC work.
- To reach those hosts, the proxy opens the HTTPS connection itself. It checks the real server's certificate. Sandboxes already trust Runtime's certificate for those hosts. Python, Node, curl and git pick it up through `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS`. A program with its own pinned certificates needs the file `/usr/local/share/ca-certificates/runtime-egress.crt` added to them. Each organization has its own certificate authority, the same on every server. A sandbox that wakes, moves to another server or is forked keeps the same certificate, so programs that are already running keep working. A sandbox is never given or served another organization's certificate authority.
- Name only hosts you trust with the value. A host that echoes requests back would show it to the sandbox.
- A secret with header `Authorization` and format `AWS4-HMAC-SHA256 {value}` holds a bucket's `ACCESS_KEY_ID:SECRET_ACCESS_KEY`. It signs S3 requests instead. The proxy signs each request to its hosts again with the real key. The secret key is never sent at all. See [mounting your own bucket](./storage#mount-your-own-bucket).
- A sandbox that starts or wakes after you store a secret has it from its first request, however briefly it runs. Until 9 October 2026, a sandbox that started on a server not yet running another of your sandboxes could send the placeholder for up to five minutes. Replacing a secret keeps its placeholder. Running sandboxes use the new value within seconds. Deleting a secret erases the value from every server that held it. That includes servers no longer running your sandboxes. Closing your account erases them all. Deleting a secret does not revoke the key at its provider.
- A change returns `enforced: true` once two things are true. Every server running your sandboxes has confirmed it. Every server still holding an earlier version has confirmed it too. A sandbox that starts or wakes later gets the change before it runs. `false` means a server has not confirmed the change yet. Each server asks Runtime for changes every 15 seconds and takes them by itself. A server that lost what it held gets the change again the same way. A server that has not heard from Runtime for a minute stops putting any of your secrets' values into requests. The placeholder goes out instead. This continues until the server hears from Runtime again. So on a server cut off from Runtime, a deleted secret is sent for at most a minute. None of your sandboxes starts or wakes there until it hears again. A change reaches connections already open at their next request.
- A server keeps your secrets only while it runs your sandboxes. It keeps them 5 more minutes after the last one leaves, for a quick wake. Then it erases them.
- The [audit log](./teams) records every change to a secret or to your upstream proxy. Each entry names who made the change. Each change is also an [event](./observability#events) that a webhook can receive. Neither the log nor the event ever holds the value.
- Every secret has a `version`. It is 1 when the secret is stored, and one more each time the secret changes: its value, who gets it, its hosts or rules, or its variable. Pass the version you read as `expectedVersion` (`--expected-version` in the CLI). Then the write happens only if the secret is still at that version. `0` means the secret must not exist yet. Otherwise nothing is written, and the answer is 409 `version_conflict` with the current version in `details.version`. So two people or agents never overwrite each other unseen, and a new value never lands on a scope someone changed meanwhile. The website does this for you when you replace a value.
- An account can have up to 50 secrets for sandboxes (`--host` or `--exposed`). Each secret added on the way out is at most 8 KiB of visible ASCII, on one line, with up to 16 hosts. Secrets for jobs (`--jobs`) have their own limit of 1,000 per account ([jobs](./jobs#secrets-in-a-job)). The API is `PUT /v1/egress-secrets/{name}`, `GET /v1/egress-secrets`, `GET /v1/egress-secrets/{name}` and `DELETE /v1/egress-secrets/{name}`. The MCP tool is `runtime_secrets`, with `set`, `list`, `get` and `delete`.

### A secret the machine needs itself

**Some secrets are not HTTPS headers.** A database password, an SSH key, a signing key or a service account's JSON file must be in the machine itself. Store such a secret as its real value:

```bash no-run
runtime secrets set DB_PASSWORD --exposed --only-sandbox <sandbox id> < password.txt
runtime secrets set DEPLOY_KEY --exposed --only-app <app id> --env SSH_KEY --from-file deploy_key
runtime secrets get DEPLOY_KEY
```

In the API, the MCP tool and the SDKs, send `exposed: true`, no `hosts`, and `only` naming the sandboxes (`only.sandboxes`) or Apps (`only.apps`) that get it by id. Those machines get the value itself in its variable: `env`, or the secret's name.

- The trade-off: code in the machine can read the value, and could send it anywhere. A secret added on the way out cannot leak that way. So use a real value only for what the other kind cannot do.
- Only a key that may run commands in a machine can give it a real value. The value is your text in every command's environment there, so writing one is as strong as running a command there. The key must hold `exec` on each sandbox and App the secret reaches, the ones it keeps on a replacement too, and each must be its own, its agents', or any for a key that reaches the whole account. Otherwise the write is refused with 403 `forbidden`, naming the machine. On the website's Secrets page, you can give one to any machine you can open a terminal in.
- It goes only to sandboxes and Apps you name by id. Never to every sandbox, and never by label, because any key could make a sandbox or label one, and code in it could then read the value. A write without ids, or with labels, is refused with `invalid_request`. A replacement may leave `only` out: it keeps the sandboxes it has.
- Which machines get it changes only when you store it again, with its value. `runtime secrets scope` (`PUT /v1/egress-secrets/{name}/sandboxes`) is refused for it. So a key that never knew the value cannot point it at a sandbox of its own.
- A real value takes no `hosts`, `header`, `format`, `rules`, `githubApp`, `git` or `api`. Each is refused with `invalid_request`. `env` works as for every secret. Its hosts and rules cannot be narrowed, because it has none.
- Its variable is also never one that makes programs load or run code, as a second wall: a shell's start-up file or prompt (`BASH_ENV`, `ENV`, `PROMPT_COMMAND`), a loader's (`LD_*`), an interpreter's options or path (`NODE_OPTIONS`, `PYTHON*`, `PERL5OPT`, `RUBYOPT`, `JAVA_TOOL_OPTIONS`), git's (`GIT_*`), a package manager's or another tool's (`TAR_OPTIONS`, `PSQL_*`, `LESS*`, `DOTNET_*`), or one Runtime sets. Such a write is refused with `invalid_request` (field `env`). The value is your text in every command's environment, root's too, so in one of those it would run code in the machines it reaches. Put it in a variable of its own, such as `DATABASE_URL` or `PGPASSWORD`.
- The value is any text up to 64 KiB (65,536 bytes of UTF-8), several lines included, with no NUL character. An account's real values hold at most 64 KiB together.
- `exposed` is not kept. Give it on every write of such a secret. A write with neither `exposed` nor `hosts` is refused, and the error says so.
- The value is still sealed when you store it. It is opened only on the server that runs the machine, just before the machine gets it. The API and the website never see it after the write, and nothing returns it.
- The machine's own environment has the value: login shells, terminals and jobs. A command's or a deploy's `env` may hold the secret's placeholder, from `runtime secrets get`. It works even inside a longer value, such as `DATABASE_URL=postgres://app:rtsec_…@db/app`. The server that runs the machine puts the value in its place.
- When that server cannot give the value right now, a command in the machine returns 503 `secret_withheld`. Nothing ran. It is retryable: send it again after a few seconds. The SDKs do this for you.
- An SSH session carries a real value only when it is one line with no `"` or `\`. Otherwise the SSH login says which variables it left out. Use `runtime sandboxes exec` or a terminal for those.
- The value is in the machine's memory. So it can be in the machine's snapshots and forks, and in an App's saved server image. Treat those as holding the value.

### GitHub: an App's tokens, branch limits and API budgets

**Give agents GitHub access without a token that can do everything.** A secret can hold a GitHub App's private key. It can limit which branches a push may update. It can cap each sandbox's calls. Our servers enforce all of this on the way out. So a hijacked agent can't get past it.

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

const runtime = new Runtime();
await runtime.secrets.set("GITHUB_AGENTS", {
  value: process.env.GITHUB_APP_PRIVATE_KEY ?? "",
  hosts: ["github.com", "api.github.com"],
  githubApp: {
    id: 123456,
    installation: 7890123,
    repositories: ["my-app"],
    permissions: { contents: "write", pull_requests: "write" },
  },
  git: { push: ["refs/heads/task/{label.task}", "refs/heads/task/{label.task}--*"] },
  api: { callsPerHour: 400, writesPerHour: 120, keep: 1000, copies: true, fresh: 10 },
  only: { labels: [{ purpose: "agent" }] },
});
```

The same fields go to `PUT /v1/egress-secrets/{name}` and to every SDK. The SDK versions are `withruntime` 0.25.0 for JavaScript, 0.23.0 for Python, Go 0.12.0, and Java and Ruby 0.11.0. The field names are `github_app`, `git` and `api` in Python and Ruby. They are `GithubApp`, `Git` and `API` in Go. In Java, they go in the policy map. Reading the secret returns them, never the key. They only narrow what a secret does, so they are free.

- **`githubApp`**: the value is the App's private key (PEM). Our servers sign the App's token request. They use the installation token that GitHub returns. That token is narrowed to `repositories` and `permissions` when you name them. The token goes as `Authorization: Bearer` to the API. It goes as git's `x-access-token` to `git` over HTTPS. So `git clone`, `git push` and `gh` work with no credential in the sandbox. The key itself goes into no request. A token is made on first use, and again before it ends. While a token is being made, a request gets `503` with `Retry-After: 1`. If GitHub refuses the App a token, requests get `502` with GitHub's reason. This lasts until a try succeeds. Another try comes 30 seconds after a refusal. A GitHub App secret takes no `header` or `format`. For GitHub Enterprise Server, `api` is `https://<host>/api/v3`. That name must be a public name among the secret's hosts.
- **`git.push`**: the branches a push may update. Each is `refs/heads/` followed by a name. `*` is allowed only at the end. `{label.task}` stands for the sandbox's own `task` label. Any label key works. So each agent pushes only its own branch. A label goes right below a fixed first segment, as in `refs/heads/task/{label.task}`. It can never be `refs/heads/{label.task}`. After the label comes `/`, `--` or the end of the pattern. Each first segment takes one label key across all your secrets. So `task/` cannot take both `{label.task}` and `{label.name}`. This keeps two sandboxes from naming the same branch. A value is the branch of the first sandbox your account made with it. It stays that sandbox's after the sandbox is deleted. So a later sandbox with the same value never pushes to a finished agent's open pull request. Give the label when you create the sandbox. Once made, a sandbox's value of a label that a push pattern names cannot change. A sandbox pushes nothing that a label names in these cases. It lacks that label. The label's value holds `/`, `*` or `--`, or ends in `-`. An earlier sandbox had the same value. Or a key in a compartment made it. Any other ref, a tag or a delete is refused before anything reaches GitHub. `git push` prints why: `! [remote rejected] HEAD -> main (GITHUB_AGENTS pushes only …)`. `push: []` makes the secret fetch-only. The API can't get around these limits. With `git`, the secret makes an API write only when its `rules` name it. So a secret without rules writes nothing through the API. It makes a GraphQL mutation only when `api.graphql` lists it. Even then, it never writes a file, merges, makes or deletes a ref, renames or protects a branch, or makes a release. It also never makes a GraphQL mutation that does those things, such as `createCommitOnBranch`, `updateRef` or `mergePullRequest`. Each such request gets `403` with `x-runtime-egress: secret-git`. A `PATCH` of a branch the patterns allow still goes. A GitHub App secret with `git` must name its tokens' `permissions`. Those must exclude `admin`, `administration` and `secrets`. And `workflows`, `actions` and `environments` may be at most `read`.
- **`api.callsPerHour` and `api.writesPerHour`**: the most calls, and the most writes, each sandbox makes with the secret in an hour. A write is any method except GET, HEAD and OPTIONS, or a GraphQL mutation. Past either limit, the request gets `429` with `Retry-After`. `writesPerHour: 0` means read-only. A clone or push is not counted.
- **`api.keep`**: calls left for everyone else. No call goes while GitHub's last `x-ratelimit-remaining` for that bucket (core, graphql or search) is at or below `keep`. This holds until its reset. The request gets `429` with `Retry-After`. Your own services keep the last of the hour.
- **`api.copies` and `api.fresh`**: a GET over HTTP/2 is answered from this server's copy. This happens while GitHub answers `304` to its ETag. A `304` costs no GitHub calls. The copy is shared by every sandbox the secret reaches on that server. With `fresh` (1 to 300 seconds), a copy that young is answered without asking GitHub. This includes GraphQL queries. Past a sandbox's hour, its earlier reads are still answered from the copy. Each such answer carries `x-runtime-copy`, with the value `revalidated`, `fresh` or `unasked`. Answers with `no-store`, `set-cookie` or `Vary: *` are never kept. GraphQL answers holding `errors` are never kept either.
- **`api.graphql`**: `{ mutations: ["addComment", "createPullRequest"] }`. A query always goes. A mutation goes only when every mutation in the request is listed. Anything else is refused with `403`. `path` is where GraphQL is served. It is `/graphql` unless you say otherwise (`/api/graphql` on Enterprise Server).

### A secret your sandbox checks on requests it receives

A secret above only ever leaves a sandbox. Some secrets are checked by the sandbox's own server. One example is a shared key that another service sends in a header to its [preview](./networking#private-preview-links). For these, the program needs the value itself. Store it as a [real value](#a-secret-the-machine-needs-itself), or put it in the sandbox's `env`. The API, the CLI and the website never show its value. Make the key on your own machine. Give it to both sides from there. Then it is in no command line, file, log or chat:

```bash no-run
key=$(openssl rand -hex 32)
# The other side, here a Cloudflare Worker's secret, read from standard input.
printf %s "$key" | npx wrangler secret put APP_SHARED_KEY
# The sandbox: --env NAME alone sends that variable's value from your shell.
APP_SHARED_KEY=$key runtime sandboxes update "${id}" --env APP_SHARED_KEY
unset key
# A program already running keeps the value it started with: restart it.
```

- To rotate it, run the same lines again. Then restart the server in the sandbox. To avoid failed requests in between, have the server accept the old and the new key. For example, use `APP_SHARED_KEY` and `APP_SHARED_KEY_NEXT`. Do this until the other side has the new one. Then remove the old one with `--unset-env`.
- From withruntime 0.17.1, `--env NAME` without `=` works on `create`, `update`, `exec` and `run`. It works the same way as `docker run -e NAME`. A name not set in your shell is refused before anything is sent. Older versions take `--env NAME=value` only. From code, use `env` on create, or `sandbox.update({ env })`.
- Runtime's app in ChatGPT never takes a key's value. Set it from the CLI, the API or an agent connected with an API key. The preview stays private. The other service still needs its preview token as well.

## Your own proxy

**Paid accounts can send their sandboxes' connections through their own HTTP or HTTPS proxy.** The proxy's controls and logs then apply. The traffic leaves from the proxy's address.

```bash no-run
printf %s "Basic $(printf %s user:pass | base64)" | runtime secrets set PROXY_AUTH --host proxy.example.com
runtime networks upstream-proxy set http://proxy.example.com:3128 --secret PROXY_AUTH
```

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

const runtime = new Runtime();
await runtime.networks.upstreamProxy.set({
  url: "http://proxy.example.com:3128",
  secret: "PROXY_AUTH",
  hosts: ["*.internal.example.com"],
});
```

- Runtime's own rules apply first. A connection they refuse never reaches your proxy. Then the host reaches the destination with `CONNECT` through your proxy.
- `secret` names one of your secrets. Its value is sent as the whole `Proxy-Authorization` header, such as `Basic dXNlcjpwYXNz`. The secret's hosts must name the proxy's host. The secret cannot be deleted while the proxy uses it.
- `hosts` limits which destinations go through the proxy, such as `["*.internal.example.com"]`. The rest leave directly. Without it, every connection goes through the proxy.
- Runtime still puts in secrets before the bytes enter your proxy's tunnel. So your proxy sees encrypted traffic to the destination.
- If your proxy refuses the connection or cannot be reached, the connection fails with `upstream-proxy-failed`. It never falls back to a direct connection. This also holds on a server that has not yet been given your proxy. There, every connection fails the same way until the server has your proxy. UDP to a destination the proxy covers is refused.
- The proxy's own address must be public. Its port must be one a sandbox may reach. An `https://` proxy's certificate must verify against the public roots.
- `runtime networks upstream-proxy get` reads the setting, and `remove` removes it. In Python, it is `runtime.networks.upstream_proxy`. The API is `PUT`, `GET` and `DELETE /v1/networks/upstream-proxy`. The MCP tool is `runtime_networks_upstream_proxy`, with `set`, `get` and `remove`. The CLI command and the SDK methods were added in `withruntime` 0.7.0.

## Root inside the sandbox

The sandbox user has passwordless `sudo`. Root inside the guest controls the guest and nothing else. CPU, memory, disk, network rules, time limits and billing are enforced on the host.

## Lifetimes and storage

A stopped sandbox is not a separately promised backup. Export important results before you stop it.

## Browser-approved agent connections

**Connect an agent without copying a key.** Run the [CLI login](./cli), check the request code and agent name, then approve **Connect agent**.

- The browser uses your existing session when possible.
- An owner, admin or developer of the account can approve a new connection. A person who belongs to several accounts chooses which one on the same page.
- The request expires after 15 minutes. Do not approve unsolicited connection links.
- The page shows the name the requesting computer gives itself. It also shows the city and country where Runtime saw the request come from. The computer sets its own name. So treat the name as a hint, and match the code.

`runtime keys create` asks for an API key the same way. Use it on a CI runner or anywhere else with no browser:

- The page shows the key's name, its access, its daily limit, and that it lasts until revoked. An owner, admin or developer approves **Create key**.
- A billing member, an agent and an existing key cannot approve one.
- Whoever started the request receives the key. So approve only a request you started yourself.
- The key is sealed to that terminal. It is printed there once. Runtime keeps only a hash of it.
- If the command stops before the key arrives, the request is cancelled. A key that was approved but not yet received is revoked before anyone holds it.

Approval creates a separate agent identity and credential. It does not give the agent your browser session. The credential is encrypted for the initiating CLI when delivered. It is saved outside the project. On Unix, the credential directory is private to its user. The file has owner-only permissions. Software running as your user can read the file. So keep the machine and its backups secure.

Each connection can operate across the account and spend its prepaid balance. So connect only agents you trust. Separate identities let you see which agent did what. They also let you revoke one agent without the others. To cap what one agent may spend, set a daily limit on its row at [API keys](https://withruntime.com/account/keys) after it connects.

The browser reports success after the CLI receives and verifies the credential. Signing out of the browser leaves agent connections active. To revoke a single credential, use **API keys**. Or run `npx withruntime logout` on its machine. If the package is installed, run `runtime logout`. Revocation does not stop running resources. Inspect them, and stop any work you no longer want. Billing follows confirmed resource state, not sign-in state.

## The browser terminal

**The terminal on a sandbox's page acts as the agent that started the sandbox. It never acts as your browser session.** The website holds a key of that agent for you. The key is labelled "Runtime website terminals". The website discards the key's secret as soon as it makes the key. To open a terminal, the page asks the website for a ticket. The API trades the ticket for that key.

- A ticket opens one terminal in one sandbox, for the person who asked for it. It lasts 60 seconds. Its first use spends it, whatever the outcome.
- The page sends it as a WebSocket subprotocol, so it never appears in an address or an access log. Runtime keeps only its SHA-256 hash.
- The API accepts a ticket only from a page on withruntime.com. A ticket offered for another sandbox or from another site is spent and refused.
- When the ticket is used, Runtime checks again that you may still act as that agent. A changed role or a removed member is refused.
- Every call the terminal makes faces the same checks as that agent's API key. To close every browser terminal it holds, revoke "Runtime website terminals" on [API keys](https://withruntime.com/account/keys). The next terminal makes a new key.
- A person can open 30 terminals a minute. Each ticket is recorded with who asked, when, from which site and what became of it. Each record is kept 30 days.

## Single sign-on

**Sign in through your company's identity provider, and require it.** Owners connect Okta, Microsoft Entra ID, Google Workspace or any SAML or OIDC provider at [Single sign-on](https://withruntime.com/account/single-sign-on). It is free on every account. See [single sign-on](./single-sign-on).

- Your provider can sign in only addresses on the email domain you proved with a DNS record. Only one Runtime account can hold a proven domain.
- SAML assertions must be signed. They must be meant for Runtime. They must be within their validity window. They must answer a sign-in that Runtime started. Each is accepted once.
- **Require single sign-on** refuses every other kind of session for your members. Owners stay exempt, so a provider outage cannot lock you out. API keys are separate. Revoke or limit them on [API keys](https://withruntime.com/account/keys).
- SCIM directory sync removes a person as soon as your directory deactivates them. In the same step, it revokes every key they made.

## Identity tokens instead of stored keys

**Give code in a sandbox access to your cloud without a key in it.** A sandbox asks Runtime for a short-lived OIDC token. The token names the sandbox, its organization and its image. The sandbox then trades the token for credentials in your AWS or Google Cloud account. Or it presents the token to your own API. See [identity tokens](./identity-tokens).

- A sandbox can get a token only for itself. It can get one only while it runs. The token is for the audience it names. Tokens last 10 minutes. A sandbox can ask for up to an hour instead.
- The signing keys stay on Runtime's own servers. Only their public halves are published, at `https://withruntime.com/oidc/jwks`.
- Scope your trust policy to your organization's id (`org:<org-id>:*`), or to one image. Then no other Runtime customer's sandbox can assume your role.

## Before production traffic

- Run your real workload on the [free usage](./included-usage), including its package registries, cleanup and recovery.
- Give each agent or application its own key, with a daily limit where it helps.
- Keep outputs you need outside the sandbox.

Anyone can sign up at https://withruntime.com/sign-in.

## Domains, TCP ports, addresses and the tunnel

- **A custom domain is proved by DNS.** Only a TXT record holding the token made for your claim proves that a hostname is yours. A CNAME left pointing at Runtime proves nothing. So nobody can take over a name its owner forgot to clean up. Certificates are requested only for proved names.
- **A TCP port reaches one port of one sandbox.** A private network reaches only your own account's sandboxes. It never reaches another account's sandboxes, Runtime's servers or internal addresses. It never reaches the internet. The WireGuard gateway runs each account's network in its own user-space network stack. So nothing a peer sends reaches the server's own network stack. Rotating or removing a peer's key ends its connections.
- **Runtime's own relays inside a sandbox** (ports 10800, 10802 and 10853) are never reachable from outside. That covers a preview, a domain, a TCP port or the tunnel.
- **A dedicated outbound address is yours alone** while you hold it. After you release it, it rests 30 days before another account can have it.
- **Every connection is logged.** Each log entry has the sandbox, the account and the client's address. It has no contents. So a report can be traced and acted on. Runtime can turn off a domain, a port, a tunnel or everything in an account at once.

## Two-step sign-in

Customer sign-in uses Google, an email link, single sign-on or a passkey. A new account opened by email is confirmed with a six-digit code. The code is typed on the page where it was asked for. It must be entered within ten minutes and within three tries. A link in an email never opens a new account.

New accounts by email are not opened from a data-centre or VPN network. Use Google instead, or write to support. A home network opens at most two new accounts in an hour.

Every address that asks for an email gets the same answer, after the same checks. So the sign-in page does not reveal whether an address has an account.

An address is emailed at most five times an hour. One network can send at most 30 sign-in emails an hour to existing accounts. Requests from a network where the account has signed in within 90 days have their own allowance. So no one else can use up yours.

A code takes at most ten wrong tries a day per address. The tries are counted across every code and browser. After that, for a day, the address's codes stop working. Its email then carries only the one-click link.

A new code cancels the one before it. Codes are stored keyed with a secret. They are compared in constant time.

Directory reviewers use a separate, pre-provisioned demo identity with a password. That login accepts only the configured review identity. It grants no extra permissions. It follows the same second-step requirements.

Turn it on under **Settings → Two-step sign-in**, with a passkey, an authenticator app, or both. Keep the ten backup codes it gives you. From then on, every sign-in asks for the second step before the account opens. That holds whether you sign in with Google, an email link or single sign-on.

- **A passkey** lives in iCloud Keychain, Google Password Manager, 1Password, Windows Hello or a security key. You confirm it with your fingerprint, face or device PIN. It works only on withruntime.com, so a look-alike site cannot phish it. **Sign in with a passkey** on the sign-in page counts as both steps. It needs no email link and no code.
- **An authenticator app** (1Password, Google Authenticator, Authy or any app that shows six-digit codes): scan the QR code and enter the code it shows.

A backup code works once. Use one when your devices are lost. New backup codes replace the old ones whenever you ask. Removing a passkey or the app asks you to confirm it is you first. Removing the last one turns two-step sign-in off.

An owner can require two-step sign-in for everyone in the account. Members who have not set it up do so at their next sign-in. An owner turns on their own two-step sign-in before requiring it. The [audit log](./teams) records turning it on or off, each passkey added or removed, and the requirement. API keys and connected agents are not affected. They do not sign in through a browser. Five wrong codes in a row pause the step for fifteen minutes.

## Report a vulnerability

**Write to security@withruntime.com before you test anything. Write again with what you find.** Testing Runtime's own servers, network or other accounts without agreeing it with us first breaks the [acceptable use policy](/legal/acceptable-use). We may suspend the account.

A report helps most when it includes three things. Include the steps to reproduce the problem. Include the sandbox or request ids involved. Include the time, with its time zone. Please give us a reasonable time to fix a problem before you describe it in public. The same address is in [`/.well-known/security.txt`](https://withruntime.com/.well-known/security.txt).


---

<!-- https://withruntime.com/docs/single-sign-on -->

# Single sign-on and directory sync

People in your company sign in to Runtime with your identity provider, over
SAML or OIDC. Your directory adds them, gives them roles through groups, and
removes them the moment they leave, over SCIM. Both are free on every account.

Okta, Microsoft Entra ID and Google Workspace are supported from day one. Any
provider that speaks SAML 2.0 or OpenID Connect works the same way.

An owner sets it up at
[Single sign-on](https://withruntime.com/account/single-sign-on). It takes
three steps: create an app in your identity provider, prove you own your email
domain with a DNS record, and choose who joins and how.

## How it works

- **One connection per email domain.** A connection is your identity provider
  for one domain, such as `company.com`. An account can have up to 10.
- **Nobody signs in until the domain is proven.** You add a TXT record at
  `_runtime-verify.<your domain>`. Only one Runtime account can hold a proven
  domain, so another company cannot sign in people from yours.
- **Your provider speaks only for your domain.** Runtime accepts a sign-in only
  for an address exactly on the proven domain. An identity provider that
  asserts any other address is refused before an account is made or linked.
- **People join on first sign-in.** Anyone with an address on your domain who
  signs in through your provider joins your account with the default role you
  choose (developer unless you change it). Someone who already uses Runtime
  keeps their own account and joins yours as well.
- **Removal sticks.** Someone an owner or admin removed does not come back by
  signing in again. Invite them, or reactivate them in your directory.
- **The audit log records it all.** Connections made, changed and removed,
  domains verified, SSO required or not, people joining, SCIM tokens, and every
  change your directory makes.

## Set up SAML

On the Single sign-on page, choose **Connect your identity provider**. Pick
your provider, choose **SAML**, and enter your email domain. The page shows the
values to give your provider before you save anything.

### Okta

1. In Okta, go to **Applications > Create App Integration > SAML 2.0**.
2. **Single sign-on URL:** the page's single sign-on URL (ACS). Tick **Use this
   for Recipient URL and Destination URL**.
3. **Audience URI (SP Entity ID):** the page's audience URI.
4. **Name ID format:** EmailAddress. **Application username:** Email.
5. Add attribute statements `email` (user.email), `firstName`
   (user.firstName) and `lastName` (user.lastName).
6. Leave the assertion signed (Okta's default). Save, then copy the app's
   **Metadata URL** from its Sign On tab into Runtime and save.

### Microsoft Entra ID

1. In Entra, go to **Enterprise applications > New application > Create your
   own application** (non-gallery), then **Single sign-on > SAML**.
2. **Identifier (Entity ID):** the page's audience URI. **Reply URL (Assertion
   Consumer Service URL):** the page's single sign-on URL.
3. Keep the default claims. They include the email address, given name and
   surname Runtime reads. Signing option: **Sign SAML assertion** (the default).
4. Copy the **App Federation Metadata Url** into Runtime and save.
5. Assign the users or groups who should have access.

### Google Workspace

1. In the Admin console, go to **Apps > Web and mobile apps > Add app > Add
   custom SAML app**.
2. Copy Google's **SSO URL**, **Entity ID** and **Certificate** into Runtime,
   using **Enter by hand**. Or download the IdP metadata and paste it.
3. **ACS URL:** the page's single sign-on URL. **Entity ID:** the page's
   audience URI. **Name ID format:** EMAIL, **Name ID:** Basic Information >
   Primary email.
4. Optionally map First name to `firstName` and Last name to `lastName`.
5. Turn the app on for the people or groups who should have access.

## Set up OIDC

Choose **OIDC** instead, and give your provider the page's **sign-in redirect
URI**. Then enter the provider's issuer URL, client ID and client secret.
Runtime reads the provider's discovery document to find the rest.

| Provider         | Issuer URL                                           | Notes                                                             |
| ---------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| Okta             | `https://<your-company>.okta.com`                    | Create an **OIDC Web Application**; grant type Authorization Code |
| Microsoft Entra  | `https://login.microsoftonline.com/<tenant-id>/v2.0` | Register an app; add the **email** optional claim to the ID token |
| Google Workspace | `https://accounts.google.com`                        | Create an OAuth client (Web application), user type Internal      |

Runtime asks for the `openid`, `email` and `profile` scopes. It uses PKCE and
checks the ID token's signature, issuer, audience and expiry. The client
secret is stored for the sign-in service only, and it is never shown again. Leave
it empty when you change other settings to keep it.

## Prove your domain

Add the TXT record the page shows at your DNS provider:

| Type | Name                          | Value                    |
| ---- | ----------------------------- | ------------------------ |
| TXT  | `_runtime-verify.company.com` | `runtime-verify=<token>` |

Then choose **Check DNS**. A new record can take a few minutes to appear. Once
it is verified, the record can stay or go. The domain stays verified. If
another Runtime account already verified the domain, contact support.

## Sign in

- People choose **Use single sign-on (SSO)** on the sign-in page and enter their
  work email. Or they open the page's **initiate login URI**, which starts sign-in
  with your provider immediately.
- Runtime accepts only sign-ins it started. A SAML tile that posts straight
  to Runtime (IdP-initiated sign-in) is refused. For an app-list tile, point a
  bookmark app at the initiate login URI. OIDC apps take it as their initiate
  login URI directly.
- For SAML, Runtime checks the assertion's signature, audience, recipient and
  validity window. It takes each assertion once, and refuses a response with more
  than one assertion.

## Require single sign-on

Tick **Require single sign-on** on a connection once its domain is verified.

- Members other than owners can then use the account only through your
  provider. A Google or email-link session is sent back to sign in.
- **Owners are exempt,** so a broken identity provider cannot lock you out of
  your own account.
- **API keys are not affected.** A key is not a sign-in. Revoke keys, or remove
  the person, to stop them.
- A person who also belongs to another Runtime account still reaches that one
  with their usual sign-in.

## Directory sync (SCIM)

Your directory creates, updates and deactivates people in Runtime.

1. On the Single sign-on page, choose **Make a SCIM token**. Copy it. It is
   shown once.
2. In your provider, turn on provisioning with:
   - **Base URL:** `https://withruntime.com/scim/v2`
   - **Authentication:** HTTP header, bearer token: the SCIM token
   - **Unique identifier:** `userName` (the email address)
3. Push the groups whose roles you want Runtime to follow. Then choose on the
   Single sign-on page which role each group gives.

In **Okta**: the app's **Provisioning** tab, SCIM 2.0, with Push New Users,
Push Profile Updates, Push Groups and Deactivate Users. In **Entra ID**: the
enterprise app's **Provisioning**, mode Automatic, **Tenant URL** the base URL
and **Secret Token** the SCIM token. Google Workspace does not offer SCIM to
custom apps. With Google, people join on first sign-in.

What each change does:

- **A person deactivated or deleted** loses their membership immediately, and
  every API key they made is revoked in the same step. What they created stays
  with the account.
- **Reactivated**, they come back with the role their groups give. Their old
  keys stay revoked.
- **Groups decide roles.** A person gets the highest role any of their groups
  gives: admin, then developer, then billing. With no mapped group, they get
  the connection's default role. A group never makes anyone an owner. The
  directory never changes owners' roles.
- **Somebody your directory adds who has never signed in** joins at their first
  single sign-on, with their groups' role. If the directory has deactivated
  them first, they are refused.

A SCIM token acts with the authority of the owner who made it, and it stops if
they stop being an owner. An account has at most two live tokens, so you can
replace one without a gap. Runtime supports the filters and PATCH operations
Okta and Entra ID send: `eq` filters on `userName`, `externalId`, `emails` and
`displayName`, paging with `startIndex` and `count`, and `add`, `replace` and
`remove` on users and group members.

## From code

Single sign-on is changed by an owner on the website, never with a key. A key
made by an owner or admin can read it:

```bash no-run
npx withruntime sso
curl -H "Authorization: Bearer $RUNTIME_API_KEY" https://api.withruntime.com/v1/sso
```

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

const runtime = new Runtime();
const { connections, scim } = await runtime.sso.get();
console.log(
  connections.map((c) => `${c.domain} ${c.domainVerifiedAt ? "verified" : "pending"}`),
  scim.users,
);
```

Python: `runtime.sso.get()`, the same fields. MCP: the `runtime_account`
tool's `sso` action.

## Troubleshooting

- **"Provider domain has not been verified":** check DNS on the Single sign-on
  page first.
- **"signed you in with an address outside your company's verified domain":**
  the address your provider sent is not on the connection's domain. Check the
  NameID or email attribute (SAML) or the `email` claim (OIDC).
- **"Invalid SAML response":** the certificate in Runtime does not match the
  one your provider signs with, or the assertion is not signed. Upload the
  current metadata again.
- **Audience or recipient mismatch:** the audience URI or single sign-on URL in
  your provider is not the one the page shows for this connection.


---

<!-- https://withruntime.com/docs/speed -->

# Speed

Runtime times every operation of every product from outside, as a customer:
through the public API, with a production key, from a fixed place in eastern
North America, every one to five minutes. Each result records the API's own
time for the request (its `Server-Timing` header) and the time the client saw,
at p50, p95 and p99, with the sample and failure counts.

This page lists an operation once its own time is within 2× of its floor: the
least time the work it must do can take on today's hardware. An operation that
is not yet that close is not listed, and no older figure stands in for it. The
figures this page showed from September 2026 were taken down on 27 October
2026, because they were no longer what customers see.

## Run the measurement yourself

This script times sequential sandbox starts from your own machine, with 2 vCPU,
4 GiB memory and 4 GiB disk. The first command is `python3 -c pass`. The script
opens the API connection before timing. It disables automatic request and
capacity retries. It confirms each sandbox is stopped before the next.

1. Save the script as `bench.mts` in an empty folder.
2. Run `npm install withruntime` and sign in with `npx withruntime login`, or set
   `RUNTIME_API_KEY`.
3. Run `OUT=after.json node bench.mts` (Node 22.18 or later), or use
   `OUT=after.json bun bench.mts`.

`RUNS` defaults to 20 and accepts 1–100. It runs without credit's hours first,
then on the account's credit if it has some. Ctrl-C prevents further starts. It
lets the current attempt finish its cleanup. A failed or uncertain create stops
the benchmark after cleanup. Its five-minute time limit is a backstop. If
cleanup fails, the script prints the attempt labels for follow-up, and the
command fails.

For a before and after comparison, run the identical script on the same client,
connection and shape. Save separate output files. Record the SDK version and
when each run happened.

```ts check
// bench.mts
import { randomUUID } from "node:crypto";
import { writeFileSync } from "node:fs";
import { Runtime, VERSION, type Sandbox } from "withruntime";

const count = Number(process.env.RUNS ?? 20);
if (!Number.isInteger(count) || count < 1 || count > 100)
  throw new Error("RUNS must be an integer from 1 to 100");
const runtime = new Runtime({ maxRetries: 0, waitForCapacityMs: 0, timeoutMs: 60_000 });
const run = randomUUID();
const at = new Date().toISOString();
const shape = {
  vcpu: 2,
  memoryMiB: 4096,
  diskMiB: 4096,
  timeoutSeconds: 300,
  autoWake: false,
  idlePauseSeconds: 0,
};
type Sample = {
  index: number;
  ok: boolean;
  cleanup: boolean;
  id?: string;
  createMs?: number;
  firstExecMs?: number;
  totalMs?: number;
  error?: string;
};
const samples: Sample[] = [];
let interrupted = false;
process.once("SIGINT", () => {
  interrupted = true;
});
process.once("SIGTERM", () => {
  interrupted = true;
});
const message = (error: unknown) => (error instanceof Error ? error.message : "Request failed");

async function cleanup(known: Sandbox | undefined, labels: Record<string, string>) {
  const failures: string[] = [];
  const stop = async (sandbox: Sandbox) => {
    try {
      await sandbox.stop();
      await sandbox.waitFor("stopped");
    } catch (error) {
      failures.push(`${sandbox.id}: ${message(error)}`);
    }
  };
  if (known) await stop(known); // A discovery error must not skip the known guest.
  try {
    for (const sandbox of (await runtime.sandboxes.list({ labels })).data) await stop(sandbox);
    if ((await runtime.sandboxes.list({ labels })).data.length)
      failures.push("An attempt sandbox still exists");
  } catch (error) {
    failures.push(message(error));
  }
  if (failures.length) throw new Error(JSON.stringify({ labels, failures }));
}

try {
  await runtime.me(); // Establish the API connection outside the measured interval.
  for (let index = 1; index <= count && !interrupted; index++) {
    const labels = { benchmark: "startup-python", run, index: String(index) };
    const input = { ...shape, labels, name: `startup-${run}-${index}` };
    const options = { idempotencyKey: `startup-${run}-${index}` };
    const sample: Sample = { index, ok: false, cleanup: false };
    let sandbox: Sandbox | undefined;
    let createUncertain = false;
    const began = performance.now();
    try {
      sandbox = await runtime.sandboxes.create(input, options);
      sample.id = sandbox.id;
      sample.createMs = Math.round(performance.now() - began);
      if (interrupted) throw new Error("Interrupted; cleaning up");
      if (sandbox.state !== "running") throw new Error("Create did not reach running");
      const execAt = performance.now();
      await sandbox.exec(["python3", "-c", "pass"], { check: true });
      sample.firstExecMs = Math.round(performance.now() - execAt);
      sample.totalMs = Math.round(performance.now() - began);
      sample.ok = true;
    } catch (error) {
      sample.error = message(error);
      // Recover a lost create reply with the SAME request key, never a new allocation key.
      if (!sandbox) {
        try {
          sandbox = await runtime.sandboxes.create(input, options);
        } catch {
          createUncertain = true;
          console.error("Create remains uncertain:", options.idempotencyKey, labels);
        }
      }
    } finally {
      try {
        await cleanup(sandbox, labels);
        sample.cleanup = !createUncertain;
      } catch (error) {
        sample.error = message(error);
      }
      samples.push(sample);
      console.log(JSON.stringify(sample));
    }
    if (!sample.ok || !sample.cleanup) throw new Error(sample.error ?? "Attempt failed");
  }
} catch (error) {
  console.error(message(error));
  process.exitCode = 1;
}
if (interrupted) process.exitCode = 130;

const stats = (key: "createMs" | "firstExecMs" | "totalMs") => {
  const values = samples
    .filter((s) => s.ok)
    .map((s) => s[key]!)
    .sort((a, b) => a - b);
  const n = values.length;
  return {
    n,
    median: n ? (values[Math.floor((n - 1) / 2)]! + values[Math.ceil((n - 1) / 2)]!) / 2 : null,
    p95: n ? values[Math.ceil(n * 0.95) - 1]! : null,
  };
};
const result = {
  at,
  run,
  sdk: VERSION,
  engine: process.versions.bun ?? process.version,
  api: runtime.transport.baseUrl,
  shape,
  requested: count,
  attempts: samples.length,
  errors: samples.filter((s) => !s.ok).length,
  cleanupFailures: samples.filter((s) => !s.cleanup).length,
  interrupted,
  createMs: stats("createMs"),
  firstExecMs: stats("firstExecMs"),
  totalMs: stats("totalMs"),
  samples,
};
console.log(JSON.stringify(result, null, 2));
if (process.env.OUT) writeFileSync(process.env.OUT, JSON.stringify(result, null, 2) + "\n");
```


---

<!-- https://withruntime.com/docs/start -->

# Get started with Runtime Cloud

Runtime Cloud gives your agents Linux sandboxes, billed on the CPU they use. It connects them with one browser approval.

Each sandbox is a Firecracker microVM with its own kernel, disk and toolchain.
One API, one CLI, one MCP server and SDKs for JavaScript, Python, Go, Ruby and Java cover
every Runtime product. New accounts get [100 free hours of a 1 GB machine every month](./included-usage), no card.

- **100 free hours of a 1 GB machine every month, no card:** enough to run your real workload before you pay.
- **Pay for the CPU you use:** $0.025 per active vCPU-hour, measured, and
  $0.0075 per reserved GiB-hour of memory ([pricing](./pricing)).
- **Idle time costs almost nothing:** a sandbox pauses itself after
  300 seconds with nothing happening in it. It keeps its memory and processes.
- **Pause keeps memory.** A fork copies a running sandbox with its memory
  and processes.
- **An uptime promise:** paid accounts are promised 99% API
  uptime a month. 10% of a short month's charges comes back
  automatically ([Uptime Promise](/legal/sla)). The [status page](/status)
  publishes the record used to measure it.
- **Secrets the sandbox never sees,** and single sign-on, SCIM and roles free
  for every team.
- **Built in:** a desktop, a code interpreter, custom images, volumes, and
  preview URLs that are private by default.
- **Your own data:** mount your S3, R2 or Google Cloud Storage bucket as a
  folder ([storage](./storage#mount-your-own-bucket)).
- **Connected to the rest of your world:** your own domain with HTTPS, public
  TCP ports and a WireGuard private network once the account has a kept
  top-up. A dedicated outbound address comes once it has credit
  ([networking](./networking)). [Identity tokens](./identity-tokens) reach AWS or Google Cloud with no
  stored key.
- **See what runs:** each sandbox's CPU and memory over time, signed webhooks
  and OpenTelemetry export ([observability](./observability)).

## Give your agent one instruction

Paste this into your coding agent:

> Move this project to Runtime Cloud: read https://withruntime.com/llms.txt and
> follow it.

The agent connects. If the project uses another sandbox provider, the agent moves
every call to Runtime and keeps going until your real job runs there. It
reports what passed, what you save each month and what is left for you to go
live. You approve one link in your browser. There is nothing to copy.

## Run your first sandbox

**In the browser:** [sign in](https://withruntime.com/sign-in) and press
**Start a sandbox** on Home. It opens with a shell running in the page, on your
free hours. It pauses itself after 300 seconds with nothing happening in it.

**From your code:** Home offers a prompt for your coding agent. The prompt does
the whole setup. Or, by hand, make your first key in one click. The key is shown
once. The page then shows the install and a first sandbox in Python or JavaScript.
If you signed up from a page comparing Runtime with E2B, Daytona, Vercel Sandbox or Blaxel, Home
opens on that switch instead. By hand, the switch is the key, the install and the
one import that changes.

**Run a file, with Node 22.12 or later:**

```bash
printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
npx withruntime sandboxes run -- python3 - < invoice.py
```

The first time, it connects this machine:

1. Your browser opens a Runtime page, or the command prints a link and a code.
2. You sign in with Google or by email (type the six-digit code the email
   gives you, or click its link if you already have an account), check the
   code and choose **Connect agent**.
3. A fresh sandbox runs the command, prints the invoice total, 750, and is
   deleted.

Exit code zero means the command succeeded. Nothing is left behind to pay for.
`npx withruntime sandboxes ls --json` no longer lists the test sandbox. An
older CLI only stopped it. If it is still listed, delete it with
`npx withruntime sandboxes rm <id>`. Later commands reuse the connection.

An agent running it shows you the link and code. If you approve after the
command stopped waiting (50 seconds when no one is at a terminal), the agent
runs it again and it finishes, with no new link.

For several commands in one sandbox, this shell block deletes it on exit:

```bash
(
  id=$(npx withruntime sandboxes create) || exit
  trap 'npx withruntime sandboxes rm "${id}"' EXIT
  npx withruntime sandboxes exec "${id}" -- python3 -c 'print(sum([125, 250, 375]))'
)
```

Installed with `npm install --global withruntime`, the command is `runtime`:
`runtime sandboxes run -- ls`, `runtime sandboxes create`. See
[the CLI](./cli).

## Give an agent Runtime's tools

Add Runtime's MCP server to your agent with one command:

```bash no-run
claude mcp add --scope user runtime -- npx -y withruntime mcp   # Claude Code
codex mcp add runtime -- npx -y withruntime mcp                 # Codex
```

Cursor: add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{ "mcpServers": { "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] } } }
```

If this machine is not connected yet, the agent sees one tool,
`runtime_connect`. It gives the agent a link for you to approve. Then every Runtime
tool appears. See [MCP](./mcp) for other clients and the remote endpoint.

## From code

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

const sbx = await Sandbox.create();
try {
  await sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
  const result = await sbx.exec("python3 /workspace/invoice.py", { check: true });
  console.log(result.stdout);
} finally {
  await sbx.delete();
}
```

```python
from withruntime import Sandbox

sbx = Sandbox.create()
try:
    sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n")
    print(sbx.exec("python3 /workspace/invoice.py", check=True).stdout)
finally:
    sbx.delete()
```

- Install with `npm install withruntime` or `pip install withruntime`.
- The SDKs use `RUNTIME_API_KEY` when it is set. Otherwise they use the key this
  machine saved when it connected. After the one line above, they need no
  setup.
- On a server, create a key at https://withruntime.com/account/keys and give it
  as `RUNTIME_API_KEY` from your secret manager.
- `create()` needs no arguments. It waits until the sandbox is ready, and
  raises `start_failed` if it stops first.
- The examples check the command's result, and delete the sandbox even after
  an error. A stopped sandbox keeps its disk, which is billed until it is deleted.
  Export anything you need before deleting.

## Connect once in your browser

**One approval gives this machine its own key.** It is encrypted for this
machine alone and saved outside your project. The CLI receives and saves its
own credential automatically. You do not copy an API key.

- Each connection can use everything the account can, including its prepaid
  credit. Approve only connections you started.
- Browser sign-out does not revoke one. `npx withruntime logout` or the API
  keys page does. See [security](./security).
- On a machine with no browser, `npx withruntime login --no-browser` prints the
  link to open on another device.
- To use a key you already have, `npx withruntime login --with-key` reads it
  from standard input, never from the command line.
- An agent with no person to approve can open its own account and pay in
  USDC instead: `npx withruntime billing topup 20 --new-account --accept-terms --wait`.
  No free trial on that path. The key comes once the payment lands. See
  [pay with stablecoins](./pricing#pay-with-stablecoins).

There is nothing to choose between free usage and credit. The free usage is spent first, then prepaid credit. `funding` in a request is ignored.
Once the account holds credit, its sandboxes have paid limits.

## Switch from another provider

**Most sandbox code moves over call for call.** The [switch guide](./migrate)
maps E2B, Daytona, Vercel, Modal, Cloudflare, Fly and Blaxel calls to
Runtime's. It shows how to work out your monthly saving from measured usage.
Code written for E2B, Daytona, Vercel Sandbox, Blaxel or Modal Sandboxes runs
after you change one import to `withruntime/e2b`, `withruntime/daytona`,
`withruntime/vercel`, `withruntime/blaxel` or `withruntime/modal`. Morph's
TypeScript client moves to `withruntime/morph`. A Worker written for Cloudflare's
Sandbox SDK moves to `withruntime/cloudflare`, with its `containers` block deleted
and a `RUNTIME_API_KEY` secret. Code that calls Fly's Machines API works after you
point it at `npx withruntime fly-api` (`withruntime/fly`).
`npx withruntime compare --from <provider>` prints what you save. Credit you add within 30 days of signing up is matched, up to $1,000 in total.

## If the first run fails

Keep the error code, request ID and sandbox ID. A lost response is not proof
that nothing ran. Inspect the original resource before trying another create.

| Error                                                 | What to do                                                                |
| ----------------------------------------------------- | ------------------------------------------------------------------------- |
| `connection_pending`                                  | Approve the printed request, then rerun the same command                  |
| `no_credit_running_limit` or `included_usage_used_up` | Check your free usage; once the account holds credit, it runs on that     |
| `start_failed`                                        | Read the sandbox's state and `stopReason`; a stopped sandbox is not ready |

See [troubleshooting](./troubleshooting) for safe retries and cleanup.

## What you can do next

| You want to                                                        | Read                                                                                                             |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Run commands, stream output, start servers                         | [JavaScript SDK](./javascript), [Python SDK](./python), [Go SDK](./go), [Ruby SDK](./ruby) or [Java SDK](./java) |
| Drive sandboxes from a terminal or a script                        | [CLI](./cli)                                                                                                     |
| Give an agent Runtime tools                                        | [MCP](./mcp)                                                                                                     |
| Call the API from any language                                     | [API reference](./api)                                                                                           |
| Know what is installed and what the network allows                 | [The sandbox environment](./sandbox-environment)                                                                 |
| Keep data on volumes, or mount your own bucket                     | [Storage and backups](./storage)                                                                                 |
| Serve on your own domain, open a TCP port or reach your network    | [Networking](./networking)                                                                                       |
| Watch CPU and memory, get webhooks, export to OpenTelemetry        | [Observability](./observability)                                                                                 |
| Plug into the OpenAI Agents SDK, Vercel AI SDK, LangChain and more | [Frameworks](./frameworks)                                                                                       |
| Switch from E2B, Daytona, Vercel, Modal, Cloudflare, Fly or Blaxel | [Switch guide](./migrate)                                                                                        |
| Tell us what to build next, or get help                            | [Feedback and support](./feedback-and-support)                                                                   |

Keep important results outside the sandbox. A sandbox is not a backup.


---

<!-- https://withruntime.com/docs/storage -->

# Storage and backups

Checked off-server copies of snapshots and volume backups survive the loss of
the server they were made on. You can mount your own buckets inside a sandbox,
and the sandbox never holds their keys. A snapshot starts copying off its server
once its final compressed form is ready. `backedUp: true` confirms that the copy
is ready. A volume is backed up off its server every day, and whenever you ask.
It can be restored onto any server in its region. Every copy is encrypted with a
key that belongs to your organization alone.

## What is kept where

| What                  | Where it runs          | Copy off the server                                        |
| --------------------- | ---------------------- | ---------------------------------------------------------- |
| A sandbox's own disk  | Its server             | None. Keep what you cannot rebuild on a volume             |
| A volume              | One server, fixed size | A backup every day, and on request, kept 7 days unless set |
| A snapshot            | Its source's server    | Copied once after compression, and kept as long as it is   |
| A fork's own snapshot | Its source's server    | None: it is deleted when the fork ends                     |

`backedUp` on a volume or a snapshot is `true` once its copy has been written
off the server, read back and checked. Until then it is `false`.

In your account, [Volumes](https://withruntime.com/account/volumes) lists each
volume with how full it is, the sandbox it is attached to and its backups. It
lets you create a volume, back it up now, change its backup policy, restore a
backup as a new volume, or delete a volume or backup. You can attach a volume
when you create a new sandbox. A [scheduled job](./jobs#keep-data-between-runs)
attaches one to each of its runs. A stop keeps a sandbox's disk, so its volume
stays attached until that sandbox is deleted. Spending and deletion ask for
confirmation using the console agent's existing permissions.

## Attaching a volume

A create attaches up to four volumes, each at a path such as `/data`, in one of
two modes:

- **`"rw"`** (the default): read-write, attached to one sandbox at a time.
- **`"snapshot"`**: a read-only copy of the volume as it is when the sandbox
  starts. Any number of sandboxes can attach it at the same time. The name refers
  to a frozen copy of the volume's files. It is not a sandbox
  [snapshot](./javascript#snapshots-and-forks), and it creates none.

## Volume backups

A backup is a point-in-time copy of a volume, taken while sandboxes may be
writing to it. It holds everything the volume held at that moment, as a disk does
after a power cut. Data that a program had not yet written to the disk is not in
it. Stop or flush writes first when you need a clean point.

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

const runtime = new Runtime();
const volume = await runtime.volumes.create({ sizeMiB: 10_240, name: "data" });
const backup = await runtime.volumes.backup(volume.id, { retentionDays: 30 });
const restored = await runtime.volumes.restore(backup.id, { name: "data-restored" });
for await (const each of await runtime.volumes.backups({ volumeId: volume.id }))
  console.log(each.id);
await runtime.volumes.setBackupPolicy(volume.id, { daily: true, retentionDays: 14 });
await runtime.volumes.setBackupPolicy(volume.id, {
  schedule: { everyMinutes: 60 },
  keep: { hourly: 24, daily: 7, weekly: 4 },
});
```

```python check
from withruntime import Runtime

runtime = Runtime()
volume = runtime.volumes.create(10_240, name="data")
backup = runtime.volumes.backup(volume["id"], retention_days=30)
restored = runtime.volumes.restore(backup["id"], name="data-restored")
runtime.volumes.set_backup_policy(volume["id"], daily=True, retention_days=14)
runtime.volumes.set_backup_policy(volume["id"], every_minutes=60, keep={"hourly": 24, "daily": 7, "weekly": 4})
```

```bash no-run
runtime volumes backup "${vol}" --retention-days 30   # prints the backup id
runtime volumes backups "${vol}"                      # newest first
runtime volumes restore "${backup}" --name data-restored
runtime volumes backup-policy "${vol}" --daily on --retention-days 14
runtime volumes backup-policy "${vol}" --every 60 --keep hourly=24,daily=7,weekly=4
runtime volumes backup-policy "${vol}" --no-schedule    # back to daily
runtime volumes backup-rm "${backup}"
```

- **Daily:** every volume is backed up once a day, starting an hour after it is
  created. Turn this off with `daily: false`. Each daily backup is kept for the
  volume's `retentionDays`. The default is 7. You can set 1 to 365.
- **Your own schedule:** `schedule: { everyMinutes: n }` (15 or more, counted
  from 1970-01-01 UTC) or `schedule: { cron: "30 2 * * 1-5" }` (five fields in
  UTC) backs the volume up on that schedule instead of daily. `keep` says which
  of those backups stay. It keeps the `last` N backups. It also keeps the newest
  backup in each of the newest N `hourly`, `daily`, `weekly` (from Monday),
  `monthly` and `yearly` periods. Each count is 0 to 1,000. A schedule with no
  `keep` keeps one backup a day for `retentionDays`. A backup waits for the one
  before it to be copied, so backups never stack up behind a slow copy.
  `schedule: null` goes back to daily. Its backups are then kept `retentionDays`
  from that moment. While the account has no credit, each backup is kept at most
  seven days, whatever the counts.
- **On request:** `backup` makes one now and waits up to a minute for it to be
  ready. A backup can be kept for 1 to 365 days.
- **Without credit**, a backup is kept at most seven days, whatever you ask
  for, as snapshots and paused sandboxes are.
- **The newest ready backup is kept** past its retention for as long as the
  volume exists. A run of failed backups never leaves a volume with none. It is
  removed once a newer one is ready, when you delete it, or at its retention's
  end once the volume is deleted. While kept, it is billed like any other backup.
- **Restoring:** a restore is a new volume, the size of the backup, in the same
  region, on whichever server has room. It is ready once every byte has been
  downloaded and checked. `restoredFrom` names the backup. The original volume
  is not changed.
- **Proving a backup restores:** a `ready` backup has had every piece it stores
  found in the object store, at the size written. Pieces it shares with earlier
  backups were found there within the past week. Only a restore opens every piece
  and checks its content. To prove the data, restore the backup, check it, then
  delete the restored volume. A restored volume is charged by the GiB-hour only
  while it exists. The restored volume counts toward your volume limit like any
  other: 5 until the account has credit, and 10,000 after that
  ([limits](./limits)).
- **Incremental:** only what changed since an earlier backup of the same
  volume is stored again, and empty space is not stored at all.
- **Deleting a volume** keeps its backups until each one's retention ends, so
  you can still restore it. Deleting a backup removes its copy.
- **If a volume's server is lost,** the volume is gone with it, and its error
  names the newest backup to restore it from.
- **Stopping a sandbox** has it write out what it wrote to its volumes first. A
  stop that waits returns once its volumes are free to attach again. A sandbox
  whose time limit or credit runs out does the same. Its programs are frozen just
  before its end. What they wrote to its volumes, and to a persistent sandbox's
  own disk, is written out after that at no charge.
- **Pausing a sandbox with volumes** does not copy the paused sandbox off its
  server. The nightly backup keeps it, and each volume has its own backups above.

## Snapshots survive their server

A memory snapshot can be `ready`, and started from, while
`compressionPending: true`. It is still being compressed in the background. It
is charged on its final compressed size from the time it was ready.

Its encrypted off-server copy is queued only after compression finishes. While
compression is pending, `meteredBytes` is zero, `backedUp` is false and
`durability.state` is `none`. `backedUp: true` means the off-server copy has
been checked. `durability.state` says where that stands:

| `durability.state` | Meaning                                                                      |
| ------------------ | ---------------------------------------------------------------------------- |
| `pending`          | Being copied off the server                                                  |
| `durable`          | Copied, read back and checked; `backedUp` is `true`                          |
| `restoring`        | Its server was lost, and it is being restored onto another from its copy     |
| `failed`           | It could not be copied; `error` says why                                     |
| `none`             | A temporary fork snapshot, or capture waiting for compression before copying |

If a snapshot's server is lost, the snapshot is restored from its copy onto a
server in its region with a compatible processor. Memory snapshots resume the
saved machine there. Disk snapshots boot fresh from the saved root filesystem.
While that happens, a create or fork from it returns `snapshot_restoring` (503).
Try again in a few minutes. If no such server has room yet, the snapshot stays
copied off the server, and its `error` says it is waiting. It is restored as soon
as one does. A snapshot whose server was lost before it was copied is deleted.
Its `error` says why. It is not charged after the server's last sign of life.

## Randomness in copies

A fork, or a sandbox created from a memory snapshot, resumes every program
that was running when the copy was taken. It also copies each program's
random-number state. Linux itself gets fresh randomness in every copy. But a
program that keeps its own generator in memory gives the same "random" bytes
in every copy until it reseeds. Two copies can then make the same key, token,
session ID or UUID.

Make keys, tokens and IDs after the copy, from the system's randomness:
`/dev/urandom`, `getrandom`, Python's `os.urandom` or `secrets`, Go's
`crypto/rand`, or a program started after the copy. A pause and wake makes no
copy, and a disk snapshot boots its programs fresh, so neither is affected.

Measured on 6 October 2026 in a long-running process, three copies of one
memory snapshot:

| Fresh in every copy                                     | Same in every copy until the program restarts                                 |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `/dev/urandom` and `getrandom`                          | Node.js: `crypto.randomBytes`, `getRandomValues`, `randomUUID`, new key pairs |
| Python `os.urandom` and `secrets`                       | Node.js and Bun: the random bytes in a new TLS connection                     |
| Go `crypto/rand`                                        | Bun: `crypto.randomBytes`, `getRandomValues`, `randomUUID`, new key pairs     |
| Java `new SecureRandom()` (NativePRNG, Linux's default) | Chromium pages: `crypto.getRandomValues` and `crypto.randomUUID`              |
| Rust `getrandom`                                        | Python `ssl.RAND_bytes`                                                       |
| Chromium: the random bytes in a new TLS connection      | Java `SecureRandom.getInstance("DRBG")` and `"SHA1PRNG"`                      |
|                                                         | Rust `rand::thread_rng()`                                                     |

Generators that are not for secrets (`Math.random`, Python's `random`, Go's
`math/rand`) also repeat. If a program must keep running across the copy,
restart it, or reseed its generator from `/dev/urandom` after the copy.

## Updating the default image

An existing paused sandbox or snapshot keeps the filesystem saved with its
memory. Updating Runtime's default image does not replace those files. A wake
or fork keeps that identity when its trusted saved state matches, and the kernel
and machine remain compatible. New sandboxes use the current default. An
incompatible or unverifiable saved image is refused. It is never restarted
silently without its memory.

## Mount your own bucket

A bucket in Amazon S3, Cloudflare R2 or Google Cloud Storage, or any
S3-compatible store, appears as a directory in a running sandbox. **The sandbox
never holds the bucket's key.** You store the key once as a secret. The sandbox's
mount client signs its requests with a placeholder. Runtime's egress proxy signs
each request again with the real key as it leaves for the bucket's endpoint.

```bash no-run
printf %s "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" | runtime secrets set DATA_BUCKET \
  --host s3.eu-west-1.amazonaws.com --header Authorization --format 'AWS4-HMAC-SHA256 {value}'
runtime sandboxes mount "${id}" s3://my-data/datasets /data --secret DATA_BUCKET --region eu-west-1
runtime sandboxes mounts "${id}"
runtime sandboxes unmount "${id}" /data
```

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.mounts.add({
  provider: "s3",
  bucket: "my-data",
  region: "eu-west-1",
  path: "/data",
  secret: "DATA_BUCKET",
});
await sbx.exec("ls /data");
```

- **The secret:** its value is `ACCESS_KEY_ID:SECRET_ACCESS_KEY` (or
  `...:SESSION_TOKEN` for temporary keys), its header `Authorization`, its
  format exactly `AWS4-HMAC-SHA256 {value}`, and its hosts the bucket's
  endpoint: `s3.<region>.amazonaws.com` for S3,
  `<account id>.r2.cloudflarestorage.com` for R2, `storage.googleapis.com` for
  Google Cloud Storage (with an HMAC key), or your store's own host.
- **Providers:** `s3` with `region` (us-east-1 when omitted) or `endpoint` for
  another S3-compatible store, `r2` with `accountId`, `gcs`. A `prefix` mounts
  only the keys under it, and `readOnly` mounts it read-only. A public bucket
  needs no secret.
- **What it is:** rclone, installed in the sandbox the first time you mount,
  which takes a few seconds longer. Files are written to the bucket when they are
  closed. Two sandboxes can mount the same bucket. When two of them write a file,
  the last one closed wins.
- **How long:** a mount lasts through a pause and a wake, and ends when the
  sandbox stops; mount it again after a restart.
- **Network:** the bucket is reached over HTTPS through the sandbox's own
  network rules, like any other host.

## Encryption and deletion

- Each organization has its own data key. Everything a copy puts in the object
  store is encrypted with it, and the names of the stored pieces reveal nothing
  about their content. Nothing is shared or compared across organizations.
- Every piece is checked when it is read back: a copy that does not match what
  was written is refused rather than restored.
- When an organization is deleted, its key is destroyed first. That makes every
  copy it had unreadable immediately. Then the copies themselves are deleted.
- Apart from these copies, each server's own nightly backup is encrypted with
  that server's key, not your organization's key. It is kept 30 days. Its pieces
  leave the object store within 44, so what a closed organization had on that
  server is gone from these backups by then.

## Limits and price

- Up to 200 volume backups per organization at a time.
- Backups and restores run at a lower priority than your sandboxes. A backup is
  `pending` until it is copied and checked. A restored volume is `creating`
  until every byte is downloaded and checked.
- A backup's copy goes ahead of Runtime's own copies on its volume's server.
  It never waits behind one. `copyStartedAt` says when its copy off that server
  began. While it is `null`, the backup waits only for other backups there.
  (A backup whose copy began before this field existed shows `null` too.)
- A backup whose copy has not begun 15 minutes after you asked for it
  (`createdAt`) fails with `errorCode` `backup_stalled`. It does not stay
  `pending`. The exception: other backups on its server are being copied, or one
  finished there in the last 15 minutes. Then the backup is moving up the line,
  and it waits its turn. A backup whose copy began is never failed this way. The
  volume is unchanged. Back it up again.
- Snapshot copies are part of the snapshot and its [price](./pricing).
- Volume backups cost $0.02 per GB (10⁹ bytes) per 30-day month (a
  backup made before this price keeps $0.012 until
  7 November 2026), charged on
  `storedBytes` once the copy is ready. See [pricing](./pricing).


---

<!-- https://withruntime.com/docs/teams -->

# Teams and the audit log

One Runtime account can have as many people as you need. They share its
credit, sandboxes, other resources and keys. Each person has a role. Every
change to members, keys, money and security settings is recorded in an audit
log, with who made it, when, and from which address.

Every account starts with one person: its owner. Nothing changes until you
invite someone.

## Roles

| What they can do                                                  | Owner | Admin | Developer | Billing |
| ----------------------------------------------------------------- | :---: | :---: | :-------: | :-----: |
| See resources, usage, balance, keys and members                   |  yes  |  yes  |    yes    |   yes   |
| Start, run and delete sandboxes and other resources, using credit |  yes  |  yes  |    yes    |    —    |
| Create API keys and approve CLI connections                       |  yes  |  yes  |    yes    |    —    |
| Revoke or limit a key somebody else made                          |  yes  |  yes  |     —     |    —    |
| Have a key make, list and revoke keys over the API                |  yes  |  yes  |     —     |    —    |
| Make a key account-wide, or limit it to its own again             |  yes  |  yes  |     —     |    —    |
| Make, fill and delete compartments                                |  yes  |  yes  |     —     |    —    |
| Add credit and see payments                                       |  yes  |  yes  |     —     |   yes   |
| Invite, remove and change the role of members                     |  yes  |  yes  |     —     |    —    |
| Read the audit log                                                |  yes  |  yes  |     —     |    —    |
| Make someone an owner, or change or remove an owner               |  yes  |   —   |     —     |    —    |

- An account always has at least one owner. To hand over an account, make the
  new person an owner, then leave or change your own role.
- Anyone can leave an account, and anyone can revoke a key they made.
- A key can never do more than the person who made it. Runtime checks that
  person's role on every request. If you change someone from developer to
  billing, their keys become read-only immediately.

## Invite people

Owners and admins invite people at
[Members](https://withruntime.com/account/members). Choose **Invite**, enter an
email address, choose a role, and choose **Send invitation**. To change someone's
role later, pick the new one in their row.

- The person gets an email with a link. The page also shows the link, so you can
  send it yourself.
- The link works once, for seven days. It works only for someone who signs in
  with that email address. A forwarded link does not work for anyone else.
- A new Runtime user signs up through the link and joins your account. A person
  with an existing account keeps it and joins your account too.
- Sending an invitation again to the same address replaces the first one.
  **Withdraw** cancels an invitation that has not been used.
- An invitation stays valid only while its sender could still send it. When the
  sender leaves, is removed, or loses the role that can invite, their open
  invitations are withdrawn.
- An account can have 50 open invitations and send 25 in any 24 hours.

## Several accounts

A person can belong to several accounts, such as their own account and their
company's account.

- **Website:** choose the account from its name at the top of the sidebar. On a
  phone, the name sits at the left of the top bar. Runtime remembers the choice
  in this browser.
- **Connecting an agent:** when you approve a connection or a key request, the
  approval page asks which account it is for.
- **CLI:** every account you connect is saved on the machine.

```bash no-run
npx withruntime account add            # connect another account; choose it in the browser
npx withruntime account                # list them; * marks the one in use
npx withruntime account switch Acme    # use Acme for every command after this
```

- **SDKs and the API:** a key belongs to one account, so use that account's key.
  `GET /v1/me` names the account and the role of the person who made the key.

## Keys in a team

Keys belong to the account, not to a person. Everyone who can see the account
can see every key, and who made it, on the
[API keys](https://withruntime.com/account/keys) page.

- Each key is its own agent, so the audit log and the bill show which key did
  what.
- A key sees and uses only the sandboxes and other resources its own agent made.
  A sandbox made with another key returns 404 to it, while a sandbox's name is
  still unique across the whole account.
- An owner or admin can make a key **account-wide**. It sees and uses every
  sandbox, snapshot, image, volume, service and job in the account, whichever
  key made it. `getOrCreate` with a name another key holds returns that sandbox.
  To make one, choose "Everything in the account" when you create the key, use
  **Make account-wide** on a key's row, or run
  `runtime keys create --account-wide`. Only an owner or admin can approve that
  command. This is how services that share sandboxes work, as a Blaxel
  workspace key does.
- An account-wide key still acts as its own agent. The audit log names it. A
  wake, extension or restart it asks for is billed to it and counts against its
  own daily limit, even on a sandbox another key made. Job secrets stay with the
  person who made the key. The secrets that sandboxes use belong to the account,
  for every key.
- An account-wide key reaches the account only while the person who made it is
  an owner or admin. If that person changes to developer, the key sees only what
  it made again, from the next request. Developers and billing members cannot
  make or switch one. A read-only key already sees the whole account and is
  never account-wide.
- An owner or admin can put a key in a **compartment** when making it. It then
  sees only what its compartment's keys made. No other key reaches in, except an
  account-wide one ([compartments](./security#compartments)).
- A full-access key of an owner or admin can make more keys over the API
  ([run a swarm](#run-a-swarm)).
- The person who made a key sets or changes its daily spending limit. Owners and
  admins can limit or revoke any key. A key can also change the keys it made
  ([run a swarm](#run-a-swarm)).
- When someone leaves or is removed, the keys they made are revoked in the same
  step. What they created, such as sandboxes, volumes and images, stays with the
  account.

## Run a swarm

One paid account has a coordinator and many workers. The coordinator holds a
full-access key of an owner or admin (a wallet account's key is one). It makes
one key per worker, each with its own daily cap.

```bash no-run
runtime keys create --name worker-1 --daily-limit 5   # prints the key once
runtime keys ls                                       # each worker, with its spend
runtime keys usage <keyId>                            # one worker in full
runtime keys update <keyId> --daily-limit 10          # give a worker more room
runtime keys revoke <keyId>                           # when the worker is done
```

```ts no-run
import { Runtime } from "withruntime";

const runtime = new Runtime(); // RUNTIME_API_KEY
const worker = await runtime.keys.create({ name: "worker-1", dailyLimitMicros: 5_000_000 });
// hand worker.key to the worker, then later:
console.log(await runtime.keys.usage(worker.keyId));
await runtime.keys.update(worker.keyId, { dailyLimitMicros: 10_000_000 });
await runtime.keys.revoke(worker.keyId);
```

```bash no-run
curl -sS https://api.withruntime.com/v1/keys -H "Authorization: Bearer ${RUNTIME_API_KEY}" \
  -H "Idempotency-Key: worker-1" -H "Content-Type: application/json" \
  -d '{"name":"worker-1","dailyLimitMicros":5000000}'
curl -sS "https://api.withruntime.com/v1/usage?key=${KEY_ID}" -H "Authorization: Bearer ${RUNTIME_API_KEY}"
curl -sS -X PATCH "https://api.withruntime.com/v1/keys/${KEY_ID}" -H "Authorization: Bearer ${RUNTIME_API_KEY}" \
  -H "Content-Type: application/json" -d '{"dailyLimitMicros":10000000}'
curl -sS -X DELETE "https://api.withruntime.com/v1/keys/${KEY_ID}" -H "Authorization: Bearer ${RUNTIME_API_KEY}"
```

- `POST /v1/keys` takes `name`, and optionally `access` (`full` or `read`),
  `reach` (`agent`, the default, or `account`) and `dailyLimitMicros`. It can
  also take `sandboxes` and `actions` for [a key limited to sandboxes](#a-key-limited-to-sandboxes).
  It returns the new key once. A retry with the same `Idempotency-Key` returns
  without the key.
- `PATCH /v1/keys/{id}` changes a key's `reach` (`agent` or `account`) or
  `dailyLimitMicros` (`null` removes the limit), and returns the key as
  `GET /v1/keys` lists it. A key can change another key only to what it could
  make itself. It widens a key (account-wide, a larger limit, or no limit) only
  if it made that key, at any depth: account-wide only from an account-wide
  key, and the limits of the keys it made still add up to at most its own.
  Otherwise the request returns `403 forbidden`. It can narrow any key it sees:
  back to its own agent, or a smaller limit. A key never changes itself. A key
  limited to sandboxes keeps its reach. Each change is in the audit log.
- Each key is its own agent. A worker with reach `agent` sees only its own
  sandboxes, and its spend and audit rows are its own.
- A key made by a key with reach `agent` can use what a sandbox needs (sandboxes,
  files, images, volumes, snapshots, previews and ports). It can also use the
  Apps and Functions its own agent made (create, list, deploy, roll back,
  delete), its own usage, and `/v1/keys`. Another worker's App returns 404, as
  for an id that does not exist.
  It can deploy an App or Function from an image only. A deploy that names a
  `build` comes from the account's repositories and is refused with
  `403 forbidden`, before any build is read. Deploy builds with a key made on
  the website.
  It can request at most 2 `minCopies`, 2 `spares` and 20 `maxCopies` for an App.
  To make a larger App, use a key made on the website.
  It may set an App's `releaseWatch` to `alert` or `rollback`, never `off`.
  Turning it off would stop the owners hearing of a release that got worse, so
  that is refused with `403 forbidden`.
  It cannot give an App or Function a name that one of the account's own Apps
  holds. Creating or renaming with such a name returns `409 name_taken`.
  The account's own settings are refused with `403 forbidden`, whatever its
  person's role: closing the account, webhooks, telemetry exports, the audit
  log, credit and billing, secrets, scheduled jobs and their secrets, domains,
  networks, builds and repositories. For those, use a key made on the website,
  or make this key account-wide.
- The coordinator sees each worker's spend with `runtime keys ls` or
  `GET /v1/usage?key=<keyId>`. It sees its own spend, the keys it made at any
  depth, and any key its reads already reach.
- Workers start from the coordinator's snapshots that carry the label
  `share: made-keys`. Set the label when you take the snapshot, or later with
  `POST /v1/snapshots/{id}:update`. Only snapshots the coordinator's key took
  itself count. Snapshots of other keys it can reach do not.
  The label is set on each snapshot itself and is never copied. A sandbox
  started from a shared snapshot, a fork's copies and kept snapshot, and a
  snapshot taken without labels of its own all leave out `share: made-keys`. So
  a copy you change and snapshot again is not shared unless you label it.
  A worker key made before this feature was released (see the
  [changelog](./changelog)) does not reach shared snapshots. Make it again.
  Every key under the coordinator, at any depth, can create a sandbox from such
  a snapshot, memory or disk. It can do nothing else with it: it cannot list,
  read, change or delete it. A snapshot without the label returns
  `404 snapshot_not_found` to them. So does a labelled snapshot of a sandbox
  that named its egress secrets (`secrets` on create). A copy would keep that
  list, and those secrets belong to the coordinator, not the worker. The
  coordinator can still start it.
  Sharing never crosses a [compartment](./security#compartments). Revoking the
  coordinator's key ends the sharing.

  ```ts no-run
  const snapshot = await sandbox.snapshot({ labels: { share: "made-keys" } });
  // in a worker, with its own key:
  const copy = await new Runtime({ apiKey: worker.key }).sandboxes.create({
    snapshot: snapshot.id,
  });
  ```

- Revoking stops a key within ten seconds. What its agent made keeps running
  until stopped.
- Only a full-access key made by an owner or admin can do this. A read-only
  key, a selected-actions key, a developer's key or a key in a compartment
  cannot make, list or revoke keys.
- A new key never has more than the key that made it. It can be account-wide
  only if the maker is account-wide. It keeps the maker's expiry and per-request
  cap. When the maker has a daily limit, every key it makes needs one. The daily
  limits of every live key under it, at any depth, add up to at most the maker's
  limit. A worker's own workers share its limit and never add to it. Keys can be
  made at most 8 deep. A read-only key cannot spend, so it takes no limit.
- At most 100 live keys made this way per account, and 1,000 made in any 24
  hours (`quota_exceeded`). Revoke workers' keys when done.
- Each is in the [audit log](#audit-log) as `key.created`, by the making key's
  agent, with `madeBy` naming the key that made it.

### A key limited to sandboxes

A key can be limited to a few sandboxes and to what it may do to them. Give it
to something that needs one sandbox and should hold no key to the rest of the
account. An example is a watcher that restarts a server when it stops responding.

```bash no-run
runtime keys create --name watcher --sandbox <sandboxId> --actions get,create --daily-limit 2
```

```ts no-run
import { Runtime } from "withruntime";

const runtime = new Runtime(); // RUNTIME_API_KEY
const sandboxId = process.env.SANDBOX_ID!; // the sandbox to watch
const watcher = await runtime.keys.create({
  name: "watcher",
  sandboxes: [sandboxId],
  actions: ["get", "create"],
  dailyLimitMicros: 2_000_000,
});
```

- `POST /v1/keys` takes `sandboxes` (1 to 20 ids) and `actions` in place of
  `access` and `reach`. The actions are `get` (read the sandbox and its
  metrics), `create` (start, wake and restart it; it never makes a sandbox),
  `stop` (stop and pause it), `exec` (commands, processes and the
  interpreter), `read_file` and `write_file`.
- It can call only those sandboxes' own routes, by id, and only for the actions
  it was given. Everything else returns `403 forbidden`: other sandboxes, lists,
  deleting, resizing, forking, networks, sessions, secrets, jobs, keys, the
  account's settings and MCP.
- It sees its sandboxes whichever key made them. The making key can name only
  sandboxes it acts on itself, outside every compartment.
- Only `create` spends, so only a key with it takes a daily limit. It needs one
  when the making key has one.
- `runtime keys ls` and `GET /v1/keys` show it with reach `sandboxes`, its
  `sandboxes` and its `actions`. It makes no keys.

#### Asked for in the browser

With no key on the machine, or with `--browser`, the same command asks an owner
or admin to approve the key in the browser. `runtime keys create` does this for
any key. Use it when a connector such as ChatGPT or Claude made the sandboxes
and nobody holds a key to make one with. You can also use it to give an agent
somewhere else a few sandboxes and nothing more:

```bash no-run
runtime keys create --name helper --sandbox <id>,<id> --actions get,exec,read_file,write_file
```

- It prints a link and a code. The approval page names each sandbox, what the
  key can do to it, and whether it can spend. The key goes to the terminal that
  asked, sealed to it, and is never shown anywhere else.
- Only an owner or admin approves it, for any sandbox in the account outside
  every compartment, whichever key made it.
- Without `create`, the key cannot start, wake or restart its sandboxes. It takes
  no daily limit, and it places no hold of its own. A running sandbox it reaches
  is billed to its owner as usual. Commands the key runs count as activity, so
  they keep the sandbox from pausing when idle. To limit that, give the sandbox a
  time limit (`timeoutSeconds`) or stop it when done.

## Leaving and removing

On [Members](https://withruntime.com/account/members), use the link at the end of the person’s row
and confirm:

- **Leave** takes you out of an account. The last owner cannot leave until
  there is another owner.
- **Remove** takes someone else out. Admins remove developers, billing members
  and other admins; only an owner removes an owner.
- Either way, the person loses access immediately, and their keys stop working.
  They can be invited back, with a new role if you like.
- What they made stays in the account. Their stopped and paused sandboxes' disks,
  snapshots, volumes and images are kept on the account's credit, as anyone's
  are, until someone deletes them. The same holds when your directory suspends
  someone.

## Emails

Each person chooses which of Runtime's optional emails they get, for each
account they are in, at Settings, Emails
([withruntime.com/account/emails](https://withruntime.com/account/emails)).
Turning one off stops it for you only. Other owners still get theirs. The
account's notices (`GET /v1/notices`, Usage & billing) and webhooks still include
every one. Each of these emails also ends with a link that stops that kind
for you, after asking.

| Setting         | What it is                                                                                   |
| --------------- | -------------------------------------------------------------------------------------------- |
| `own-deletions` | A day before a sandbox is deleted at the date its own `:retention` chose, at most once a day |
| `billing`       | When the account's credit runs low or runs out                                               |
| `usage`         | When the account has used 80% and all of the month's free usage                              |
| `tips`          | A few getting-started emails in your first days                                              |

Always sent, with no switch: sign-in links and invitations, a revoked key,
replies in a support conversation, credit about to expire, service credits,
and a warning before Runtime deletes something nothing pays for.

From code, a key reads and sets only its own person's emails, never anyone else's:
`GET /v1/account/emails`, and `POST /v1/account/emails:update` with
`{"category": "own-deletions", "enabled": false}`. In the CLI, use
`runtime account emails` and `runtime account emails own-deletions off`. In
MCP, `runtime_account` action `emails` reads them. Reading them needs a key
that reads usage. Changing them needs a key with every action. A read-only or
limited key returns 403 `forbidden` and changes nothing. A key with no
person (a wallet account's) has none, and returns 403 `no_person`.

## Closing the account

An owner closes the account for good on the
[Close account](https://withruntime.com/account/close) page, linked at the foot of
Members. It can also be done from the terminal with `withruntime` 0.7.0 or later:

```bash no-run
runtime account close --confirm "Acme Inc"
```

Type the account's name exactly. `runtime whoami` shows it. The CLI and the API
(`POST /v1/account:close` with `{"confirm": "<name>"}`, or
`runtime.account.close({ confirm })` in either SDK, from `withruntime` 0.7.0)
need a key for every product made by an owner. No MCP tool closes an account.

Closing cannot be undone. Immediately:

- every sandbox stops, and every snapshot, image, volume, volume backup,
  secret, egress secret and saved registry password is deleted;
- custom domains, dedicated addresses and the private network are released,
  and webhooks, telemetry exports and the upstream proxy removed;
- every key and CLI connection stops working, open invitations are withdrawn,
  and every member loses access.

Unspent credit from a purchase made in the last 15 days is refunded on request.
Write to support@withruntime.com. Other credit, including granted and referral
credit, is forfeited. Signing in again later starts a new, empty account.

## Audit log

Owners and admins read the audit log at
[Audit log](https://withruntime.com/account/audit). It records:

- **Members:** joined, added, removed, left, and role changes; invitations sent
  and withdrawn
- **Keys:** created and revoked, with the reason when Runtime revoked one; CLI
  connections and key requests approved or denied; spending limits set and removed
- **Credit:** top-ups started, credit bought, granted, earned by referral,
  refunded, disputed, taken back or expired
- **Security settings:** network rules, secrets created, updated, rotated,
  revealed and deleted (never the value), preview ports made public or private
- **Creations:** every sandbox, volume, image, snapshot, service and job, with
  its name, labels and funding. Rules a sandbox is created with are part of its
  creation. A later change is recorded as a network rules entry. Funding is
  `trial` when the free usage pays for it. That covers a volume inside its
  10 GiB, and a job on an account without credit. Such a job runs nothing until
  the account holds credit.
- **Sandboxes:** every pause, wake, restart and stop, with who asked. For each
  one Runtime did itself, the entry says why: the sandbox sat idle, it reached
  its time limit, credit ran out, or a spending limit was hit.
- **Deletions:** volumes, images, snapshots, services and jobs
- **The account:** created, renamed, suspended and restored; the encryption key
  for its backups created, rotated (the old key made read-only) and destroyed
- **Single sign-on:** connections added, changed and removed, domains
  verified, single sign-on required or not
- **Directory sync:** SCIM tokens made and revoked, people your directory
  added, deactivated, reactivated or deleted, and the role each group gives

Each entry has the action; who did it (a person, a key, your directory, or
Runtime itself, for things like a card payment); the time; the client's IP
address; the request id; and whether it came through the website, the API or
MCP. A call made by code inside one of your sandboxes also names that sandbox.

Entries are kept for at least 400 days. Nobody can edit an entry, and none is
deleted before then. The page downloads the whole log, or one group of it, as
a CSV file.

### Read it from code

A key made by an owner or admin can read the log, if it has full access or is
read-only. Entries are listed newest first, 50 at a time by default, up to 200.

```bash no-run
curl -H "Authorization: Bearer $RUNTIME_API_KEY" \
  "https://api.withruntime.com/v1/audit?action=member.&limit=100"
npx withruntime audit --action key.
```

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

const runtime = new Runtime();
const { events, next } = await runtime.audit.list({ action: "credit." });
console.log(events.length, next);
```

```python check
from withruntime import Runtime

with Runtime() as runtime:
    page = runtime.audit.list(action="credit.")
    print(len(page["events"]), page["next"])
```

- `action` is one action, like `key.created`, or a group ending in a dot:
  `member.`, `invitation.`, `key.`, `connection.`, `limit.`, `credit.`,
  `network.`, `secret.`, `preview.`, `resource.`, `account.`, `sso.`, `scim.`.
- `next` is the page's last entry. Pass it as `before` for older entries.
- MCP: the `runtime_audit_list` tool, with the same filters.
- A key made by a developer or billing member, or a key limited to selected
  actions, gets `403 forbidden`.

## Sign-in and single sign-on

People sign in with an email link, with Google, or with your company's
identity provider. Single sign-on works over SAML or OIDC with Okta, Microsoft
Entra ID, Google Workspace and any other standard provider. SCIM directory
sync adds, updates and removes people for you. Both are free on every account.
See [single sign-on](./single-sign-on) for the setup.

- An owner connects your identity provider for your email domain. The owner
  proves the domain with a DNS record. Only an owner can change single sign-on.
- Anyone on that domain who signs in through your provider joins your account
  with the role you choose. Someone you removed does not come back that way.
- **Require single sign-on** makes your provider the only way in for members.
  Owners can still use Google or an email link, so a broken provider cannot
  lock you out, and API keys keep working.
- With SCIM, deactivating someone in your directory removes them from the
  account and revokes every key they made, immediately. Groups in your directory
  decide roles: admin, developer or billing, never owner.


---

<!-- https://withruntime.com/docs/troubleshooting -->

# Diagnose a sandbox integration

Start with the failing step: connection, creation, readiness, execution, pause, wake or cleanup.

- Every error carries a `code`, a `hint` and a `requestId`. Follow the hint
  first.
- Keep the request id, the sandbox id, the time and the SDK version for a
  report. Never include API keys, connection secrets or private file contents.
- Confirm you are using the correct account and API origin.

Check https://withruntime.com/status first. It shows whether the API responds.
That check runs from outside our servers every two minutes. It also shows
whether a real sandbox starts, runs a command and stops. That test runs from
outside every ten minutes. The page also shows uptime since the record began,
and notes on incidents.

If it looks like Runtime's fault, report it with
`npx withruntime feedback "..." --request-id <id>`. If you are stuck, ask
`npx withruntime support "..."`. The support agent reads your account and can
reproduce the problem. See [feedback and support](./feedback-and-support).

## Browser login does not finish

**Open the exact link the CLI printed, check the code, and approve as an owner,
admin or developer of the account.**

- If the command was stopped while it waited, run it again. It shows the same
  link and code, and picks up the approval.
- Approval and delivery are separate. The browser waits for the CLI to receive
  and verify the credential before it shows success.
- Requests expire after 15 minutes. After expiry, start a new `npx withruntime login`.
- On a remote terminal, use `--no-browser` and open its link on your own device.
- If the CLI cannot reach Runtime, check its outbound HTTPS access. Do not paste
  credentials into the browser or into your agent's prompt.

Run `npx withruntime whoami` to check a saved connection. If it is refused, run
login again. `RUNTIME_API_KEY` overrides the saved connection. An invalid
environment key can fail even when browser login worked before. Remove an
unwanted override without printing its value.

If a previous credential update was interrupted, the CLI names its lock file.
Remove that file only after confirming no Runtime command is running, then
retry. The CLI never steals an active lock automatically.

## Behind a proxy, every call says `No answer from Runtime`

**From SDK version 0.4.0, the CLI and both SDKs use the proxy your environment
names, the way curl does:**

- `HTTPS_PROXY` carries every call to the HTTPS API and terminal WebSockets,
  through a `CONNECT` tunnel. A `user:password@` in its address is sent to the
  proxy. `HTTP_PROXY` is used only for `http://` addresses, never for HTTPS.
- `NO_PROXY` lists hosts to reach directly, split by commas or spaces. A name
  covers its subdomains, a leading dot is allowed, `host:port` limits it to one
  port, and `*` alone means every host.
- Each name works in upper or lower case. When both are set, lower case wins.
  A proxy address without a scheme is taken as `http://`.
- A proxy address that cannot be used fails immediately with `invalid_proxy`,
  naming the variable.

When the proxy cannot be reached, the error names it. For example:
`No answer from Runtime at https://api.withruntime.com through the proxy
http://proxy:3128 (HTTPS_PROXY).` If the proxy returned 407, the hint says to
put credentials in the variable as `http://user:password@host:port`. If only
`HTTP_PROXY` is set, the hint says to set `HTTPS_PROXY`, since the API is HTTPS.

On earlier versions, every call fails with `connection_error` ("No answer from
Runtime at https://api.withruntime.com") while `curl` through the same proxy
works, because the client connects directly:

- **CLI and JavaScript SDK on Node 22.21 or later, or Node 24.** Also set
  `NODE_USE_ENV_PROXY=1`. Then Node's own `fetch` reads those variables. Node's
  documentation marks this setting as still in active development.
- **Under Bun**, the proxy variables already work.
- **The Python SDK** connects directly, and no setting changes that. Upgrade.

```bash no-run
NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.example.com:3128 npx withruntime whoami
```

## The CLI stops with `OpenSSL configuration error`

**Node could not read an OpenSSL configuration file, so it stopped before the
CLI started.** This happens with a Node build that uses the system's OpenSSL,
such as Homebrew's or a Linux distribution's. It also happens inside a sandbox
that blocks reading outside the project, such as a coding agent's.
`OPENSSL_CONF` naming a file that cannot be read does the same. The message
names the file:

```text
node: OpenSSL configuration error:
...:BIO_new_file:Permission denied:...calling fopen(/opt/homebrew/etc/openssl@3/openssl.cnf, rb)
```

The CLI does not need that file. Give Node an empty one for the command, or let
the sandbox read the file that the message names:

```bash no-run
OPENSSL_CONF=/dev/null npx withruntime whoami
```

Node from nodejs.org reads no such file, so it starts either way.

## Creation is refused

| Code                      | What it means                                                                               | What to do                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `no_credit_running_limit` | Four sandboxes without credit are already running; `details` names them                     | Stop or pause one, or retry once one ends                                                                                          |
| `no_credit_domain_limit`  | Your email domain's eight shared slots without credit are all running                       | Stop or pause one, or add credit                                                                                                   |
| `included_usage_used_up`  | This month's free usage, or a product's share of it, is used                                | Add credit, or wait for the 1st (UTC)                                                                                              |
| `no_credit_size_limit`    | A sandbox without credit is at most 2 vCPU, 4 GiB of memory and 10 GiB of disk              | Omit the size fields for the default                                                                                               |
| `invalid_request`         | `details.issues` names every wrong field                                                    | Fix the named fields; unknown fields are refused                                                                                   |
| `invalid_region`          | `details.available` lists your regions                                                      | Use a region listed for your account, or omit it                                                                                   |
| `no_capacity`, `busy`     | No host has room right now (503)                                                            | Wait `Retry-After`, then retry with the same idempotency key and a growing delay; for a planned burst, [book room](./reservations) |
| `image_not_found`         | `image` names nothing in your account; the message lists the name's tags                    | Name one it lists, or build a public image first                                                                                   |
| `volume_not_ready`        | A volume it names, or one you back up, is still `creating` (a restore is too until checked) | Wait until the volume reads `ready`, then try again                                                                                |

**`no_credit_running_limit` is temporary.** It returns 429 with `Retry-After: 5`.
A slot frees when any sandbox without credit stops or pauses.

- Retry with the same idempotency key, a growing delay and a bounded deadline,
  or stop or pause one of the sandboxes `details` names.
- A fork asking for more running copies than an account without credit allows
  never fits. Ask for fewer.
- An SDK create waits for a slot by itself, for up to two minutes by default
  (`waitForCapacityMs` in JavaScript, `wait_for_capacity` in Python, Ruby), and
  then returns the refusal. A wake and a restart wait the same way for room on
  their own server, and a fork when no server has room for a copy. The error's
  `retryable` is `true`, for a loop of your own.
- Once the account holds prepaid credit, it runs more sandboxes immediately,
  with nothing to change.

Once the free usage is used up, an account with prepaid credit keeps running on
that credit, with nothing to change. An account with neither is refused with
`included_usage_used_up` until the 1st (UTC). See how much is left with
`npx withruntime usage`, or with `GET /v1/usage` or `GET /v1/limits`.
`trial.availableMs` is what a new sandbox without credit can still use, in
milliseconds, after what running sandboxes hold; a create is refused exactly
when it is 0. `allowances` shows what each pool has left this month. When
the account has no free machine time at all, `freeUsageHold` says why, and
the refusal's `details.reason` names the same rule. See
[free usage](./included-usage).

## A sandbox's `env`, stop, delete or image switch is refused

| Code                          | What it means                                                                                                                                                          | What to do                                                                                                                   |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `invalid_env`                 | A name is not a letter or underscore followed by letters, digits and underscores, or a value holds a NUL; `details.name` says which                                    | Rename the variable, or drop the byte                                                                                        |
| `env_too_large`               | More than 32 variables or 32 KiB in the sandbox, or a command's own `env` and the sandbox's together are more than one command carries | Keep large settings in a file in `/workspace`, or pass fewer in the command                                                  |
| `env_unavailable`             | This deployment cannot store an environment; nothing was created or changed                                                                                            | Pass `env` to each `exec` instead                                                                                            |
| `resize_unavailable`          | Changing a running sandbox's size is not switched on here; nothing was changed                                                                                         | Create a new sandbox at the size you need                                                                                    |
| `env_unreadable`              | Its stored environment could not be opened, a fault on our side, so nothing ran                                                                                        | Set it again with `:update`, or contact support with the request id                                                          |
| `sandbox_in_use`              | The sandbox runs a managed service                                                                                                                                     | Delete the service, which ends its sandbox                                                                                   |
| `snapshot_in_progress`        | A stop or delete came while a snapshot of the sandbox is still being taken, and would have lost it; nothing changed                                                    | Wait until the snapshot is `ready` (seconds; `GET /v1/snapshots/{id}`), then stop or delete it; or delete the snapshot first |
| `switch_keeps_workspace_only` | `keep` named something other than `"workspace"`: a switch of image keeps only `/workspace`; nothing changed                                                            | Leave `keep` out, or snapshot the sandbox first to keep everything                                                           |
| `switch_undone`               | The switch did not finish and was undone: the sandbox is on its old image with its files as they were                                                                  | Retry; a `/workspace` that takes longer than 60 seconds to copy cannot be switched                                 |
| `switch_needs_disk`           | A stopped sandbox that was not persistent kept no disk, so there is nothing to move                                                                                    | Create a new sandbox from the image                                                                                          |
| `image_on_another_host`       | The image is stored on another server than the sandbox                                                                                                                 | Create a new sandbox from the image, or build it again                                                                       |
| `delete_unavailable`          | Deleting cannot run here yet, a fault on our side that we are told of                                                                                                  | Stop it instead, and delete it later                                                                                         |

## Creation returns `starting`

**The SDKs and `npx withruntime sandboxes create` wait for `running` for you.**
Over raw HTTP, send `Prefer: wait=60`, or read the sandbox with
`?waitFor=running`.

Wait for running before you issue commands. A command on a sandbox that is still
starting waits up to 30 seconds, then returns `sandbox_not_ready`. If the
sandbox stops before it is ready, its `stopReason` says why. Report that failure
with its sandbox id and request id. Do not start a new sandbox repeatedly
without checking the first request's outcome.

## A sandbox stopped on its own

**Read its `stopReason`.** A sandbox paused at the end of its time limit, or by
`:pause`, has lost nothing and has no `stopReason`: wake it. A paused sandbox
that reads `pause_failed` lost its memory and kept its files.

| `stopReason`         | What it means                                                                                                                                                                                                                                                                                                                                                                          | What to do                                                                                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `idle`               | Read on a paused sandbox, not a stopped one: nothing happened in it for `idlePauseSeconds`, so it paused itself. Nothing is lost                                                                                                                                                                                                                                                       | A request wakes it while `autoWake` is on; `idlePauseSeconds: 0` keeps it running                                                                |
| `requested`          | A key, an agent or a person stopped it                                                                                                                                                                                                                                                                                                                                                 | Nothing                                                                                                                                          |
| `time_limit`         | The time limit it was created with (`timeoutSeconds`) ran out, and it was made to stop then rather than pause: `onTimeout: "stop"`. Its disk is kept for `:restart`. Before 4 October 2026 this read `lease_expired`                                                                                                                                                                   | Leave out `timeoutSeconds` so the next one runs while it works, or extend a running one before its end (`keepAlive` in the SDKs does it for you) |
| `paused_expired`     | It stayed paused past its `pausedExpiresAt` (seven days without credit, days you set, or seven days after credit ran out), so its memory and disk were deleted                                                                                                                                                                                                                         | Wake it before then, top up, set `:retention` to `null`, or take a snapshot                                                                      |
| `insufficient_funds` | The credit ran out, or the account is blocked by a payment that is disputed or [under review](./pricing#when-a-payment-is-under-review)                                                                                                                                                                                                                                                | Add credit at Usage & billing. When a dispute or review is the cause, a create returns `account_blocked` and says what clears it                 |
| `pilot_hours_used`   | The pilot it ran on has used its sandbox hours, so it paused or stopped with its files kept. Credit does not run a pilot's sandbox                                                                                                                                                                                                                                                     | To extend the pilot or ask for more hours, the account's owner writes to support (support@withruntime.com, or a reply to the pilot's email)      |
| `pilot_ended`        | The pilot it ran on, and the pilot's grace, are over. A pilot's sandbox runs only on its pilot, and is kept seven days, then deleted, with an email first                                                                                                                                                                                                                              | To extend the pilot, the account's owner writes to support before then. New sandboxes run on free usage or credit                                |
| `lifetime_cap`       | The sandbox reached its own `maxTotalCostMicros`                                                                                                                                                                                                                                                                                                                                       | Start a new sandbox if the work needs more                                                                                                       |
| `spending_limit`     | An owner-set spending limit, usually this agent's daily one                                                                                                                                                                                                                                                                                                                            | See what is left with `GET /v1/limits` or `runtime limits`                                                                                       |
| `authority_revoked`  | The key or agent that made it was revoked or removed                                                                                                                                                                                                                                                                                                                                   | Connect the agent again or make a new key, then create a new sandbox                                                                             |
| `startup_failed`     | It stopped before it was ready to run commands                                                                                                                                                                                                                                                                                                                                         | If it starts from your image, check the image's start and ready commands; otherwise report the sandbox id                                        |
| `account_busy_here`  | It can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start. Nothing ran in it                                                                                                                                                                                                                               | Start it again in a minute, or once some of your sandboxes there are done; keep sources on separate servers with `spreadFrom`                    |
| `service_unready`    | A service on our side that it needs was unavailable, so it could not keep running                                                                                                                                                                                                                                                                                                      | Create a new one, and report the sandbox id if it happens again                                                                                  |
| `pause_failed`       | Read on a paused sandbox: the pause could not keep its memory, so the programs that were running are gone, and its files are kept                                                                                                                                                                                                                                                      | Wake it: it starts fresh from its disk and reads `memoryRestored: false`. Report the sandbox id                                                  |
| `host_stopped`       | Its machine ended it without a stop being asked for. While it was starting or waking that is our fault; once it was running it can also be a shutdown or crash inside the sandbox                                                                                                                                                                                                      | Check whether your program shut the machine down; otherwise create a new one and report the sandbox id                                           |
| `host_lost`          | The server it ran on stopped responding and was taken out of service. Its memory is gone; its disk is kept (`diskKept: true`) unless it was a single copy                                                                                                                                                                                                                              | With `diskKept: true`, Runtime restarts it on another server; if it stays stopped, `:restart` it. Otherwise create a new one                     |
| `operator_stopped`   | Runtime stopped it: an operator, a suspension of the account, or the [abuse checks](./security#network-access) on traffic only abuse makes, which also cut its network. Your inbox (`GET /v1/notices`) holds an `abuse-halted` notice saying what was seen. Until it is lifted, its network stays off and a command, file write, snapshot or fork of it returns `sandbox_halted` (403) | Start it and download its files (`GET /v1/sandboxes/{id}/files/archive`); write to support with the sandbox id if you think it was a mistake     |

Only a person can raise a spending limit, on the account's keys page: the member
who made the key, or an owner or admin. Do not
create replacements in a loop; the limit counts the last 24 hours.

## A running sandbox refuses commands

Each code below means nothing ran. A retry with the same idempotency key runs the call at most once. The SDKs retry each of them.

| Code                              | Status | What it means                                                                                                                                    | What to do                                                                                                                                 |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `guest_busy`                      | 429    | The sandbox is running as many commands as it can at once                                                                                        | Wait `Retry-After`, then retry. Run fewer commands at once                                                                                 |
| `sandbox_unreachable`             | 503    | The sandbox's agent did not answer for about ten seconds. When its memory was full shortly before, the message names the process that was killed | Retry. If it repeats, restart the sandbox (`POST /v1/sandboxes/{id}:restart`). A running sandbox reboots from its disk, and its files stay |
| `sandbox_environment_unavailable` | 503    | The sandbox could not read its environment from its server's network service. The fault is ours, and we are alerted                              | Retry. If it lasts more than a minute, restart the sandbox                                                                                 |

**A slow disk returns an error within seconds.** When the sandbox's server cannot finish writing to its disk, a new command returns `sandbox_unreachable` (503) after 5 seconds, with `details.reason` set to `disk_stalled`. The request ran nothing. Commands already running continue, and their output can be read as usual. Retry with the same idempotency key; the SDKs do.

**A sandbox that stops responding says so.** Within about 5 seconds, `GET /v1/sandboxes/{id}` returns `unreachable` with `since` and `reason` (`agent_not_answering`, `disk_stalled` or `host_quarantined`), and the event `sandbox.unreachable` is sent to your [webhooks](./observability#events). `sandbox.reachable` follows when it responds again. For `agent_not_answering` or `host_quarantined`, restart the sandbox: it reboots from its disk and keeps its files.

**A sandbox at its memory limit stays reachable.** When the sandbox's programs fill its memory, Linux's out-of-memory killer ends one of them, never Runtime's agent. Commands keep running. Each process killed is recorded as the event `sandbox.oom_kill`, which names the process, its process ID and the memory it used. The event appears on the sandbox's page in the console and in `GET /v1/events?resourceId=<id>`, and is sent to your [webhooks](./observability#events). A command whose own processes were killed also returns `outOfMemory` in its result. Give the sandbox more memory (`memoryMiB`), or make the program use less.

## The request timed out

**A missing response is not proof that a command failed to run.** Use the same
idempotency key and identical input. The server returns the first result again
instead of running it twice. The SDKs do this for you. If a command's outcome is
still unknown, inspect its files and `processes` before repeating a side effect.

## The service returns 401, 403, 409, 429 or 5xx

| Response           | What to check                                                                                                | Safe next step                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| 401                | Missing, expired or revoked key; wrong API origin                                                            | Check `npx withruntime whoami` or the secret-manager configuration         |
| 403                | Owner approval, key scope, account suspension or resource ownership                                          | Confirm the account and permitted action; do not work around a refusal     |
| 409                | The resource's state: paused (`sandbox_paused` with `autoWake` off says so), stopped, or a name already held | Resolve that state (`wake`, or `autoWake: true`), then retry               |
| 422                | Well formed but not possible as asked, such as an idempotency key used before with a different body          | Same key, same body; or a new key for genuinely new work                   |
| 429                | Your own limit: request rate, concurrent work, a quota or a daily cap                                        | Respect `Retry-After`, add a growing delay, and reduce concurrent requests |
| 5xx or no response | The write may already have reached the server                                                                | Retry identical input with the same idempotency key and inspect state      |

A 5xx whose message says the fault is ours was reported to us when it happened,
with its `requestId`. [API errors and retries](./api) describes the full
contract.

**`time_limit_too_short` (409) means the command could outlast the sandbox's
time.** A command is refused, and nothing runs, when the timeout you set is
longer than the time left before the sandbox's time limit, or before the end of
its funding once credit, free usage or a spending limit ran out. A paused
sandbox is refused before it is woken, so the wake costs nothing. For a time
limit, raise it first (`runtime sandboxes extend <id> 600`, `sbx.extend(600)`).
For funding, add credit or raise the limit (`runtime limits`). Or give the
command a shorter timeout. `details.secondsLeft` gives the time left. A
sandbox with no time limit and credit to run accepts a command of up to 24
hours. A command with no timeout of yours is not refused: it runs until the
sandbox's end, unless that is within about three seconds.

At create or resize, `time_limit_too_short` means the time limit is too short
to load the sandbox's memory back after a pause. The message names the least
`timeoutSeconds` for that size (190 for 65,536 MiB). Use it, leave the limit
out, or ask for less memory.

## The command succeeded over HTTP but the task failed

**Check the command's exit code, standard error and truncation flags.** HTTP
success means the operation was handled, not that the program returned zero.

- A result holds all of the output, up to 256 MiB of each stream. `stdoutTruncated`
  or `stderrTruncated` is `true` when `maxOutputBytes` or that limit cut it, or when an older sandbox returned
  at most 64 KiB of a stream (its byte count is then `null`). Stop and start
  such a sandbox, or stream the output.
- Use `check: true` (`check=True` in Python) to raise on a non-zero exit.
- A timeout is a result with `timedOut: true`. Raise `timeoutMs`, or run long
  jobs in the background and follow their output.

## A file operation fails

File errors name the path and the reason: `file_not_found`, `is_a_directory`,
`not_a_directory`, `permission_denied`. Paths are absolute. `/workspace` is home.
Outside your own files, use `sudo` in a command.

## A command or a write answers `no_space`

The sandbox's disk is full. Commands still run on a full disk, so you can free
space with a command, such as `rm -rf /workspace/node_modules/.cache`, or
`du -sh /workspace/* | sort -h` to find what is large. A disk cannot be grown in
place. For more room, create a sandbox with a larger `diskMiB`.

## Dependencies cannot reach a server

**Check the sandbox's network rules and the destination port.**

- `npx withruntime sandboxes network <id>` shows the rules.
- A sandbox without credit reaches ports 80 and 443 only. A paid sandbox of an account
  with a kept top-up reaches every port. `openPorts` in the rules says
  which. See [the sandbox environment](./sandbox-environment#the-network).
- Name lookups or `pip install` time out in a sandbox from your own image on
  a Debian or Ubuntu base, such as `python:3.12-slim`, built before 30
  September 2026. The image kept its own `/etc/resolv.conf`. Build it again.
  Every image built since uses Runtime's resolver ([images](./images)).
- `API rate limit exceeded for <address>` from `api.github.com`: calls
  without a token share a limit with everyone on that address. Store a GitHub
  token as a secret ([shared addresses and per-address limits](./egress#shared-addresses-and-per-address-limits)).
- Do not disable security protections to make a migration appear successful.

## A secret's placeholder reaches the server unchanged

**Read the sandbox's `sandbox.secret_not_applied` event first.** Runtime sends
it when it sees a placeholder go out without being replaced. Its `reason` and
`message` say why ([events](./observability#events)):
`npx withruntime events --type sandbox.secret_not_applied`. With no event,
check these four things, in order. They decide whether a request carries a
[secret](./security#secrets-sandboxes-never-see).

1. The host. `npx withruntime secrets ls` shows each secret's hosts. The URL's
   host must be one of them by name: `*.example.com` covers
   `api.example.com` but not `example.com`, and an IP address never matches.
2. The request. Only HTTPS carries a secret, and only in its credential
   header, never in the URL or the body. With `rules`, the method and path
   must match a rule: `/ingest` does not match `/ingest/`, and a path that
   could be read two ways (an encoded slash, a semicolon or a backslash) gets
   no secret that has rules.
3. The route. Inside the sandbox, run
   `curl -sv https://<host>/ -o /dev/null 2>&1 | grep -i issuer`. For a secret's
   host, the issuer is Runtime's egress certificate. The server's own issuer
   means the request never reached the step that adds the secret. The client
   went around the sandbox's proxy (raw sockets and some HTTP libraries ignore
   `HTTPS_PROXY`), or the host is in its `NO_PROXY`. The sandbox's own
   `NO_PROXY` lists only loopback and private addresses, so a secret's host is
   there only if your code added it. If the server could not add the secret
   at that moment, a `withheld` event says so. That is Runtime's fault, not
   your code's.
4. Pinned certificates. A client with its own certificate list needs
   `/usr/local/share/ca-certificates/runtime-egress.crt` added to it.

If all four hold and the placeholder still arrives,
write to support with the sandbox's id, the time of the request
and the output of step 3.

## The bill differs from an estimate

**Compare like with like.** Compare total CPU-seconds, provisioned memory, the
quoted CPU floor and actual running duration. Include startup, dependency
installation, retries and cleanup. A running sandbox's charges settle as it
runs, so wait for it to stop before comparing the total.

- Usage & billing groups daily and monthly settled service charges in UTC. Its
  estimate for the rest of the month is the pace so far, not a charge.
- A payment adds credit. It is not service usage.
- Paused storage is a separate meter, so stopping compute does not prove all
  retained-storage charges have ended.

## A paused sandbox will not wake

**Check `pausedExpiresAt`, available credit and the error code.** Wake needs
room on the original host for CPU, memory, the full disk allowance and its next
snapshot. A full host can refuse restoration while preserving the saved state.
When the host is short only because of work Runtime runs at the lowest
priority there (such as Runtime's own CI), the wake pauses that work and waits
up to 20 seconds for the room before it returns `no_capacity`. A request
that would wake a sandbox while a snapshot of it is being taken waits for the
snapshot to finish, then wakes it. Past the request's own deadline, it returns
`snapshot_capturing` (409). A retry once the snapshot is over wakes it.

- Do not delete it as a retry step.
- Missing memory images are an error, not an instruction to claim a fresh boot
  restored the previous process.
- Keep important outputs outside a sandbox before relying on long retention.

See [storage and retention terms](./pricing) and [isolation](./security).

## A sandbox stays `resuming`, or its operation never finishes

**A wake that is still `resuming` after a minute is stuck on our side.** A wake that boots from the
disk, because the memory could not be kept (`memoryRestored: false`), does so within seconds. While
a sandbox is `resuming`, a command on it waits up to 30 seconds and then returns
`sandbox_not_ready`.

**An operation we cannot finish gives up within about a minute.** The
sandbox then stays in the state it was moving from (`starting`, `resuming`,
`pausing` or `stopping`), with its files kept and nothing charged. Its response
carries `operationFailed`: the action (`start`, `wake`, `pause`, `stop`
or `delete`) and when it failed. Every command and wake on it returns
`operation_failed` (500) immediately instead of waiting. Our operators are
alerted. Retrying the same call does not help. A stop or a delete does.
A wake or pause that gave up because its machine held the sandbox for our
operators is retried every five minutes. Once the machine has let it
go, the sandbox is `paused` again (with `stopReason: "pause_failed"` and
`memoryRestored: false` on its next wake if its memory could not be kept),
and its next command wakes it.

| What you see                                   | What it means                                                                                                                                                                                           |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host_unknown` (5xx)                           | The sandbox's machine failed to carry out the request. The fault is ours, and it was reported when it happened                                                                                          |
| `fence_conflict` in an operation's result      | The machine would not take the wake as asked, so the sandbox was put back to paused with its files                                                                                                      |
| `pause_failed` with `memoryRestored: false`    | The programs that were running are gone; the files are kept, and the next wake starts fresh from the disk                                                                                               |
| `resuming` or `pending` for more than a minute | An operation on the sandbox cannot finish, and calls on it wait behind it                                                                                                                               |
| `operation_failed` (500), or `operationFailed` | The operation gave up. Stop the sandbox to keep its disk and restart it later, or delete it                                                                                                             |
| `wake_refused` (503)                           | A wake or restart was refused immediately by a fault of ours, before anything ran or was charged. The sandbox stays as it was with its files kept, and we were alerted. Retry the wake in a few minutes |

- Your other sandboxes are not affected: a stuck operation holds one sandbox.
- Do not delete the stuck sandbox as a retry step, and do not retry commands
  on it in a loop. Its files are kept while it is stuck.
- After `operation_failed`, stop it (`runtime sandboxes stop <id>`) to keep
  its disk, then restart it, or delete it if you do not need its files. A
  sandbox whose stop or delete gave up can only be deleted. Write to support
  to keep its disk.
- After `wake_refused`, retry the same wake or restart in a few minutes. It
  is safe to repeat, and nothing was queued. Its paused storage is not billed
  from the first refused wake until it can wake. Write to support if it
  still fails after an hour.
- Continue in a new sandbox from the same image if the work cannot wait.
- Write to support with the sandbox id and the time it got stuck. An operator
  clears it and tells you whether its files can be brought back.

## Stop returned, but the sandbox is still stopping

**Stop is asynchronous.** The SDKs wait for `stopped`. Over HTTP, send
`Prefer: wait=60`, or read the sandbox with `?waitFor=stopped`. Compute ends
after confirmed VM shutdown. Do not report cleanup complete just because the
request was accepted.

## MCP is connected but execution is still local

**MCP tools and a framework's built-in shell are different paths.** Configure
the framework's execution backend, or replace its tool registration explicitly.
Run a probe that prints the sandbox id and verifies a remote file round trip
before you call the switch complete.


---

<!-- https://withruntime.com/docs/trust -->

# Security and compliance

Runtime runs every sandbox in its own Firecracker virtual machine on dedicated
servers in audited data centers, encrypts every backup to keys the storage
provider never sees, and publishes how it works. This page is the summary a
security review asks for, with links to the detail.

For a questionnaire, a data processing agreement or anything this page does not
cover, write to security@withruntime.com.

## Where your data lives

Everything runs in one region, US East
([speed](./speed) has the measurements).

| What                                         | Who                   | Their certifications, checked 27 September 2026 |
| -------------------------------------------- | --------------------- | ----------------------------------------------- |
| Sandboxes, their disks and memory            | Data center, US East  | SOC 1, SOC 2 and SOC 3 Type 2; ISO 27001        |
| Accounts, billing, audit log, sealed secrets | Neon                  | SOC 2 Type 2; ISO 27001 and 27701               |
| The website, the API and the console         | Vercel                | SOC 2 Type 2; ISO 27001                         |
| Encrypted backups                            | Backblaze B2          | SOC 2 Type 2                                    |
| Card payments                                | Stripe                | PCI DSS Level 1                                 |
| Email in and out                             | Cloudflare, Resend    | SOC 2 Type II; Cloudflare also ISO 27001        |

The full list, with what each company does and where, is on the
[subprocessors](/legal/subprocessors) page, and the
[data processing addendum](/legal/dpa) is part of the terms for every account.

## How your work is kept apart

- **Each sandbox is its own virtual machine**, with its own Linux kernel, disk
  and memory. CPU, memory, network rules and leases are enforced on the host,
  outside the guest.
- **Sandboxes reach the public internet only.** Private and internal addresses
  are refused, and any sandbox's network can be cut immediately.
- **Secrets your sandboxes use are never inside them.** A sandbox sees a
  placeholder, and the host puts the real value in on the way out
  ([secrets sandboxes never see](./security#secrets-sandboxes-never-see)).
- **Customers are separated in the database** by row-level security tied to the
  organization, and each part of the system connects with its own role holding
  only what that part needs.

[Isolation and account boundaries](./security) has the detail.

## Encryption

- **In transit:** every connection to Runtime, and from Runtime to its
  database, uses TLS, and the database's certificate is verified.
- **Copies of your volumes and snapshots** are encrypted with a key that
  belongs to your organization alone, before they leave the server. Deleting
  the organization destroys that key first, so those copies become unreadable
  immediately ([storage and backups](./storage#encryption-and-deletion)).
- **Each server's nightly backup** is encrypted with that server's own key
  before it leaves the server. It is kept 30 days, and its pieces leave the
  storage within 44, so what a closed organization had on that server is gone
  from these backups by then.
- **The nightly copy of our database** is encrypted to a key held offline, so
  neither the storage provider nor the website can read it.
- **Stored secrets** are sealed, never returned by any API, and never written
  into a sandbox.

## Sign-in and access

- **Single sign-on** over SAML or OIDC and **directory sync** over SCIM, free on
  every account ([single sign-on](./single-sign-on)).
- **Two-step sign-in** with a passkey or an authenticator app, which an owner
  can require of everyone in the account, and sign-in with a passkey alone
  ([two-step sign-in](./security#two-step-sign-in)).
- **Four roles** (owner, admin, developer, billing), read-only keys,
  compartments that wall a group of keys off from the rest of the account, and
  daily spending limits per key ([keys](./security#read-only-keys-and-daily-limits)).
- **An audit log** of every change to the account, who made it, from where and
  how, kept at least 400 days ([teams and the audit log](./teams)).

## Availability and recovery

- **The status page** publishes the API's uptime, checked from outside every two
  minutes, and a real sandbox started from outside every ten
  ([status](https://withruntime.com/status)).
- **Paid accounts are promised 99% API uptime** every month, with
  service credit paid automatically when a month falls short
  ([uptime promise](/legal/sla)).
- **The database** can be rewound to any moment in the last 24 hours, and a
  sealed copy goes off-site every night and is kept 30 days, locked so it cannot
  be deleted early. A restore from that copy was last tested on
  27 September 2026.
- **Volumes are backed up off their server every day.** A snapshot survives
  loss of its server once its off-server copy is checked, shown by
  `backedUp: true` ([storage and backups](./storage)). Every week one backed-up
  item is restored and checked against the checksum recorded when it was saved.

## How Runtime is run

The service uses the following operational controls.

- **Access.** Production is reached only by the people and systems that
  operate it, and actions on customers' resources are recorded.
- **Change.** Changes are in version control and pass repository checks before
  they are pushed. The checks cover formatting, dependency advisories, linting,
  types, builds and tests for the affected packages. A production website
  release passes the full check; going live is a separate, deliberate step.
- **Vulnerabilities.** Dependencies are checked against published advisories. Reports go to security@withruntime.com, as
  [security.txt](https://withruntime.com/.well-known/security.txt) says
  ([report a vulnerability](./security#report-a-vulnerability)).
- **Monitoring.** Security events, such as an account locked after wrong
  two-step codes, every sign-in to the operator's dashboard and a backup that
  did not complete, are reviewed automatically every ten minutes, and the
  operator is alerted to anything unusual. The servers' sign-in logs and the
  log of every release signed are copied off the servers every day and kept a
  year, where the key that writes them cannot delete them.
- **Incidents.** A written procedure covers containing an incident, keeping the
  evidence, finding who is affected and telling them without undue delay, as
  the [data processing addendum](/legal/dpa) promises.
- **Suppliers.** Every company that handles customer data is on the
  [subprocessors](/legal/subprocessors) page before it starts, under a data
  processing agreement.
- **Retention and deletion.** What is kept, and for how long, is in the
  [privacy policy](/legal/privacy).


---

<!-- https://withruntime.com/docs/vercel-ai-sdk -->

# Runtime for the Vercel AI SDK

Run an AI SDK harness agent (Claude Code, Codex, OpenCode, Pi and the rest) in a Runtime sandbox, or give any AI SDK model call four sandbox tools.

`createRuntimeSandbox()` is a sandbox provider for the AI SDK's `HarnessAgent`,
like `@ai-sdk/sandbox-vercel`. Pass it as the agent's `sandbox` and the harness,
its bootstrap and every command it runs live in a Firecracker microVM with its
own kernel, billed for the CPU it uses. The agent definition does not change.

## Harness agents

```bash no-run
npm install withruntime @ai-sdk/harness @ai-sdk/harness-claude-code
```

```ts no-run
import { HarnessAgent, type HarnessAgentAdapter } from "@ai-sdk/harness/agent";
import { createRuntimeSandbox } from "withruntime/ai-harness";

// harness: claudeCode from @ai-sdk/harness-claude-code, codex, opencode, pi, ...
export async function fixTests(harness: HarnessAgentAdapter) {
  const agent = new HarnessAgent({
    harness,
    sandbox: createRuntimeSandbox({ ports: [4000] }),
    instructions: "You are a careful coding assistant.",
  });
  const session = await agent.createSession();
  try {
    const result = await agent.generate({ session, prompt: "Fix the failing test." });
    return result.text;
  } finally {
    await session.destroy();
  }
}
```

The key comes from `RUNTIME_API_KEY`, or from `npx withruntime login` on this
machine, as in the rest of the SDK. Pass `createRuntimeSandbox({ runtime })` to share a
client, or `{ sandbox }` to run the harness in a sandbox you created and keep.

Bridge harnesses (Claude Code, Codex, OpenCode, Deep Agents) talk to a bridge in
the sandbox over a WebSocket, so give them a port: the agent uses the first one
in `ports`. Host-runtime harnesses such as Pi need none.

## Options

Every option is optional.

| Option              | What it does                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `create`            | How to create each sandbox: `funding`, `region`, `image`, `snapshot`, `vcpu`, memory, disk, time limit, `network` |
| `env`               | Set for every command, under the command's own `env`                                                              |
| `ports`             | Ports shared as Runtime previews; bridge harnesses use the first                                                  |
| `previewVisibility` | `private` (default): the endpoint carries a preview token; `public`: anyone with the address, paid only           |
| `previewTtlSeconds` | How long each endpoint's token lasts, 60 seconds to 7 days; one day by default                                    |
| `commandTimeoutMs`  | The longest a command may run: one hour by default, 24 hours at most                                              |
| `pauseOnStop`       | `session.stop()` pauses the sandbox, so a resumed session wakes the same machine                                  |
| `runtime`           | The client to use                                                                                                 |
| `sandbox`           | A sandbox you created; the provider never stops it                                                                |

## What runs in the sandbox

- **Commands** run under `bash` as the sandbox user, with passwordless `sudo`,
  in the session's working directory under `/workspace`. Output streams, so a
  long log is not cut at the size of one response. A command past its limit
  exits 124. `run` also takes `stdin` and `timeoutMs`, and aborting a command
  ends it in the sandbox too.
- **Files** are read and written atomically, with parent directories made for
  you. A file over 1 MiB is written under `/workspace`.
- **Ports** become previews at `runtimehost.com`, private unless you ask. An
  HTTPS endpoint carries its token in the link and in the
  `x-runtime-preview-token` header; a WebSocket endpoint sends it in the header.
- **Network policy.** `allow-all` is the public web, `deny-all` refuses every
  outbound connection, and `custom` reaches only the listed hosts and ranges,
  with `deniedCIDRs` refused. Changes apply immediately, to open connections too.
- **Bootstrap.** A harness's setup recipe runs once in each new sandbox before
  its first turn.

## Stop, resume and destroy

With a session id, each sandbox is named `ai-harness-<id>`. `session.destroy()`
stops it. `session.stop()` stops it too, or with `pauseOnStop` pauses it: its
files, memory and processes are kept, billed as paused storage
([pricing](./pricing#paused-storage)), and
`agent.createSession({ sessionId, resumeFrom })` wakes the same machine.

A missing or refused key raises the AI SDK's
`HarnessSandboxAuthenticationError`, so your application can tell configuration
from an outage.

## Tools for `generateText` and agents

Without a harness, `runtimeTools(sbx)` from `withruntime/ai` gives any AI SDK
model the four [framework tools](./frameworks#vercel-ai-sdk): `runtime_exec`,
`runtime_read_file`, `runtime_write_file` and `runtime_list_files`.

```ts
import { generateText, stepCountIs, type LanguageModel } from "ai";
import { Sandbox } from "withruntime";
import { runtimeTools } from "withruntime/ai";

export async function solve(model: LanguageModel, prompt: string) {
  await using sbx = await Sandbox.create();
  const { text } = await generateText({
    model,
    tools: runtimeTools(sbx),
    stopWhen: stepCountIs(20),
    prompt,
  });
  return text;
}
```

It needs the `ai` package, version 5 or later. Mastra agents take the same tools.

## What was verified

- On 25 September 2026 the provider ran under `@ai-sdk/harness` 1.0.124's own
  `HarnessAgent`, driven by a scripted harness adapter so no model was called,
  against a fake of the Runtime API behind the real API router: create, the
  bootstrap recipe, commands with env, stdin, timeouts and abort, files, private
  and public previews, network policy, pause, resume and stop.
- The same scripted agent against real sandboxes, including a WebSocket through
  a private preview as a bridge harness opens one, is written and has not run
  yet. No bridge harness (Claude Code, Codex) has run on Runtime yet.
- On 23 September 2026 `runtimeTools` ran in the AI SDK's own agent loop (AI SDK
  7.0.87) against real sandboxes without credit, driven by a scripted model.

Official reference checked 25 September 2026:
[AI SDK HarnessAgent](https://ai-sdk.dev/docs/ai-sdk-harnesses/harness-agent).


---

<!-- https://withruntime.com/docs/vercel-sandbox-alternative -->

# Runtime vs Vercel Sandbox

Runtime runs Firecracker microVMs and bills active CPU, like Vercel Sandbox. For an agent that mostly waits on a model, it costs **70% less**.

**The saving:** 1,000 one-minute runs of a 2 vCPU sandbox with 4 GiB cost **$0.64
on Runtime and $2.12 on Vercel**. At 100,000 runs a month, that is $63.89 against
$212.44, **$149 a month saved**. Your Vercel Sandbox code keeps working. Change one
import.

Comparing more than two providers? [Vercel Sandbox alternatives](/compare/vercel-sandbox-alternatives) ranks the other providers by the cost of the same job.

## Where Runtime is better

- **80% cheaper CPU.** Active CPU costs $0.025 an hour on Runtime and $0.128 on Vercel. Memory costs 65% less. Busier jobs save
  more. With both CPUs busy the whole minute, the example job costs $1.33 on
  Runtime and $5.68 on Vercel.
- **It pauses itself when idle.** After 300 seconds with no request, command, connection,
  traffic or CPU use, a Runtime sandbox pauses. While paused, it pays only paused storage,
  $0.08 per GB (10⁹ bytes) a month. The next request wakes it. Its processes keep running.
- **A written uptime promise.** Paid accounts get 99% API uptime a month,
  measured from outside. If a month falls short, 10% of that month's charges
  is returned as credit automatically ([Uptime Promise](/legal/sla)).
- **Memory survives a pause.** A paused Runtime sandbox wakes with its
  processes still running, kept while you have credit. A stopped Vercel sandbox
  keeps its filesystem, and its processes start again.
- **Forks keep memory too.** A Runtime fork copies a running sandbox with its
  memory and running processes. A Vercel snapshot or fork captures the
  filesystem, so processes start again.
- **Private ports by default.** A Runtime preview gives a port an HTTPS address
  that needs a token unless you make it public. Vercel's exposed ports are
  reachable at a public URL.
- **No platform to join.** Runtime needs no hosting plan, team or project.
  Prepaid credit from $10 is the whole account.
- **A one-line switch.** `withruntime/vercel` runs code written for Vercel
  Sandbox's SDK, in JavaScript and Python: commands, files, ports, snapshots and
  persistent sandboxes, with no Vercel project or token. Credit you add within 30 days of signing up is matched, up to $1,000 in total.
- **Single sign-on included.** SAML or OIDC sign-in, SCIM, roles and an audit
  log come with every Runtime account ([single sign-on](./single-sign-on)).
  Vercel sells SAML single sign-on as an add-on for Pro teams and keeps
  directory sync for Enterprise.
- **Your agent sets itself up.** It runs `npx withruntime sandboxes run -- ...`,
  shows you a link, and starts once you approve in the browser. No API key goes
  into a prompt or a config file. The [MCP server](./mcp) reuses the same
  connection.

**Also included:** a code interpreter, network allow and deny lists, secrets the
sandbox never sees, custom images, volumes backed up daily, a Linux desktop,
metrics, webhooks, OpenTelemetry export, S3, R2 and GCS bucket mounts, and identity tokens for AWS and Google Cloud. Paid
accounts add custom domains, TCP ports, dedicated outbound addresses and
WireGuard private networks. See [products](./products).

## At a glance

Vercel's figures come from its public pricing and documentation, checked
25 October 2026, at the rates of its default `iad1` region.

|                  | Runtime                                                                     | Vercel Sandbox                                       |
| ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
| Isolation        | Firecracker microVM, own kernel                                             | Firecracker microVM, own kernel                      |
| CPU billing      | $0.025 per active vCPU-hour, with a small floor                       | $0.128 per active CPU-hour              |
| Memory billing   | $0.0075 per reserved GiB-hour                                       | $0.0212 per provisioned GB-hour       |
| Plan             | None; prepaid credit from $10                                     | Hobby allowance free; usage beyond it needs Pro      |
| Free start       | 100 free hours of a 1 GB machine in the first 30 days, no card                          | 5 active CPU-hours and 420 GB-hours a month on Hobby |
| Session length   | No time limit: runs while it works, pauses itself after 300 seconds idle | 45 minutes on Hobby, 24 hours on Pro                 |
| Stop and resume  | Pause keeps files, memory and processes                                     | Stop keeps the filesystem; processes start again     |
| Snapshots, forks | Files, memory and running processes                                         | The filesystem                                       |
| Port URLs        | Private with a token by default                                             | Public                                               |

## Cost for the same job

Take 1,000 runs of a 2 vCPU sandbox with 4 GiB on Runtime and 4 GB on Vercel,
which gives 2 GB per vCPU. Each run lasts 60 seconds and keeps the CPU busy for
20 CPU-seconds. This is an agent that spends most of its time waiting for a model.

```
Runtime  CPU    1,000 × 20 s / 3,600 × $0.025      = $0.14
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0075 = $0.50
         Total                                        $0.64

Vercel   CPU    1,000 × 20 s / 3,600 × $0.128      = $0.71
         Memory 1,000 × 60 s / 3,600 × 4 × $0.0212 = $1.41
         Total                                        $2.12
```

- **Saving:** 70%, or $1.49 per 1,000 runs.
- **Per month:** at 100,000 runs, $63.89 on Runtime against $212.44 on Vercel.
- **Busier work:** with both CPUs busy for the whole minute, $1.33 on
  Runtime against $5.68 on Vercel, a 77% saving.

A GiB is about 7% larger than a GB, so Runtime's memory figure covers slightly
more. Creations, network, storage, plan fees, taxes and free allowances are excluded
from both. On Runtime, inbound traffic is free. Each account's first 100 GiB out a month is free, then $0.02 per GB (10⁹ bytes). See [pricing](./pricing) for
Runtime's terms.

## How to switch

Give your coding agent the one instruction in [migration](./migrate). It
replaces the Vercel calls on a branch, tests them on the free usage, and tells
you what you save each month. Your old code stays on the main branch until you
merge.

### Change one import

Runtime's SDK runs code written for Vercel Sandbox's SDK. Change the import and
set `RUNTIME_API_KEY`, or run `npx withruntime login` once:

```ts no-run
import { Sandbox } from "withruntime/vercel"; // was: from "@vercel/sandbox"
```

```python no-run
from withruntime.vercel import sandbox  # was: from vercel import sandbox
```

Sandboxes get Vercel's defaults: 2 vCPUs with 2048 MiB each, a 5-minute
timeout, and persistence. So `stop()` pauses a sandbox, and the next call or
`Sandbox.get({ name })` wakes it. Ports listed at create get public addresses.
`domain(port)` returns the address for that port. Sandboxes use the free usage first, then prepaid credit.

With no timeout, a sandbox has no time limit: it runs while it works. A timeout
over an hour works too. The sandbox object moves Runtime's hour-long limit on
toward it while your program runs. Users and groups (`createUser`,
`asUser`) and list filters, sorting and cursors work as on Vercel. A call
Runtime handles differently, such as Drives or other regions, throws
`NotSupportedError` before anything happens. It names what to use instead.
`VERCEL.md` in the package lists every mapping.

### Or port the calls

Vercel Sandbox:

```js
import { Sandbox } from "@vercel/sandbox";
const sandbox = await Sandbox.create();
const command = await sandbox.runCommand("echo", ["hello"]);
console.log(await command.stdout());
await sandbox.stop();
```

Runtime:

```ts
import { Sandbox } from "withruntime";
const box = await Sandbox.create();
try {
  console.log((await box.exec("echo hello", { check: true })).stdout);
} finally {
  await box.stop();
}
```

## When Vercel Sandbox may fit better

- **Regions and scale.** Vercel runs sandboxes in 19 regions, with up to 10,000
  concurrent sandboxes on Pro. Runtime runs in one US region.
- **Your app already lives on Vercel.** Sandboxes then share its account,
  billing and observability.

## Sources

Checked 23 September 2026; single sign-on and the firewall checked
27 September 2026.

- [Vercel Sandbox pricing and quotas](https://vercel.com/docs/sandbox/pricing)
- [Vercel SAML single sign-on](https://vercel.com/docs/saml)
- [Vercel Sandbox firewall](https://vercel.com/docs/sandbox/concepts/firewall)
- [Understanding Vercel Sandboxes](https://vercel.com/docs/sandbox/concepts)
- Runtime [pricing](./pricing), [security](./security) and [products](./products)


---

<!-- https://withruntime.com/docs/versioning -->

# API versions and deprecation

How the HTTP API is versioned, how a name that changes keeps working, and the
headers that tell your code a path is being retired. The same rules cover the SDKs,
the CLI and the MCP tools.

## Versions

Every path starts with `/v1`. The OpenAPI document at
`https://api.withruntime.com/v1/openapi.json` gives the version of the API in
`info.version`; it is 0.2.0.

The 0.1.0 routes under `/v1/resources` were removed on 22 September 2026. Each
returns `410` with the code `upgrade_required`, and `details.replacement` names
the route that replaced it. [The migration guide](./migrate) maps each old call
to its new one.

## When a name changes

Each product has one plural name in every path, SDK call, command and MCP tool:
`/v1/sandboxes`, `runtime.sandboxes`, `runtime sandboxes`, `runtime_sandboxes`.
When a name changes, the old one keeps working for 30 days:

1. **From the day the new name ships**, a request to the old path is served as
   the new one. Each response carries a `Warning` header with the new name and a
   `Link` to the new path (`rel="successor-version"`). The SDKs and the CLI print
   the warning once; an MCP response carries it as `warning`.
2. **Once the last day is set**, responses also carry `Deprecation` (RFC 9745, the
   day the rename shipped) and `Sunset` (RFC 8594, the last day), and the warning
   names that day.
3. **From the last day**, the old name returns `410` with the code
   `name_retired`, and its `hint` names the new one.

A field renamed in a response follows the same 30 days, with the same code once
it stops.

```http
HTTP/2 200
Warning: 299 runtime "/v1/tunnel is now /v1/networks/wireguard."
Link: </v1/networks/wireguard>; rel="successor-version"
```

## What to do

- Read `Warning` and `Sunset` on responses, or let the SDK print them. Move to
  the new name before its last day.
- Treat `410 name_retired` and `410 upgrade_required` as a sign that the code must
  change, never as a reason to retry. The `hint` names what to call instead.
- The [API reference](./api#versions) holds the same rules beside every route.