Skip to content

Create a sandbox

Synchronous: waits up to 10 seconds for the sandbox to start and answers with the sandbox as it is by then, usually running. A sandbox that could not be started is answered too, with status failed and a statusReason. 400 image_not_found, 400 for a bot the organization doesn't have, 403 access_denied naming bots.pass, 403 image_access_denied, 409 quota_exceeded.

POST
https://sandboxes.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/sandboxes

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    UUID or prefixed ID (org_…)

  • projectIdstringrequired

    UUID or prefixed ID (prj_…)

Header parameters

  • Idempotency-Keyoptionalstring

    Makes a retry safe: the same key and request get the stored response.

    pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

  • imagestringrequired

    A container image the caller may pull, by tag or digest.

    minLength: 1
  • botoptionalstring

    A Bot of the organization, by its ID (bot_…). Code in the sandbox can get the Bot's short-lived API keys from the metadata endpoint, so give it only what that code may do. Needs bots.pass on the Bot.

    pattern: ^bot_[a-z0-9]{12}$
  • commandoptionalarray ofstring

    Run when the sandbox starts, in place of the image's own. At most 64 arguments, 8 KiB in all.

  • diskGiBoptionalinteger
    maximum: 50, minimum: 1
    Default: 5
  • envoptionalmap ofstring

    At most 64 variables, 32 KiB in all. Names match ^[A-Za-z_][A-Za-z0-9_]*$.

  • idleSecondsoptionalinteger

    0, or 60 to 86400.

    maximum: 86400, minimum: 0
    Default: 300
  • memoryMiBoptional512or1024or2048or4096or8192or16384
    Default: 512
  • nameoptionalstring

    Defaults to the sandbox's slug.

    maxLength: 63, minLength: 1
  • networkoptionaldefaultornone

    none: no network device; nothing in the sandbox can reach any network. Not with vpc. Not available in every region yet: where it isn't, a create that names it is 400.

    Default: "default"
  • serveoptionalobject | null

    Run the image's entrypoint and command as a service that serves HTTP on port, with PORT set. Leave command out. Null, the default, runs no service. Not available in every region yet: where it isn't, a create that names it is 400.

    3 properties
    • maxConcurrencyintegerrequired

      The most requests the sandbox takes at once.

      maximum: 1000, minimum: 1
    • portintegerrequired

      The port the service listens on, given to it as PORT.

      maximum: 65535, minimum: 1
    • startupTimeoutSecondsintegerrequired

      How long the service may take to open its port after the sandbox starts.

      maximum: 3600, minimum: 1
  • vcpusoptional1or2or4or8
    Default: 1
  • vpcoptionalobject | null

    Reach a VPC: its connections into the VPC come from an address in the subnet, and its internet traffic goes through the VPC's NAT gateway (IPv4 only). Nothing in the VPC can connect to the sandbox. Needs network.subnets.get on the subnet, a subnet of the sandbox's project. Null, the default, reaches only the internet.

    1 properties
    • subnetstringrequired

      The subnet's ID, sbn_….

      pattern: ^sbn_[a-z0-9]{12}$

Returns

201

The sandbox.

JSON
  • botobject | nullrequired

    The Bot whose short-lived API keys code in the sandbox gets from the metadata endpoint; null with none. Set at create only.

    2 properties
    • idstringrequired

      The Bot's ID, bot_….

    • namestring | nullrequired

      The Bot's name on a read of one sandbox; null in lists, and when the organization no longer has the Bot.

  • createdAtstringrequired
    format: date-time
  • diskGiBintegerrequired
  • egressBlockedbooleanrequired

    Whether EZGH has turned off this sandbox's network. It keeps running, and nothing in it can reach the internet. Contact support.

  • egressIpv4string | nullrequired

    The address its outbound IPv4 connections come from. Null unless it is running, and always null for a sandbox in a VPC or with network none.

  • egressIpv6string | nullrequired

    The address its outbound IPv6 connections come from. Null unless it is running, and always null for a sandbox in a VPC or with network none.

  • envNamesarray ofstringrequired

    The names of its environment variables, sorted. Their values are never returned.

  • hasCommandbooleanrequired

    Whether it was created with a command. The command is never returned.

  • idstringrequired
    format: uuid
  • idleSecondsintegerrequired

    Suspended after this long with no command, file call or open stream; 0 is never.

  • imageobjectrequired

    The image as it was asked for, and the repository and digest it was resolved to when the sandbox was created. Every later start uses that digest.

    3 properties
    • digeststringrequired
    • referencestringrequired
    • repositorystringrequired
  • lastActivityAtstring | nullrequired

    When a command or a file call last used it, to within about a minute and a half while it runs; idleSeconds counts from the exact time.

    format: date-time
  • memoryMiBintegerrequired
  • memoryRestoredboolean | nullrequired

    Whether its last start, resume or restart carried its processes on (true: a resume that restored its memory) or started it again from its disk (false: a start after a stop, a restart, or a resume that could not restore its memory). Null until the first one after its creation.

  • namestringrequired
  • networkdefaultornonerequired

    default, or none: a sandbox with no network device, which reaches nothing and has no egress addresses.

  • organizationIdstringrequired
    format: uuid
  • projectIdstringrequired
    format: uuid
  • regionstringrequired
  • resourceNamestringrequired
  • serveobject | nullrequired

    The service the sandbox runs: the image's entrypoint and command, serving HTTP on port. Null for a sandbox that runs no service.

    3 properties
    • maxConcurrencyintegerrequired

      The most requests the sandbox takes at once.

      maximum: 1000, minimum: 1
    • portintegerrequired

      The port the service listens on, given to it as PORT.

      maximum: 65535, minimum: 1
    • startupTimeoutSecondsintegerrequired

      How long the service may take to open its port after the sandbox starts.

      maximum: 3600, minimum: 1
  • slugstringrequired
  • startedAtstring | nullrequired
    format: date-time
  • statusstartingorrunningorsuspendingorsuspendedorresumingorstopping+4 morerequired

    Clients treat any other value as unknown.

  • statusReasonstring | nullrequired

    Why it has its status, when there is something to say: idle, drain, host_lost, host_rebooted, suspend_failed, no_capacity, vpc_unavailable, image_prepare_failed, start_failed, reboot_loop, guest_halted, snapshot_unusable, interrupted or operator_hold (EZGH stopped it, and it can't be started or resumed until support lifts the hold); clients treat others as unknown.

  • suspendedAtstring | nullrequired
    format: date-time
  • updatedAtstringrequired
    format: date-time
  • vcpusintegerrequired
  • vpcobject | nullrequired

    The VPC and subnet the sandbox reaches, set at create; null for a sandbox that reaches only the internet.

    2 properties
    • subnetstringrequired

      The subnet's ID, sbn_….

    • vpcstringrequired

      The VPC's ID, vpc_….

  • vpcIpv4string | nullrequired

    The address in the subnet its IPv4 connections into the VPC come from. Null unless it is running in a VPC.

  • vpcIpv6string | nullrequired

    The address in the subnet its IPv6 connections into the VPC come from. Null unless it is running in a VPC.

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close