Skip to main content
POST
Copy a sandbox
Boot one or more new sandboxes from a running or suspended source, restoring filesystem, memory, and running processes so each copy warm-starts.
  • This path accepts either the sandbox ID or the sandbox name.
  • The source must be running or suspended. Any other state returns 400 Bad Request.
  • A running source is copied from the executor hosting it. A suspended source is copied from the snapshot its suspend already produced, so a copy does not leave a new checkpoint behind for you to clean up.
  • Copies inherit the source’s image, resources, entrypoint, network policy, and exposed ports.
  • The request takes no body. times and name are query parameters.

Endpoint

Example Request

Example Response

Fanning Out

Pass times to create several copies from the same source in one call. Each copy is an independent sandbox with its own ID.

Naming Copies

Sandbox names are unique per namespace, so copies cannot reuse the source’s name. Names are derived instead:
Naming matters for lifecycle: only named sandboxes can be suspended and resumed. An unnamed copy terminates at its idle timeout instead. A named source therefore keeps its copies named by default, so a copy behaves like the sandbox it came from. Pass name explicitly to give an unnamed source’s copies a name. Derived names are validated before any copy is created:
  • 400 if a derived name is malformed, or exceeds the 63-character DNS label limit once suffixed. A base that fits on its own can still overflow with -N appended.
  • 409 if a derived name is already claimed by a live sandbox in the namespace. This is checked up front, so a rejected request creates nothing — re-running the same named fan-out is safe and will not leave partial copies behind.

Partial Failures

A 200 means every requested copy is running. Two other statuses return the same body shape, so inspect each entry’s status to see which copies succeeded:
  • 422 — one or more copies failed before becoming ready.
  • 504 — one or more copies did not become ready within the timeout.

Snapshot and Clone

Capture a reusable artifact and restore it into new sandboxes later.

Lifecycle

Create, suspend, resume, and terminate sandboxes.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

sandbox_id
string
required

The running or suspended source sandbox ID or name.

Query Parameters

times
integer

Number of copies to create from the source sandbox. Defaults to 1.

Required range: x >= 1
name
string

Name for the copies. Used verbatim when times is 1, and suffixed -1..-N when it is greater, since sandbox names are unique per namespace. When omitted, a named source produces <source-name>-copy (suffixed the same way) and an unnamed source produces unnamed copies. Named copies can be suspended and resumed; unnamed ones terminate at their idle timeout.

Response

All requested sandbox copies are running

source_sandbox_id
string
required

The sandbox the copies were made from.

sandboxes
object[]
required

One entry per requested copy, in creation order. On a 422 or 504 the entries report per-copy status, so inspect each one to see which copies became ready.