Skip to main content
Run a command in a running sandbox and read its output while it runs. A command has no time limit unless you set one.

Write the code that runs a command in a sandbox.

Before you start

Run a command

Send POST /v1/sandboxes/{id}/commands with a command:
  • A string runs with bash -lc, for example "npm test".
  • A list runs the program with its arguments, for example ["ls", "-la"].
The answer is a stream of JSON lines (NDJSON) that ends when the command exits.

Events in the stream

Each line is one event. Each event has a seq that starts at 0.
  • encoding is utf8 for text, and base64 for bytes that are not valid UTF-8.
  • When no event comes for 15 seconds, the stream sends an empty line, so that proxies keep the connection open. Skip empty lines.
  • If you disconnect before the exit event, the command gets SIGKILL. To keep a command running, use a detached command.

Set the folder, the environment, and a time limit

Send stdin

Start the command with "stdin": true. Then send POST /v1/sandboxes/{id}/commands/{commandId}/stdin with data. Send "eof": true to close stdin. The answer is 204.
Send "encoding": "base64" for bytes that are not text. Stdin to a command that exited answers 409.

Run a detached command

Send "detached": true for a long command, such as a dev server or a build. The API answers 201 with the command at once, and the command runs after you disconnect.
Read the output with GET /v1/sandboxes/{id}/commands/{commandId}/events. Send ?after=N to get only the events with a seq above N, for example after a disconnect. The stream ends at the exit event. You can read the events of a command again after it exits.
The sandbox keeps the newest 4 MiB of events of each command. If you ask for older events, the stream starts at the oldest kept event.

List, get, and kill commands

A kill sends SIGKILL. Send ?signal=SIGTERM for a different signal: SIGTERM, SIGINT, SIGHUP, SIGQUIT, SIGUSR1, or SIGUSR2. The answer comes when the command exits, or after 5 seconds. After the exit, signal has the signal. If a command runs out of memory, the command gets SIGKILL and oomKilled is true. Use a bigger size for this command. The sandbox keeps each running command and its 25 newest exited commands. A restart of the sandbox removes the list.

Errors

A revoked API key can work for 30 more seconds on these endpoints.