Skip to content
DashboardGet API key

Copy a sandbox

View .md
POST

Start a new sandbox with a copy of this one's disk. The source keeps running. The copy is billed like a create: $0.01, then machine time, with the same plan, balance and limit checks, and keeps the source's size, timeout, name and metadata.

The source must be running or stopped, and not ephemeral. Not available with test-mode keys.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • sandboxIdstringrequired

    Sandbox ID.

Responses

202Accepted. The copy is starting.
  • sandboxobjectrequired

    An isolated Linux machine. It is billed per second while starting or running (with a one-minute minimum per run), plus $0.01 each time it is created or resumed. A stopped sandbox costs nothing.

    17 properties
    • idstringrequired
    • namestringnullable

      Your label for it, set with name on create. Copies keep their source's name.

    • statusstringrequired
      • starting: accepted, the machine is being prepared. Commands and file calls wait for it.
      • running: the machine is up. Machine time is billed.
      • stopping: a stop was requested; billing already ended.
      • stopped: the disk is kept until expiresAt, and POST /resume starts it again. Not billed.
      • failed: the machine could not start or failed on its host. See failureReason. A sandbox that fails before it ever runs gets its start fee back.
      One ofstartingrunningstoppingstoppedfailed
    • sizestringrequired

      Machine size, and its price per hour of machine time: - small: 2 vCPU, 4 GB RAM. $0.0225/h. - default: 4 vCPU, 8 GB RAM. $0.045/h. - large: 8 vCPU, 16 GB RAM. $0.09/h.

      One ofsmalldefaultlarge
    • timeoutSecondsintegerrequirednullable

      The sandbox is stopped automatically this many seconds after it started (or was last resumed). Checked every minute. null when auto-stop is off: it runs until you stop it, or until the balance, the spend cap or leaving the paid plan stops it.

    • ephemeralbooleanrequired

      Created with ephemeral: true. Its disk is never saved: a stop erases it, expiresAt is the moment it stopped, and resume answers 409 sandbox_expired.

    • metadataobjectrequired

      What you attached when creating it. Kept by Zavu only; never visible inside the machine.

      1 properties
      • {key}string
    • startedAtstring<date-time>nullable

      When the current or last run was accepted.

    • stoppedAtstring<date-time>nullable

      When the last run ended. Null while starting or running.

    • expiresAtstring<date-time>nullable

      Present while stopped: when the disk is deleted, 14 days after the stop, or the stop itself for an ephemeral sandbox. After it, resume answers 409 sandbox_expired.

    • stopReasonstringrequirednullable

      Why the last run ended, while stopping or stopped; null otherwise. requested: you stopped it, from the API or the dashboard. timeout: its timeoutSeconds passed. insufficient_balance and spend_cap_reached: the balance or the monthly spend cap no longer covered 15 more minutes. plan: the team left its paid plan. provider: it ended on its host. The sandbox.stopped project webhook carries the same value.

      One ofrequestedtimeoutinsufficient_balancespend_cap_reachedplanprovidernull
    • costTotalnumberrequired

      USD charged for this sandbox so far: start fees plus machine time. Machine time of a running sandbox is settled every five minutes, so this lags by up to five minutes until it stops.

    • failureReasonstringnullable

      Why it failed. Present only when status is failed.

    • forkedFromSandboxIdstringnullable

      The sandbox this one is a copy of, when it was made with POST /v1/sandboxes/{sandboxId}/fork.

    • fromSnapshotIdstringnullable

      The project's saved snapshot it started from. Null when it started blank, as a copy, or from another team's shared snapshot.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
400A test-mode key.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
402`paid_plan_required`, `insufficient_balance` or `spend_cap_reached`, as on create.
  • codestringrequired
  • messagestringrequired
  • detailsobject
403`plan_limit_reached`: 10 sandboxes are already starting or running.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sandbox not found, or it belongs to another project.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409`sandbox_not_ready`: the source is not running or stopped. `sandbox_ephemeral`: an ephemeral sandbox's disk is never saved, so it cannot be copied.
  • codestringrequired
  • messagestringrequired
  • detailsobject
429`daily_limit_exceeded`: 200 starts today.
  • codestringrequired
  • messagestringrequired
  • detailsobject
503`sandbox_unavailable`: no capacity right now. The start fee is returned.
  • codestringrequired
  • messagestringrequired
  • detailsobject