Copy Sandbox
Boot one or more new sandboxes from a running or suspended source, restoring filesystem, memory, and running processes so each copy warm-starts. A running source is copied from the executor hosting it; a suspended source is copied from the snapshot its suspend produced. Copies inherit the source’s image, resources, entrypoint, network policy, and exposed ports. Takes no request body.
- 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.
timesandnameare query parameters.
Endpoint
Example Request
Example Response
Fanning Out
Passtimes 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:name explicitly to give an unnamed source’s copies a name.
Derived names are validated before any copy is created:
400if 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-Nappended.409if 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
A200 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.
Related
Snapshot and Clone
Lifecycle
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The running or suspended source sandbox ID or name.
Query Parameters
Number of copies to create from the source sandbox. Defaults to 1.
x >= 1Name 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.