curl --request POST \
--url https://{sandbox_key}.{domain}/executions \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: <api-key>' \
--data @- <<EOF
{
"action": "exec",
"parameters": {
"command": "printf '%s\\n' \"$APP_ENV\"",
"envs": {
"APP_ENV": "production"
},
"cwd": "/workspace"
}
}
EOFimport requests
url = "https://{sandbox_key}.{domain}/executions"
payload = {
"action": "exec",
"parameters": {
"command": "printf '%s\n' \"$APP_ENV\"",
"envs": { "APP_ENV": "production" },
"cwd": "/workspace"
}
}
headers = {
"X-Access-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
action: 'exec',
parameters: {
command: 'printf \'%s\n\' "$APP_ENV"',
envs: {APP_ENV: 'production'},
cwd: '/workspace'
}
})
};
fetch('https://{sandbox_key}.{domain}/executions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{sandbox_key}.{domain}/executions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'action' => 'exec',
'parameters' => [
'command' => 'printf \'%s\\n\' "$APP_ENV"',
'envs' => [
'APP_ENV' => 'production'
],
'cwd' => '/workspace'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{sandbox_key}.{domain}/executions"
payload := strings.NewReader("{\n \"action\": \"exec\",\n \"parameters\": {\n \"command\": \"printf '%s\\\\n' \\\"$APP_ENV\\\"\",\n \"envs\": {\n \"APP_ENV\": \"production\"\n },\n \"cwd\": \"/workspace\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Access-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{sandbox_key}.{domain}/executions")
.header("X-Access-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"action\": \"exec\",\n \"parameters\": {\n \"command\": \"printf '%s\\\\n' \\\"$APP_ENV\\\"\",\n \"envs\": {\n \"APP_ENV\": \"production\"\n },\n \"cwd\": \"/workspace\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{sandbox_key}.{domain}/executions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"action\": \"exec\",\n \"parameters\": {\n \"command\": \"printf '%s\\\\n' \\\"$APP_ENV\\\"\",\n \"envs\": {\n \"APP_ENV\": \"production\"\n },\n \"cwd\": \"/workspace\"\n }\n}"
response = http.request(request)
puts response.read_body{
"request_id": "<string>",
"execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sandbox_id": "<string>",
"status": "pending",
"exit_code": 123,
"stdout": "<string>",
"stderr": "<string>",
"stdout_truncated": true,
"stderr_truncated": true,
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"termination_reason": "runtime_terminated",
"failure_reason": "cwd_not_found"
}{
"request_id": "<string>",
"execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sandbox_id": "<string>",
"status": "pending"
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Auth.Unauthorized",
"message": "unauthorized",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40"
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}Execute a command in a sandbox
Starts an asynchronous shell execution in the sandbox. The request body keeps the
action=exec and parameters shape used by the runtime contract. The effective URL is
the sandbox data-plane host; the sandbox ID is obtained from the leftmost Host label and
is not repeated in the path. The endpoint does not include the control-plane /api/v2 prefix.
When wait=true, the server waits for a terminal result for at most
wait_timeout_seconds seconds; a timeout returns 202 without cancelling the execution.
Cancelling an execution, or reaching its timeout, stops the command and every process it started: all processes in the command’s process group receive SIGTERM and then SIGKILL, so a pipeline or bash -c "a; b" leaves nothing behind. A process that deliberately leaves the group (for example with setsid) is not stopped. A command that exits on its own does not stop the background processes it started, so a server started with nohup app > app.log 2>&1 & keeps running; redirect the output of such a process, because the execution only ends once the command’s stdout and stderr are closed. Pausing the sandbox does not end the execution; the time spent paused still counts toward the execution’s timeout.
The request body is limited to 1 MiB. Unknown query parameters are rejected with 400. A sandbox allows at most 10 non-terminal executions at the same time; further requests return 429 Execution.ConcurrencyLimitExceeded until one completes.
curl --request POST \
--url https://{sandbox_key}.{domain}/executions \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: <api-key>' \
--data @- <<EOF
{
"action": "exec",
"parameters": {
"command": "printf '%s\\n' \"$APP_ENV\"",
"envs": {
"APP_ENV": "production"
},
"cwd": "/workspace"
}
}
EOFimport requests
url = "https://{sandbox_key}.{domain}/executions"
payload = {
"action": "exec",
"parameters": {
"command": "printf '%s\n' \"$APP_ENV\"",
"envs": { "APP_ENV": "production" },
"cwd": "/workspace"
}
}
headers = {
"X-Access-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
action: 'exec',
parameters: {
command: 'printf \'%s\n\' "$APP_ENV"',
envs: {APP_ENV: 'production'},
cwd: '/workspace'
}
})
};
fetch('https://{sandbox_key}.{domain}/executions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{sandbox_key}.{domain}/executions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'action' => 'exec',
'parameters' => [
'command' => 'printf \'%s\\n\' "$APP_ENV"',
'envs' => [
'APP_ENV' => 'production'
],
'cwd' => '/workspace'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{sandbox_key}.{domain}/executions"
payload := strings.NewReader("{\n \"action\": \"exec\",\n \"parameters\": {\n \"command\": \"printf '%s\\\\n' \\\"$APP_ENV\\\"\",\n \"envs\": {\n \"APP_ENV\": \"production\"\n },\n \"cwd\": \"/workspace\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Access-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{sandbox_key}.{domain}/executions")
.header("X-Access-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"action\": \"exec\",\n \"parameters\": {\n \"command\": \"printf '%s\\\\n' \\\"$APP_ENV\\\"\",\n \"envs\": {\n \"APP_ENV\": \"production\"\n },\n \"cwd\": \"/workspace\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{sandbox_key}.{domain}/executions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"action\": \"exec\",\n \"parameters\": {\n \"command\": \"printf '%s\\\\n' \\\"$APP_ENV\\\"\",\n \"envs\": {\n \"APP_ENV\": \"production\"\n },\n \"cwd\": \"/workspace\"\n }\n}"
response = http.request(request)
puts response.read_body{
"request_id": "<string>",
"execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sandbox_id": "<string>",
"status": "pending",
"exit_code": 123,
"stdout": "<string>",
"stderr": "<string>",
"stdout_truncated": true,
"stderr_truncated": true,
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"termination_reason": "runtime_terminated",
"failure_reason": "cwd_not_found"
}{
"request_id": "<string>",
"execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sandbox_id": "<string>",
"status": "pending"
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Auth.Unauthorized",
"message": "unauthorized",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40"
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}{
"code": "Execution.InvalidRequest",
"message": "<string>",
"request_id": "req-3f2b6c1e-8a0d-4f6b-9c3e-2d7a1b5e9f40",
"details": {}
}Authorizations
Sandbox data-plane token — the sandbox_access_token returned by the create/connect endpoints. Used for /files, Sandbox-Exec, and other data-plane endpoints; the control plane (/api/v2) does not accept it, and conversely the control plane's Authorization: Bearer is invalid on the data plane.
The token is bound to its sandbox: using sandbox A's token against sandbox B's host fails. It stays valid until the sandbox's lifetime ends; there is no separate rotation endpoint (rotate_traffic_token rotates the port traffic token traffic_access_token and does not affect this one).
Headers
Optional key that makes POST /executions safe to retry: 1 to 64 printable ASCII characters without whitespace. Resubmitting the same key with identical parameters returns the same execution in its current state instead of starting a new one; the same key with different parameters returns 400 Execution.IdempotentParameterMismatch. A key that is empty or not 1 to 64 printable ASCII characters returns 400 Execution.InvalidRequest. The key is remembered for a limited time after the execution reaches a terminal state; after that, the same key starts a new execution.
1 - 64Query Parameters
Maximum time to wait when wait=true, in seconds. Values from 1 through 25
are accepted. A wait timeout never cancels the execution.
Only valid together with wait=true (otherwise 400 Execution.InvalidRequest); a value outside 1..25 or not an integer returns 400 Execution.InvalidWaitTimeout.
1 <= x <= 25Body
Response
Execution completed within the requested wait window.
Public lifecycle status of a sandbox execution. timed_out means the per-command time limit (execution_timeout_seconds) was reached and the command was terminated (SIGTERM, then SIGKILL after a grace period); exit_code is then null.
pending, running, cancelling, succeeded, failed, cancelled, timed_out Exit status of the command. A command killed by a signal (for example an out-of-memory kill) reports 128 + signal (137 for SIGKILL) with status failed and no termination_reason. Null while non-terminal, and when the execution was cancelled, timed out, or its runtime was terminated.
Why an execution that did not finish on its own ended. Omitted when the command exited by itself, including when it was killed by a signal from inside the sandbox (see exit_code). explicit_cancel: the execution was cancelled (status cancelled). execution_timeout: the execution reached its timeout (status timed_out). runtime_terminated: the command's process is gone without having reported an outcome, for example the sandbox was resumed from a pause without memory, or its output stream was lost for good, so the outcome of the command is unknown (status failed). Pausing a sandbox does not by itself end an execution: after a pause with memory the command continues and the execution reports its real result.
explicit_cancel, execution_timeout, runtime_terminated "runtime_terminated"
Classified process startup failure. Omitted when no recognized startup cause is available. cwd_not_found means the working directory does not exist; cwd_not_directory means the working directory is not a directory; permission_denied means startup was denied without a reliably identified operation. Contains no path or raw upstream error. Runtime interruptions use termination_reason.
cwd_not_found, cwd_not_directory, permission_denied