---
title: "Copies of a sandbox as it is now: files, memory and running processes."
method: POST
path: "/v1/sandboxes/{id}:fork"
tags: ["sandboxes"]
---

# Copies of a sandbox as it is now: files, memory and running processes.

`POST /v1/sandboxes/{id}:fork`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}:fork`
- Auth: HTTP bearer

A running sandbox is paused for the moment it takes to snapshot it (usually well under a second), then woken again. Answers once the copies are running: {sandboxes, snapshot}, where snapshot is null unless keepSnapshot. Each copy has the source's vCPUs, memory, disk and CPU (cpu and cpuFloorMillis), is quoted as a create with them would be, and runs on its host. A fork that fails after its snapshot is taken answers with the failing step's error; details.startedSandboxIds names the copies that did start, which keep running until stopped.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `count` integer: How many copies: 1 to 100 on prepaid credit, 1 to 4 without credit. One fork takes at most a quarter of its server's free memory.
  - `name` string: Your own handle for the resource. Letters, digits, dot, dash, underscore.
  - `labels` object: Your own key/value tags, at most 32. Filter lists with label=key:value.
  - `secrets` string[]: The egress secrets the copies may use: a narrower list than the source's. Omit it and each copy keeps the source's list (every secret that reaches it, when the source names none). A name the source may not use is refused.
  - `keepSnapshot` boolean: Keep the snapshot the copies started from, to start more later (it is billed as snapshot storage). By default it is deleted when the fork ends, whether every copy started or not, and nothing is billed for it.
  - `funding` 'trial' | 'paid': Accepted and not read: copies run on what the account's new sandboxes run on, as for a create. On an account without credit, each copy must fit the limits without credit (it has the source's size) and takes one of its running slots.

## Response `200`

Success

- object
  - `sandboxes` object[], required
    - `id` string, required: Resource identifier (UUID).
    - `kind` 'sandbox', required
    - `name` string, nullable
    - `labels` object: Your own key/value tags, at most 32. Filter lists with label=key:value.
    - `status` 'pending' | 'active' | 'paused' | 'stopping' | 'stopped', required: Deprecated: read state. An older, coarser name for it, kept for older clients.
    - `state` 'starting' | 'running' | 'pausing' | 'paused' | 'resuming' | 'stopping' | 'stopped', required
    - `region` string, required
    - `funding` 'trial' | 'paid', required
    - `vcpu` integer
    - `memoryMiB` integer
    - `diskMiB` integer
    - `cpu` 'shared' | 'reserved'
    - `cpuFloorMillis` integer
    - `pausable` boolean
    - `timeoutSeconds` integer: Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle.
    - `onTimeout` 'pause' | 'stop' | 'delete': What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name.
    - `idlePauseSeconds` integer: Pauses after this many idle seconds; 0 is never.
    - `idlePauseUnusedOnly` boolean: True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity.
    - `autoWake` boolean: A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port.
    - `persistent` boolean: It has no time limit and is not paused for being idle unless idlePauseSeconds says so.
    - `diskKept` boolean: Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it.
    - `lastActiveAt` string, date-time, nullable: The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused).
    - `createdAt` string, date-time, required
    - `readyAt` string, date-time, nullable: When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended.
    - `expiresAt` string, date-time, required: Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself.
    - `endsAt` string, date-time, nullable: When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running.
    - `endedAt` string, date-time, nullable
    - `stopReason` string, nullable: Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. 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 and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox.
    - `pausedAt` string, nullable
    - `pausedExpiresAt` string, nullable: When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit.
    - `memoryRestored` boolean
    - `placement` string, nullable: Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed.
    - `chargedMicros` integer: Settled, in microdollars (1,000,000 = $1).
    - `heldMicros` integer: Deprecated, kept for older clients: read chargedMicros and GET /v1/usage.
    - `rates` object
    - `envNames` string[]: The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown.
    - `secrets` string[], nullable: The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox.
    - `secretsEnforced` boolean: On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds.
    - `simulated` boolean
    - `replayed` boolean: Present and true when an Idempotency-Key replay answered.
  - `snapshot` object, nullable, required

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)