Fork a machine

POST

sandboxes

{id}

fork

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/fork" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "count": 2,
  "timeout": 300
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
children = sandbox.fork(n=2, timeout=300)

// sandbox is returned by Sandbox.create or Sandbox.connect.
const children = await sandbox.fork(2, 300);

{
  "operationID": "<string>",
  "snapshotID": "<string>",
  "capture": {
    "sourcePreserved": true,
    "sourceBilling": "<string>",
    "capturedAtMs": 123,
    "freezeNanos": 123,
    "sourceResumed": true,
    "timing": {
      "incremental": true,
      "dirtyMemoryBytes": 123,
      "totalNanos": 123,
      "pauseNanos": 123,
      "dumpNanos": 123,
      "diskReflinkNanos": 123,
      "adoptNanos": 123,
      "cleanupNanos": 123,
      "resumeNanos": 123,
      "publicationNanos": 123
    }
  },
  "status": "<string>",
  "results": [
    {
      "index": 123,
      "status": 123,
      "operationID": "<string>",
      "response": {
        "alias": "<string>",
        "clientID": "<string>",
        "domain": {},
        "envdAccessToken": "<string>",
        "envdVersion": "<string>",
        "grace_deadline": {},
        "idle_timeout": {},
        "kind": "<string>",
        "last_activity": {},
        "machine_state": "<string>",
        "paused_at": {},
        "sandboxID": "<string>",
        "templateID": "<string>",
        "trafficAccessToken": {},
        "wake_reason": {},
        "warnings": [
          {}
        ],
        "code": 123,
        "message": "<string>",
        "error_code": "<string>",
        "limit": {
          "limit": "<string>",
          "maximum": 123,
          "usage": 123,
          "next_action": "<string>",
          "reset_at": 123
        },
        "operationID": "<string>",
        "status": "<string>"
      }
    }
  ]
}

Authentication

Send your scoped bearer token in the Authorization: Bearer <BEAD_TOKEN> header, or send your API key in X-API-Key.

Parameters

string

required

Machine identifier returned by creation.

string

required

Caller-generated durable retry key: lowercase ASCII letters, digits, and hyphens only. Reuse the same key and body after a connection failure. Minimum length: 1. Maximum length: 255.

Request body

The JSON body is required.

integer

required

Number of child machines to create. Minimum: 1. Maximum: 20.

integer

default:300

Funded execution timeout per child in seconds. Minimum: 1. Maximum: 86400.

boolean

default:false

Must be false; fork does not inherit credential profiles. Use a consented snapshot to copy them.

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/fork" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "count": 2,
  "timeout": 300
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
children = sandbox.fork(n=2, timeout=300)

// sandbox is returned by Sandbox.create or Sandbox.connect.
const children = await sandbox.fork(2, 300);

Response

202

Fork capture or one or more children are pending.

string

required

Fork batch UUID to poll.

string

required

Snapshot shared by the fork children.

object | null

required

Memory capture result and source recovery details. May be null.

Show Properties

boolean

required

Whether the source was preserved for recovery.

string

required

Who pays for the source after capture. Allowed values: "platform", "tenant".

integer

required

Capture timestamp in Unix milliseconds.

integer

required

Source freeze duration in nanoseconds.

boolean

required

Whether the source resumed after capture.

object

required

Time spent in each capture stage.

Show Properties

boolean

required

Whether this capture used an incremental memory dump.

integer

required

Allocated memory dump bytes before flattening.

integer

required

Total capture time in nanoseconds.

integer

required

Pause time in nanoseconds.

integer

required

Memory dump time in nanoseconds.

integer

required

Disk clone time in nanoseconds.

integer

required

Snapshot adoption time in nanoseconds.

integer

required

Cleanup time in nanoseconds.

integer

required

Source resume time in nanoseconds.

integer

required

Publication time in nanoseconds.

string

required

Whether any children are still pending. Allowed values: "pending", "completed".

object[]

required

Ordered child results; a failed child has its own error response.

Show Properties

integer

required

Zero-based request index.

integer

required

HTTP status for this member; 202 means it is still pending.

string

Operation UUID for a pending member.

object

Machine connection fields on success, or an error body on failure. Accepts object or object or object.

Show Properties

string

Alias of the template

string

deprecated

Identifier of the client

string | null

Base domain where the sandbox traffic is accessible May be null.

string

Access token used for envd communication

string

Version of the envd running in the sandbox

string | null

End of the credit grace period as an RFC 3339 timestamp, or null when funded. May be null.

integer | string | null

Seconds without activity before a persistent machine pauses, or never to disable idle pause. Persistent machines default to 900 seconds; numeric values must be 300–86400. May be null. Accepts integer or string (“never”).

string

Lifetime policy: temporary expires at its timeout; persistent retains state until explicit deletion or the end of credit grace. Allowed values: "temporary", "persistent".

string | null

Most recent activity as an RFC 3339 timestamp, or null when no activity was recorded. May be null.

string

Current lifecycle state including running, idle-paused, waking, credit-grace, lost, or deleted. Allowed values: "running", "idle-paused", "waking", "credit-grace", "lost", "deleted".

string | null

Time the machine last paused as an RFC 3339 timestamp, or null when it has not paused. May be null.

string

Identifier of the sandbox

string

Identifier of the template from which is the sandbox created

string | null

Token required for accessing sandbox via proxy. May be null.

string | null

Reason for the last wake or lifecycle transition, or null when none is recorded. May be null.

object[]

Lifecycle or credit grace warnings attached to this machine. Additional keys accept any values.

integer

HTTP status code.

string

Explanation of the failed request.

string

Stable error identifier when supplied; use it to decide how to recover.

object

The resource limit that blocked the request.

Show Properties

string

required

Name of the exhausted resource.

integer

required

Allowed amount of this resource.

integer

required

Current usage counted against the limit.

string

required

Action you can take to proceed.

integer

Unix time in seconds when this time window resets.

string

Operation UUID.

string

Current operation state.

207

All child attempts finished; inspect each member status. The response fields are the same as the success body above.

Errors

Status	Meaning
400	Invalid request values, unsupported bounds, or malformed JSON.
401	Authentication credential is missing or rejected.
402	Insufficient prepaid credit (`insufficient_credit`) to fund the requested machine attempts.
403	The credential lacks the required scope.
404	The requested resource does not exist or is outside your organization.
409	Request key reused with a different body (`idempotency_request_mismatch`), or resource ownership/state conflicts.
413	Request body exceeds the route limit.
429	Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next_action and Retry-After when present.
503	Service or persistence is temporarily unavailable.

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/fork" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "count": 2,
  "timeout": 300
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
children = sandbox.fork(n=2, timeout=300)

// sandbox is returned by Sandbox.create or Sandbox.connect.
const children = await sandbox.fork(2, 300);

{
  "operationID": "<string>",
  "snapshotID": "<string>",
  "capture": {
    "sourcePreserved": true,
    "sourceBilling": "<string>",
    "capturedAtMs": 123,
    "freezeNanos": 123,
    "sourceResumed": true,
    "timing": {
      "incremental": true,
      "dirtyMemoryBytes": 123,
      "totalNanos": 123,
      "pauseNanos": 123,
      "dumpNanos": 123,
      "diskReflinkNanos": 123,
      "adoptNanos": 123,
      "cleanupNanos": 123,
      "resumeNanos": 123,
      "publicationNanos": 123
    }
  },
  "status": "<string>",
  "results": [
    {
      "index": 123,
      "status": 123,
      "operationID": "<string>",
      "response": {
        "alias": "<string>",
        "clientID": "<string>",
        "domain": {},
        "envdAccessToken": "<string>",
        "envdVersion": "<string>",
        "grace_deadline": {},
        "idle_timeout": {},
        "kind": "<string>",
        "last_activity": {},
        "machine_state": "<string>",
        "paused_at": {},
        "sandboxID": "<string>",
        "templateID": "<string>",
        "trafficAccessToken": {},
        "wake_reason": {},
        "warnings": [
          {}
        ],
        "code": 123,
        "message": "<string>",
        "error_code": "<string>",
        "limit": {
          "limit": "<string>",
          "maximum": 123,
          "usage": 123,
          "next_action": "<string>",
          "reset_at": 123
        },
        "operationID": "<string>",
        "status": "<string>"
      }
    }
  ]
}

Start here

Endpoints

Fork a machine

Authentication

Parameters

Request body

Response

202

207

Errors

​Authentication

​Parameters

​Request body

​Response

​202

​207

​Errors

Authentication

Parameters

Request body

Response

202

207

Errors