Create a sandbox

Create a new sandbox from a snapshot. Provide at most one of snapshot_id or snapshot_name; if neither is provided, the server uses the default snapshot.

POST /v2/sandboxes/boxes

Error

A valid request URL is required to generate request examples

201

{
  "cpu_millicores": 123,
  "created_at": "<string>",
  "created_by": "<string>",
  "dataplane_url": "<string>",
  "delete_after_stop_seconds": 123,
  "fs_capacity_bytes": 123,
  "id": "<string>",
  "idle_ttl_seconds": 123,
  "mem_bytes": 123,
  "mount_config": {
    "auth": {
      "aws": {
        "access_key_id": {
          "is_set": true,
          "value": "<string>"
        },
        "secret_access_key": {
          "is_set": true,
          "value": "<string>"
        }
      },
      "gcp": {
        "service_account_json": {
          "is_set": true,
          "value": "<string>"
        }
      }
    },
    "mounts": [
      {
        "id": "<string>",
        "mount_path": "<string>",
        "s3": {
          "bucket": "<string>",
          "region": "<string>",
          "endpoint_url": "<string>",
          "path_style": true,
          "prefix": "<string>"
        },
        "type": "s3",
        "cache": {
          "max_size_bytes": 1,
          "writeback_seconds": 1
        },
        "read_only": true,
        "contexthub": {
          "repo": "<string>",
          "initial_pull_only": true
        },
        "gcs": {
          "bucket": "<string>",
          "prefix": "<string>"
        },
        "git": {
          "remote_url": "<string>",
          "ref": {
            "name": "<string>"
          },
          "refresh_interval_seconds": 2
        }
      }
    ]
  },
  "name": "<string>",
  "preserve_memory_on_stop": true,
  "proxy_config": {
    "access_control": {
      "allow_list": [
        "<string>"
      ],
      "deny_list": [
        "<string>"
      ]
    },
    "callbacks": [
      {
        "match_hosts": [
          "<string>"
        ],
        "ttl_seconds": 1830,
        "url": "<string>",
        "full_request": true,
        "request_headers": [
          {
            "name": "<string>",
            "is_set": true,
            "value": "<string>"
          }
        ]
      }
    ],
    "no_proxy": [
      "<string>"
    ],
    "rules": [
      {
        "name": "<string>",
        "aws": {
          "access_key_id": {
            "is_set": true,
            "value": "<string>"
          },
          "secret_access_key": {
            "is_set": true,
            "value": "<string>"
          }
        },
        "enabled": true,
        "gcp": {
          "scopes": [
            "<string>"
          ],
          "service_account_json": {
            "is_set": true,
            "value": "<string>"
          }
        },
        "headers": [
          {
            "name": "<string>",
            "is_set": true,
            "value": "<string>"
          }
        ],
        "match_hosts": [
          "<string>"
        ],
        "match_paths": [
          "<string>"
        ],
        "type": "<string>"
      }
    ]
  },
  "size_class": "<string>",
  "snapshot_id": "<string>",
  "status": "<string>",
  "status_message": "<string>",
  "stopped_at": "<string>",
  "updated_at": "<string>",
  "updated_by": "<string>",
  "vcpus": 123
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

Authorizations

API KeyTenant IDBearer Auth

X-API-Key · string · header · required

Body

application/json

cpu_millicores · integer

CPUMillicores optionally requests CPU at millicore granularity (e.g. 500 = 0.5 vCPU); takes precedence over VCPUs. Fractional (sub-vCPU) values are not available for every sandbox.

delete_after_stop_seconds · integer

env_vars · object

Show child attributes

fs_capacity_bytes · integer

idle_ttl_seconds · integer

mem_bytes · integer

mount_config · object

Show child attributes

name · string

preserve_memory_on_stop · boolean

PreserveMemoryOnStop, when true, suspends the sandbox's memory on a voluntary stop (idle timeout or explicit stop) so the next start resumes from where it left off. Default false discards memory and keeps only the filesystem, so the next start is a cold boot. Restarts triggered by infrastructure maintenance always preserve memory regardless of this setting.

proxy_config · object

Show child attributes

restore_memory · boolean

RestoreMemory selects how the sandbox handles a snapshot's captured memory:

nil → if-present: resume from memory when the snapshot has it, else cold-boot (default). true → always: resume from memory; rejected if the snapshot has none. false → never: always cold-boot.

Applies to this request only.

snapshot_id · string

snapshot_name · string

tag_value_ids · string[]

vcpus · integer

Response

201

application/json

Created

cpu_millicores · integer

created_at · string

created_by · string

dataplane_url · string

delete_after_stop_seconds · integer

fs_capacity_bytes · integer

id · string

idle_ttl_seconds · integer

mem_bytes · integer

mount_config · object

Show child attributes

name · string

preserve_memory_on_stop · boolean

proxy_config · object

Show child attributes

size_class · string

snapshot_id · string

status · string

status_message · string

stopped_at · string

updated_at · string

updated_by · string

vcpus · integer