Execute Sandbox Command

POST/v1/sandbox/{sandbox_id}/command

POST/v1/sandbox/{'{sandbox_id}'}/command

Base URL *

Your instance endpoint, shown on the instance page in the dashboard. Each instance has its own host; there is no shared API host.

Authorization (Bearer token)

sandbox_id (path) *

Request Body (JSON)

Description

Executes a shell command inside the specified sandbox. By default the response is a Server-Sent Events (SSE) stream that emits stdout, stderr, and exit events in real time as the command runs.

When background is set to true, the command is launched in the background and the response immediately returns a command ID and status that can be used to poll for results.

Path Parameters

Parameter	Type	Required	Description
`sandbox_id`	`string`	Yes	Sandbox ID or name

Request Body

Property	Type	Required	Description
`command`	`string`	Yes	Shell command to execute
`cwd`	`string`	No	Working directory for the command. Defaults to the sandbox root
`background`	`boolean`	No	Run the command in the background and return immediately. Default: `false`
`timeout`	`integer`	No	Timeout in milliseconds before the command is killed. Default: `30000`

Responses

200 Success (foreground — SSE stream)

Each line is a JSON-encoded SSE event:

Property	Type	Description
`type`	`string`	Event type: `"stdout"`, `"stderr"`, or `"exit"`
`data`	`string`	Event payload. For `"exit"` events, contains the numeric exit code as a string

200 Success (background — `background: true`)

Property	Type	Description
`id`	`string`	Unique ID for the background command
`status`	`string`	Initial status, e.g. `"running"`

default An unexpected error response.

Property	Type	Description
`code`	`integer`
`message`	`string`
`details`	`object[]`

Request

curl -X POST "https://{instance}.{region}.everstack.ai/v1/sandbox/{sandbox_id}/command" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"command":"ls -la /workspace","cwd":"/workspace","background":false,"timeout":30000}'

const sandboxId = "your-sandbox-id";
const response = await fetch(`https://{instance}.{region}.everstack.ai/v1/sandbox/${sandboxId}/command`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "text/event-stream",
  },
  body: JSON.stringify({
    "command": "ls -la /workspace",
    "cwd": "/workspace",
    "background": false,
    "timeout": 30000,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

import requests

sandbox_id = "your-sandbox-id"
response = requests.post(
    f"https://{instance}.{region}.everstack.ai/v1/sandbox/{sandbox_id}/command",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Accept": "text/event-stream",
    },
    json={
        "command": "ls -la /workspace",
        "cwd": "/workspace",
        "background": False,
        "timeout": 30000,
    },
    stream=True,
)

for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Response

{"type":"stdout","data":"total 48\ndrwxr-xr-x 6 root root 4096 Jan  1 00:00 .\n"}
{"type":"stderr","data":""}
{"type":"exit","data":"0"}

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}