Write the code that runs a command in a sandbox.
Before you start
- You need an API key with the
sandboxes:execscope. See API keys. - The sandbox must be
running. See Create, get, and delete a sandbox.
Run a command
SendPOST /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"].
Events in the stream
Each line is one event. Each event has aseq that starts at 0.
encodingisutf8for text, andbase64for 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
exitevent, the command getsSIGKILL. 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.
"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.
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.
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.