Run one command in a sandbox made for it

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.

A string is one line for sh -c; a list is run as it is, without a shell, its first word found as a shell finds it: along the PATH of the command's own environment (the image's, with what env says). At most 1000 arguments, no NUL bytes.

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, and which of its requests get a secret added, as in SandboxCreate.

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.

Added to the sandbox's env for this command; the same name wins here.

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.

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 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.)

As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

As in SandboxCreate: accepted, and its checkpoints taken while the command runs.

As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

As in SandboxCreate.

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.

As in SandboxCreate: more variables, whose values are secrets, the sandbox's and so the command's; none of them in env too (400 invalid_field, param secret_env.<name>). No answer shows a value.

An absolute path to run in. Default: the image's working directory. A directory that does not exist is not an error of the call: the command ends with exit code 126.

A user name, a uid, or uid:gid. Default: the image's user.

As in RunRequest, with a default: nothing else would stop the sandbox.

Fed to the command's input, which is then closed (unless stdin_open). Base64 when encoding says so. The whole request is 64 MiB at the most (413 body_too_large beyond): a longer input goes in …/exec/{exec_id}/stdin calls, or in a file first.

base64: stdin is base64, and stdout and stderr come back as base64 (in a stream: events carry base64 instead of text). For output that is not text.

Answer with an event stream. Default: true if the request's Accept contains text/event-stream.

Have the command wait for whoever reads this call's answer, instead of running ahead of it. As in RunRequest.

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.