Skip to content
التنقل

Detach a volume from a sandbox

The sandbox unmounts the volume (its file system written out first) and has it no more; the volume stays where it is, with what it holds, for any sandbox of its region. A volume's id or name takes away its read-write mount alone; a snapshot's id (dsnap-…, slice D7) takes away the sandbox's read-only mount of that snapshot, and the node's view of it with it, the volume and the snapshot deleted since or not, answered with the snapshot. ?force=true: a mount that a process still uses is taken away all the same. Takes write.

DELETE
https://api.glac.ai/v1/sandboxes/{id}/volumes/{volume}

التفويض

  • apiKeyHTTPrequired

معاملات المسار

  • idstringrequired

    The sandbox's id or name.

  • volumestringrequired

    The volume's id or name; or the id of a snapshot of a volume (dsnap-…) the sandbox has mounted read-only.

معاملات الاستعلام

  • forceoptionalboolean

    Take the mount away while a process uses it.

Returns

200

The volume, detached; a snapshot's read-only mount taken away, the snapshot.

JSON

واحد مما يلي:

  • Volume
    • managed_byobject | nullrequired

      The database it is under (/v1/databases), or the installation of a Managed Application it is part of (/v1/installations), which changes it alone: every other call that would change it is refused, 409 managed_by_database or managed_by_installation. Null: none's.

      • objectdatabaseأوinstallationrequired
      • idstringrequired
    • idstringrequired

      Its id.

      pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
    • objectstringrequired
    • namestring | nullrequired
    • size_bytesintegerrequired

      The most it holds: a whole number of 4 KiB blocks.

      format: int64 · minimum: 16777216
    • used_bytesintegerrequired

      What it holds, logically: the 4 KiB blocks written to it and not discarded since (a guest's fstrim, which its node asks for every minute, gives them back), its file system's own among them. What it is billed by (storage_gb_hours, $0.05 a GB-month); a fork too, by all it holds, what its snapshot holds among it: a fork of a 10 GB snapshot is billed as a volume of 10 GB, whatever it shares with the snapshot and its volume in the object store. As its node said last; while no node holds it, the last the control plane heard.

      format: int64 · minimum: 0
    • attached_toمصفوفة منstringrequired

      The sandboxes that have it, by their ids, as the volumes' API always said them: one at the most (attachments says where and how).

      pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
    • regionrequired

      واحد مما يلي:

      • string
      • null
    • homerequired

      The region whose object store holds its copy: the region it was made in (region), until it moves to the region it is mounted in (POST /v1/volumes/{id}/home, or by itself after an hour there). Null where its node copies nothing to an object store. Null of a volume of another kind than a Drive (kind).

      واحد مما يلي:

      • string
      • null
    • home_moveobject | nullrequired

      A move of its home to the region it is held in, while one is under way: when it was asked and why (user: POST /v1/volumes/{id}/home; away: held there for an hour; back: held in its home's region again, taken from another region's store before its home moved there: what it wrote there is copied home, and its home stays), how many of its objects and bytes are copied so far and how many objects are left, and the error it stopped at last, where it stopped (it goes on by itself). Null where none is under way. Null of a volume of another kind than a Drive (kind).

      • asked_atstringrequired
        format: date-time
      • asked_bystring | nullrequired
      • copied_objectsinteger | nullrequired
        minimum: 0
      • copied_bytesinteger | nullrequired
        format: int64 · minimum: 0
      • objects_leftinteger | nullrequired
        minimum: 0
      • errorstring | nullrequired
    • statusstringrequired

      ready; restoring: made from a backup and not all here yet; failed: that restore gave up, and it can only be deleted; unavailable: its node cannot be reached now (it is as it was last seen).

    • leaserequired

      While a sandbox has it read-write; null otherwise. Null of a volume of another kind than a Drive (kind).

      واحد مما يلي:

      • VolumeLease
      • null
    • app_idstring | nullrequired

      A keyed instance's volume (key_drives of the app's version): the app. Null of a volume of another kind than a Drive (kind).

    • keystring | nullrequired

      And the key whose volume it is: it is made with the key's instance, has no other sandbox, and is deleted with the key. Null of a volume of another kind than a Drive (kind).

    • created_atstringrequired
      format: date-time
    • cache_bytesinteger | nullrequired

      Its cache on its node's NVMe: the most of it the node keeps there, its size where that is all of it (the default); the rest is in the object store alone, and a read of it fetches it (the guest waits for the store) and keeps it, while what was used least long ago goes once the store holds it (never what it does not hold yet, which may take a volume past its cache for as long as the store takes to have it). Under 64 MiB it is held at 64 MiB, what a guest's read brings with its read-ahead. Billed by the hour as the volume's NVMe cache, up to what it holds (cache_gb_hours of GET /v1/usage), beside what it holds (used_bytes, storage_gb_hours): all of it cached costs both, none costs the second alone. A database's caches a quarter of it, 1 GiB at the least. A fork has the cache of the volume it was made of. Null of a volume of another kind than a Drive (kind).

      format: int64 · minimum: 0
    • cached_bytesinteger | nullrequired

      What of it is on its node's NVMe now: what was written to it and read of it and not evicted since. Null while no node holds it, and from a node from before caches. Null of a volume of another kind than a Drive (kind).

      format: int64 · minimum: 0
    • history_secondsinteger | nullrequired

      How far back the volume can be restored, or forked, by a time (its window of versions, slice DB8: reports/storage/drives.md 4.7): 3600 to 86400 seconds (an hour to a day). Every window (30 seconds) a volume that was written gets a version that is the volume at one moment (its machine paused for the last of it, two seconds at the most), kept for this long; what they keep that the volume no longer needs is billed as a snapshot's is (history.exclusive_bytes, on the meter of storage under dhist-<the volume's id without vol->). Null (or 0): none, the default; set to null, what it kept goes. Null of a volume of another kind than a Drive (kind).

      format: int64 · maximum: 86400 · minimum: 3600
    • historyobject | nullrequired

      Its window of versions while it has one (history_seconds); null otherwise. Null of a volume of another kind than a Drive (kind).

      • fromstring | nullrequired

        The earliest time it can be restored to: the window's beginning, or its first version where that is later; null until it has one.

        format: date-time
      • versionsintegerrequired

        How many versions the window keeps (GET /v1/volumes/{id}/versions).

        minimum: 0
      • exclusive_bytesintegerrequired

        What its versions keep alone: the data they read from objects that the volume's newest version, its snapshots and every other volume need not, as the object store's collector last worked it out. What the window is billed for, as a snapshot is.

        format: int64 · minimum: 0
      • exclusive_atstring | nullrequired

        When the collector worked that out; null: not yet.

        format: date-time
      • keep_bytesinteger | nullrequired

        The most old data the window keeps (a Free plan's database: a GB, as Tiger keeps): its oldest versions go past it. Null: no bound.

        format: int64 · minimum: 0
    • attachmentsمصفوفة منobjectrequired

      The sandbox that has it, where and how: one at the most. Empty for a volume of another kind than a Drive.

      • sandbox_idstringrequired
        pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
      • pathstring | nullrequired

        Where the sandbox has it mounted: an absolute path. Null where the control plane has heard of the mount from the node's inventory alone.

      • modestringrequired

        read_write: the one writer. A read-only mount of one of its snapshots is not one of these: it is a volume of the sandbox's own (view_of), taken away by the snapshot's id.

    • parent_volume_idstring | nullrequired

      The volume this one was forked from (POST /v1/volumes/{id}/fork), which may be deleted since; null for a volume that is no fork. Null of a volume of another kind than a Drive (kind).

      pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
    • root_volume_idstring | nullrequired

      The first volume of its line of forks (the parent's root, or the parent where that is no fork); null for a volume that is no fork. Null of a volume of another kind than a Drive (kind).

      pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
    • kindstringrequired

      drive: a volume as this section says it, a disk one sandbox has at a time, copied into the object store (every volume made for a project's key but a shared one). shared: a file system a node keeps, any number of sandboxes have at once (POST /v1/volumes with shared: true), which is none of the rest: no lease, no home, no snapshots, forks or versions, no cache of its own. plain: one the operator made (a file system on one node, never copied).

    • sharedbooleanrequired

      Whether it is a shared volume (kind shared).

    • host_failureobject | nullrequired

      What the last hard stop of its node's host left uncertain about its disk, as its node says it; null: nothing.

    • from_backupstring | nullrequired

      The backup it was made from (POST /v1/volumes with from_backup); null for one made empty.

    • failurestring | nullrequired

      Why it could not be made from its backup (status failed); null otherwise.

    • restore_attemptinteger | nullrequired

      Of one made from a backup, which attempt to make it this is (2: the first failed on another node); null for one made empty.

      maximum: 2 · minimum: 1
    • first_failurestring | nullrequired

      With restore_attempt 2, why the first attempt failed; null otherwise.

    • placement_refusalsarray | nullrequired

      Of one made from a backup: the nodes that refused to make it before one did, and why; null where the first did.

    • backupsobject | nullrequired

      Its rule for its backups (PATCH /v1/volumes/{id} with backups; its backups: /v1/volumes/{id}/backups): whether one is taken every day, how many of those are kept, and for how long one is kept. Null where its node says none.

      • dailyoptionalboolean
      • keepoptionalinteger
      • expires_in_daysoptionalinteger
    • durabilityoptionalstring | null

      How it is kept, decided when it is made (DriveCreate.durability). standard: a guest's fsync returns at once (the write is on its node), and a host that is lost loses at most the last second of writes. strict: a guest's fsync, and every flush of its file system, returns once the object store holds every write before it: nothing a guest synced is lost with its host, and each fsync waits for a request to the store (tens of milliseconds). Null of a volume of another kind than a Drive (kind).

  • VolumeSnapshot
    • idstringrequired
      pattern: ^dsnap-[0-9a-hjkmnp-tv-z]{16}$
    • objectstringrequired
    • namestring | nullrequired
    • consistencystring | nullrequired

      How the guest's writes were held for it: frozen, its file system frozen by the sandbox's agent (fs_consistent), consistent for the file system; paused, its machine paused, as at a power cut; at_rest, no running sandbox had the volume read-write.

    • used_bytesintegerrequired

      What the volume held when it was taken (its used_bytes).

      format: int64 · minimum: 0
    • exclusive_bytesintegerrequired

      What it keeps alone: the data its version reads from objects that the volume's newest version, its newer snapshots and every fork need not (an object two snapshots keep counts to the older), as the store's collector last worked it out; 0 before that. What it is billed for, by the hour.

      format: int64 · minimum: 0
    • exclusive_atstring | nullrequired

      When the collector worked that out; null: not yet.

      format: date-time
    • versionobjectrequired

      The version of the volume it is.

      • numberintegerrequired
        format: int64 · minimum: 0
      • epochintegerrequired
        format: int64 · minimum: 0
    • created_atstringrequired
      format: date-time
    • volume_idstringrequired

      The volume it is of, which may be deleted since.

      pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$

400

unknown_parameter; invalid_field: force is not true or false.
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

401

missing_api_key, invalid_api_key, expired_api_key, invalid_token.
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

402

account_in_debt: the account owes (its balance is below zero), and until it has paid nothing of it can be used: every call of its keys, and of the tokens of its sandboxes, is refused so, but those that read what it owes and pay it; those that list and read the backups of its volumes and make a volume from one (POST /v1/volumes with from_backup, but while what it stores is being deleted), what one that stopped paying wants most; and, unless the control plane is started with --debt-allows-delete false, those that list, read and delete the volumes, snapshots and sandboxes it stores, and delete its backups. Never a new backup. Before the key's scopes are looked at, and whatever the path. The message says how much is owed, since when, when what the account stores is deleted, how to pay, that it can delete what it stores to stop the amount from growing, and that a volume is still made from a backup (GET /v1/billing, debt).
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

403

key_scope: the key does not allow the scope the call takes (the message names it); needs_api_key: the operator's key, or the SSH gateway's; account_held: the account is held for its payments, and every call of its keys but GET /v1/account is refused so, before the scopes are looked at (x-error-codes); installation_key_scope: a key held to an installation of a Managed Application, on a call that is not about that installation's own things. (A sandbox token is passed to its node, which answers what it has no call for with 404 no_such_route.)
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

404

volume_not_found, sandbox_not_found; snapshot_not_found: the project has no snapshot of a volume of that id; drive_not_attached: the sandbox does not have it read-write (the message says where it has one of its snapshots read-only, which is taken away by the snapshot's id), or has no read-only mount of the snapshot.
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

409

mount_in_use: a process in the sandbox uses it (?force=true takes it away all the same); key_drive: it is a keyed instance's; sandbox_failed: the sandbox failed. managed_by_database: the volume is a database's (managed_by), changed through /v1/databases alone.
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

503

node_unavailable: the sandbox's node cannot be reached; unavailable: it did not answer in time.
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    With already_moving: the move of the sandbox that is under way.

  • upgrade_idoptionalstring

    With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        Its name; null for a node that is off the books since.

    • epochintegerrequired

      The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.

      minimum: 1
    • stepstringrequired

      Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).

    • whystringrequired

      What made it: the operator's move, an evacuation, a recovery.

    • wakebooleanrequired

      Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.

    • from_storebooleanrequired

      The new node takes it from the object store alone.

    • releaseobject | nullrequired

      What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.

    • takeoverobject | nullrequired

      What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.

    • errorrequired

      Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.

      واحد مما يلي:

      • object
      • null
    • attemptsintegerrequired

      How many times the step it is at was asked without an answer that settles it.

      minimum: 0
    • next_attempt_atstring | nullrequired

      When that step is asked again; null where it is not waiting.

      format: date-time
    • batchstring | nullrequired

      The evacuation (evc-…) or recovery (rcv-…) it is of.

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

    format: date-time
  • activeoptionalobject | null

    With standby: the active copy, as the standby last read the lease; null while no copy holds it.

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).

  • problemsoptionalمصفوفة منobject

    With invalid_definition: every problem of the definition, each where it is and what it is.

    • atstringrequired

      Where in the definition, a dotted path (services.web.port); empty for the whole of it.

    • messagestringrequired
  • reportoptionalobject

    With compose_refused: the import's report, which says what is refused, why, and what to change.

    • objectcompose_importrequired
    • namestring | nullrequired

      The model's name: each service's label compose.project. Null: it has none.

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profilesمصفوفة منstringrequired
    • treatmentsobjectrequired

      How many items of the report have each treatment.

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • itemsمصفوفة منobjectrequired

      The model's top-level elements: name, each volume, network, config and secret, extensions.

      • atstringrequired

        Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

      • treatmentdoneأوadaptedأوignoredأوrefusedrequired

        done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

      • whystringrequired
      • changestring | nullrequired

        Of one that is refused: what to change. Null otherwise.

    • servicesمصفوفة منobjectrequired

      The services the import takes, in the model's order.

      • namestringrequired

        The service's name, which is its app's.

      • app_idstring | nullrequired

        Its app. Null: a dry run of a service the project does not have.

        pattern: ^app-
      • statuscreatedأوchangedأوunchangedrequired

        What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.

      • kindserviceأوjobrequired

        job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.

      • statefulbooleanrequired

        It mounts a volume of its own: one instance, which has the volume.

      • versionbooleanrequired

        Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.

      • itemsمصفوفة منobjectrequired
        • atstringrequired

          Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).

        • treatmentdoneأوadaptedأوignoredأوrefusedrequired

          done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.

        • whystringrequired
        • changestring | nullrequired

          Of one that is refused: what to change. Null otherwise.

      • appobjectrequired

        The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.

        • imagestring | nullrequired

          What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.

        • image_pull_secretstring | nullrequired

          The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.

        • start_commandrequired

          واحد مما يلي:

          • StartCommand
          • null
        • start_argsrequired

          What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.

          واحد مما يلي:

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).

          • httpoptionalstring

            A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.

          • tcpoptionaltrue

            The app's port takes a connection.

          • commandoptional

            A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.

            واحد مما يلي:

            • string
            • array<string>
        • envخريطة منstringrequired
        • secretsخريطة منstringrequired

          Names of secrets. No answer has a value.

        • sizeobjectrequired

          What one instance may use at most. It is billed by what it uses.

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).

            minimum: 134217728
        • volumesمصفوفة منobjectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            There only where it was given as true.

        • kindstringrequired
        • filesمصفوفة منobjectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          واحد مما يلي:

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regionsمصفوفة منstringrequired

          In the order na, eu, ap.

        • scaleobjectrequired
          • min_instancesintegerrequired

            How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.

            minimum: 0
          • max_instancesinteger | nullrequired

            How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.

            minimum: 1
          • concurrencyinteger | nullrequired

            A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          واحد مما يلي:

          • object
          • null
        • egressobject | nullrequired

          Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).

          • defaultoptionalallowأوdenyأوnull
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.

        • metadataخريطة منstringrequired
        • logsobjectrequired

          What the app's log has, each part as it was given or at its default (AppLogSettings).

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          Whether it answers at its default domain (url).

        • depends_onمصفوفة منobjectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliasesمصفوفة منstringrequired
          • endpoint_modestringrequired
        • drivesoptionalمصفوفة منobject

          The Drives its instance mounts (AppCreate.drives): none, [], where it names none.

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptionalمصفوفة منobject

          The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            There only where it was given as true.

        • runtimeoptional

          Its runtime settings (AppCreate.runtime). null: none.

          واحد مما يلي:

          • Runtime
            • ulimitsخريطة منRuntimeLimitGivenrequired
            • sysctlsخريطة منstringrequired
            • tmpfsمصفوفة منobjectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • serversمصفوفة منstringrequired
              • searchمصفوفة منstringrequired
              • optionsمصفوفة منstringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumesمصفوفة منobjectrequired

      The volumes of the project the services mount.

      • modelstring | nullrequired

        Its name in the model. Null: made for a path a stateful service mounts with no volume named.

      • namestringrequired

        Its name in the project.

      • idstring | nullrequired

        Null: not made yet (to_make).

        pattern: ^vol-
      • sharedbooleanrequired

        Several services mount it, or one with several instances: every instance of each mounts it at once.

      • statusto_makeأوmadeأوthereأوexternalrequired

        to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.

      • used_byمصفوفة منstringrequired
    • secretsمصفوفة منobjectrequired

      The secrets of the model that services are granted.

      • modelstringrequired

        Its name in the model.

      • namestringrequired

        The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.

      • therebooleanrequired

        Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.

      • used_byمصفوفة منstringrequired
    • left_outمصفوفة منobjectrequired

      The services of profiles that are not turned on, which the import does not touch.

      • namestringrequired
      • profilesمصفوفة منstringrequired
    • absentمصفوفة منstringrequired

      The project's services that the model does not have: kept as they are.

    • deploystring | nullrequired

      The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.

      pattern: ^dpl-
  • accountsoptionalمصفوفة منobject

    With sole_owner: the accounts the user is the only owner of.

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

اكتب للبحث…

↑↓ للتنقل↵ للاختيارEsc للإغلاق