Create a sandbox

The caller's own id for the request: 1 to 64 letters, digits, ., _ and -. The node then knows the request by it: in the answer's X-Request-Id, in error bodies and in its log. Anything else is ignored, and the node makes an id.

Makes the request safe to send again. See "Idempotency-Key" in the introduction.

true: start the image's own start command (ENTRYPOINT and CMD) when the machine boots; false: start nothing, whatever the image's labels ask for. Given (as any of start, start_command and ready), it is all that counts: the image's labels sbx.start and sbx.ready are not read. The sandbox is made from a template built with these settings and env (two settings of one image are two templates; the first sandbox of a setting is returned starting while it is built), which only its owner's sandboxes are made from. Not for a sandbox made from a snapshot or a template (400 invalid_start).

The start command, run as the image's user, its output kept by the sandbox's agent as that of the command exe-start (the last 16 MiB of it, read like any command's with GET …/exec/exe-start and …/exec/exe-start/output; for an app's instance it is also what the app's log has of the instance): a string is run by /bin/sh -c and may hold several lines; a list is run as it is, without a shell (for an image that has none). At most 1000 arguments and 64 KiB, no NUL bytes, the first argument not empty. With start: false, 400 invalid_start.

When the machine of the sandbox's template counts as up: the node saves the template, which every sandbox of these settings is cloned from, only once this check passes, so that the service is running in each of them from the start. One of three. tcp and http are tried by the node from the host, at the address the preview URLs reach the sandbox by: nothing runs in the sandbox for them, so an image without a shell can be checked, and the service has to listen on all addresses, not on 127.0.0.1 alone. command runs in the sandbox as the image's user, by sh, like the label sbx.ready. Tried every 0.2 s for at most 120 s; a start command that ends with a failure meanwhile ends the wait at once. Either way the sandbox fails with failure_code boot_failed, and failure says what the check last got and what the start command printed last. Needs start: true or start_command (400 invalid_start). Not given: the template is saved without waiting.

What the sandbox may reach, what it may ask of a host, and which of its requests get a secret added. In force before the sandbox runs anything. A sandbox made from a snapshot starts with the rules the snapshot recorded unless this field is given; null then means no rules.

Whether the guest kernel keeps its mitigations against speculative execution. They guard the guest's kernel against processes in the same sandbox: turn them on when a sandbox runs code of several users who do not trust each other. Sandboxes are kept apart from each other by the host either way. Default: the node's setting (off). The setting is fixed when the kernel boots: the first sandbox with a setting other than its image template's starts like a new image (returned starting), and a sandbox made from a snapshot keeps the snapshot's (asking for the other is 400).

Where the sandbox's /tmp is. disk: on its disk, as the rest. memory: a tmpfs of at most half of its memory, mounted before its first command (in a sandbox made from a template or an image, over what the template's guest had put there; by the guest's init where it starts from its disk): what is written there is the guest's memory, billed as memory, kept when it sleeps, and gone when it starts again from its disk. A sandbox made from a snapshot whose sandbox had it in memory has it so whatever this says.

Runtime settings of its machine and its commands, as a Compose file's ulimits, sysctls, tmpfs, dns and shm_size ask for them (Runtime). For a sandbox made from an image: they make a template of the caller's own, built with them (with nothing said of the start, the image is started as its labels ask). Refused for one made from a snapshot or a template (400 invalid_start), which goes on with what its machine has.

What the sandbox's PID 1 is. Not given, or null: the platform's init, which starts the image's start command where there is one (start, start_command, the image's labels). systemd: a whole system. The image's own systemd is PID 1 and the node's agent is one of its services: the user installs packages, starts services with systemctl, uses cron and the journal and logs in by SSH, as on a machine. Nothing a create names is started (start, start_command and ready are refused with 400 invalid_start), and the template is saved once systemd says the machine has booted. Without image: the node's image of a whole system (--systemd-image; Ubuntu 24.04 with systemd and OpenSSH, sandboxd/images/ubuntu), refused with 400 invalid_start on a node that has none. An image without systemd (/usr/lib/systemd/systemd) fails its build, with failure_code invalid_image. Its template is anybody's who asks for the same image so, unless something of the caller's is in it (runtime, image_pull_secret). Refused for one made from a snapshot or a template (400 invalid_start), which goes on as its machine was. Everything else a sandbox does works as for any sandbox: commands, files, terminals, the SSH gateway, sleep and wake, snapshots and forks, moves, egress rules (sandboxd/README.md, 「整个系统：systemd 当 PID 1」).

true: the sandbox is on its project's private network from before it runs anything, at the first of the addresses the node was left to spare for the project (setProjectNetwork): the answer says which (project_address). The project is the call's owner, so this is for a call the control plane makes for a project; on a node that stands alone a sandbox is nobody's, and is put on a network by being named in it. A sandbox is on no project's network unless it asks: default false. A copy made by a fork is on none, whatever its original is on.

An OCI image reference (python:3.12, ghcr.io/org/app@sha256:…), in a registry on the internet: one that gives the image to anybody, or one that wants a login, with image_pull_secret. The first sandbox of an image is returned starting while the node pulls the image and builds a template; later ones start from the template. Default: the node's base image.

The name of a secret (PUT /v1/secrets/{name}) that holds the credentials of the image's registry, for an image that is not public: username:password in printable ASCII, the user name ending at the first colon. A registry that takes a token alone documents the user name that goes with it (AWS for ECR, oauth2accesstoken for Google's, any name for GHCR). The node hands the credentials to the tool that pulls the image and to nothing else: nothing of them is in the sandbox, in its template or in the node's log, and what a registry says when it refuses them comes back without them (failure_code registry_auth_failed). The sandbox is made from a template of its owner's alone, which a create that names credentials finds and no other: the same image named without them is asked of its registry without a login, whether or not the node has the template. The secret has to exist (404 secret_not_found), to be one that may go to the image's registry (its allowed_hosts cover the registry's host as the reference writes it, without its port, docker.io where it names none; 403 secret_host_not_allowed otherwise) and to hold such a pair (400 invalid_field), and it goes with image (400 invalid_field for a sandbox made from none).

A snapshot's id or name: the sandbox goes on from the instant the snapshot was taken, processes included.

A template's key on the node (base, img-…), as GET /internal/node lists them. Not in the reference README; the benchmark scripts use it.

The shape a create asks for. Each part that is not given (or is null) is the node's base template's, which is what a sandbox that asks for none gets. Up to the most this node gives a sandbox, max_vcpus and max_memory_bytes of GET /internal/node (by default the host's CPUs, up to 32, and its memory; never less than the base template's shape); more is 400 invalid_field. Each shape of an image is a template of its own: the first sandbox of a shape the node has not built that image in is returned starting while the node builds it, from the same image, and later ones are cloned from it. Without image, another shape than the base template's is built from the node's base image. A sandbox made from a snapshot or a template has that one's shape: asking for it is fine, for another 400 invalid_field (param limits). The disk's size is the node's: disk_bytes is 400 invalid_field.

A name given by the caller to a sandbox, a snapshot, a volume or an SSH key: 1 to 63 lower-case letters, digits and hyphens, not starting or ending with a hyphen, and not starting with an id prefix (sbx-, exe-, snap-, vol-, evt-, req-; an SSH key's not with sshkey- either). A DNS label that cannot be taken for an id. Unique among sandboxes, among snapshots, among volumes and among SSH keys.

Environment variables. Names match [A-Za-z_][A-Za-z0-9_]*; values hold no NUL byte; at most 256 KiB in all.

More environment variables, whose values are secrets: every command started in the sandbox gets them with env, and so does its start command (written for it where env is, and nowhere else: no value of them is in a template's key or record). No answer shows a value: the sandbox shows their names (Sandbox.secret_env). At most 64 variables and 64 KiB, names as env takes them, none of them in env too (400 invalid_field, param secret_env.<name>); taken when the sandbox is made and not changed afterwards (a PATCH that gives env one of these names is refused the same way, param env.<name>). Not in a snapshot: a sandbox made from one has the ones its own create gives.

Free key-value pairs for the caller's own use; lists of sandboxes filter by them. At most 64 keys of 1 to 64 characters, values of up to 1024. Not a place for secrets: metadata are stored in clear, and every set of them a sandbox has had while it used something is kept with its usage for thirteen months, also after the sandbox is deleted (GET /v1/usage groups and filters by them).

Volumes to mount before the call returns. At most two that are not shared. A sandbox made from a template that holds its start command back (TemplateBuildRequest.start_after_volumes) has its start command started once they are mounted, and the call returns when the command is up as the template's ready says; so does every boot of it from its disk (a restart, a host that went down), which mounts them first.

Ports anybody may open at their short preview URL.

Every port but these is public as well: its short preview URL opens it for anybody, as a port in public_ports (how E2B makes a sandbox's ports; the control plane's E2B compatibility gives [49983], envd's port, which a sandbox token opens). []: every port. Null (the default): only public_ports. Ports are taken once each, in order.

Ports on which a connection upgraded through the preview URL (a WebSocket: a browser's DevTools client on 9222, the viewer of a screen on 6080) keeps the sandbox awake for as long as it is open, and is billed for. While this names a port, the sandbox is idle by those connections and by the requests and calls it is given, and by nothing its guest does: its CPU, its timers, its connections to anywhere and their traffic do not keep it awake, and it is not woken for a timer (what came due meanwhile fires when the next connection wakes it). It goes to sleep sleep_after_seconds after the last of them ended, without its guest being asked. Such a connection has TCP's keepalive on its client's side, so that a client that went away without closing it is found out within about a minute. Null or [] (the default): idle as any sandbox is. Kept in order, without duplicates. Not for a one-shot run (POST /v1/run). A session of Browsers (reports/browsers/README.md) is made with [9222].

A connection on one of awake_ports that has carried nothing in either direction for this long is closed by the node (and the sandbox, if nothing else holds it, sleeps sleep_after_seconds after that). Null (the default): never for that. Holds for the connections that open after it is set.

Ports open to the internet at the sandbox's own IPv6 address from the start, each with its sources (…/tcp/{port} opens one later). A node without a pool of addresses refuses a list that is not empty: 409 no_ipv6.

Sleep after this long idle. Null: never by itself. The default is the node's (--sleep-after-seconds, 30 unless set).

Delete the sandbox at this time, which must be in the future (or what on_expiry says). Null or absent: never.

What expires_at does when it comes: delete the sandbox (null or absent: this); sleep, put it to sleep whatever goes on in it, and keep it (its expires_at is null from then on, and a request wakes it as ever); hold, the same, held asleep (held_asleep is set then: a request does not wake it). How E2B pauses a sandbox when its time is up (the control plane's E2B compatibility). Another word is 400 invalid_field.

True: while it sleeps, a request to one of its ports does not wake it: the preview listener answers 502 sandbox_paused in its place, as E2B's proxy answers for a paused sandbox (x-preview-ingress), and only a call of the API (or its own timer) wakes it. It is not put to sleep by this: POST /v1/sandboxes/{id}/sleep does that. False or null: as any sandbox. (E2B's pause without its autoResume, which the control plane's E2B compatibility sets, and takes away at its connect.)

How long before the idle rule puts the sandbox to sleep (or pauses it) every program connected to its guest's /run/sbx/awake is sent the line sleep N, in milliseconds; the sleep comes that long after, unless a hold raised meanwhile puts it off (sleep_hold_max_ms). Where nobody is connected, the sleep is not put off. A sleep somebody asks for (POST /v1/sandboxes/{id}/sleep, a freeze, a move, the node stopping) is told nothing. 0, null or absent: not told.

How long the holds a program in its guest raises (+ on /run/sbx/awake) keep the sandbox up at the most, in milliseconds, counted from the moment it was first found held while nothing else kept it up; then it sleeps whatever holds it (the programs connected are told sleep N cap first, where sleep_notice_ms asks for a notice), and the count begins again at its next quiet. Held, it runs and is metered as running. 0: holds are not heeded. Null or absent: the node's (--sleep-hold-max-seconds, 30 s unless set).

How long the pause tier (pause_tier of GET /internal/node) holds the sandbox paused, once the idle rule has stopped it, before its memory is saved and it sleeps for real, in milliseconds. Paused, it answers in a millisecond or two and is metered for the memory it holds; asleep, for what it keeps on disk. The node's --pause-max-seconds (600 unless set) is also the longest it is held paused whatever this says: a paused machine holds the host's memory. The host's memory below the floor, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null or absent: the node's. Of no effect where the node has no pause tier.

A time of day in UTC, HH:MM, at which the node wakes the sandbox every day while it sleeps or stands paused, for work of its own that waits for a wake and keeps no time (a database's maintenance, say). The wake is no activity: what runs then is, and once that is done the idle rule puts it to sleep again. Not for a sandbox that is idle by its connections (awake_ports). A stateful service's instance (its start command held back for its volumes) is woken besides for the next run of its PostgreSQL server's pg_cron jobs, which the node asks its agent for before it rests; while a job runs, or is due within 5 s, the idle rule does not rest it. Null or absent: none.

Delete the sandbox once it has slept for this long, in milliseconds (Sandbox.idle_since); a wake starts the count again at the next sleep. Null or absent: never for that. Less than 1000 is refused (400 invalid_field).

The name the sandbox's machine has, for good, in place of its id: what hostname says in it, from its first boot and after every restart. Lower-case letters, digits and hyphens, in labels between dots; otherwise 400 invalid_field. The control plane gives a service's instance the service's name (or the service's hostname). Not given: the sandbox's id.

How the sandbox's start command is stopped before its machine is ended for good: before a restart (POST /v1/sandboxes/{id}/restart) and a delete. The signal goes to the start command, which is then given grace_ms to end; what has not ended then goes with the machine. A machine that sleeps or is paused is not stopped: it goes on from where it was. Not given: the start command goes with its machine, as it always has. Unknown keys: 400 unknown_field; a signal that is none of these, or a grace beyond ten minutes: 400 invalid_field.

The app's log the sandbox's lines go to, as the lines of the app's instances do (readAppLog): what its start command prints, a line for each request through its ports and what the node does to it (made, stopped, deleted). For a sandbox made from the app's version's template (template, the key the log knows the version by), of its owner's: the control plane gives it for an app's keyed instance and for a stateful service's. Nothing of the app's group holds for it otherwise: it is no instance the app's requests are given to, and sleeps and is deleted as a sandbox. Without template: 400 invalid_field.

Checkpoints while the sandbox runs: every every_seconds its memory and its disk as they are at one instant go to the node's object store (the node pauses its machine for a few milliseconds for it; what it wrote since the last one is what goes), so that when the node's host is lost the sandbox is taken over elsewhere with its processes, from its newest checkpoint, losing at most what it did since. A checkpoint is begun only once the one before is in the store: a sandbox that writes more than the node's link for them takes falls behind (checkpoint.behind_seconds) rather than filling it. Asleep, its sleep's image is what it is taken over from. Null (the default): none. Any sandbox may have it, given when it is made or by a PATCH (the control plane also gives it to the keyed instances of an app whose checkpoint says so); what the store keeps of its newest checkpoint is billed as a sleeping sandbox's state while it runs (checkpoint.stored_bytes). A node that does not copy disks to an object store (--upload), or whose memory is not in layers, refuses it (409 checkpoints_unavailable, param checkpoint), and a control plane makes a sandbox with it only on a node that takes checkpoints. Its Drives are pinned with its own disk at the same instant, and a takeover from it brings them back as they were then, with its memory; none is taken while a volume that is not a Drive is attached (such a volume has no copy in the store), or while a read of its guest is held up on a drive of its machine. A checkpoint does not reset the guest's vsock connections (the agent's calls go on), and the first one after a wake from a sleep whose image the store has sends only what the guest wrote since.

The region to make it in, read by the API and not passed on. Null or left out: the region the API itself runs in. Where no machine of that region can take it, the next region does; what has to go to one machine (made from a snapshot or with volumes, or sent again with the same Idempotency-Key) goes there, whatever the region. A volume made from a backup is made in the backup's region: another is 400 invalid_field. Not a region: 400 unknown_region. The answer's region says where it was made.