Run Commands

The exec endpoint runs a command inside a running session and streams the output as Server-Sent Events (SSE). Each named SSE event carries one chunk of output.

Basic usage

curl

curl -N -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/exec \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd": ["python3", "-c", "import sys; print(6 * 7)"]}'
curl -N -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/exec \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd": ["python3", "-c", "import sys; print(6 * 7)"]}'

SSE event format

The raw response body is a series of SSE events separated by blank lines. Each event has a named event: field and a data: field:

SSE stream

event: stdout
data: {"data":"installing dependencies\n"}

event: stdout
data: {"data":"added 42 packages in 3.2s\n"}

event: exit
data: {"code":0,"error":""}
event: stdout
data: {"data":"installing dependencies\n"}

event: stdout
data: {"data":"added 42 packages in 3.2s\n"}

event: exit
data: {"code":0,"error":""}

Event types:

event	data fields	Meaning
`stdout`	`data: string`	A chunk of stdout output (single line, newlines stripped).
`exit`	`code: number, error: string`	Command finished. Stream ends after this event.

Note

If a command takes longer than 30 seconds and the stream appears to cut off, a proxy between your client and the API may be closing idle HTTP connections. See the troubleshooting guide for details.

timeoutMs

timeoutMs is the maximum time to wait for the command to finish, in milliseconds. The minimum is 1 ms, the maximum is 300,000 ms (300 seconds). The default is 30,000 ms (30 seconds).

5-minute exec

{
  "cmd": ["sleep", "120"],
  "timeoutMs": 300000
}
{
  "cmd": ["sleep", "120"],
  "timeoutMs": 300000
}

Environment variables

Pass additional environment variables for this exec with the env object. These are merged with the session environment and do not persist across exec calls.

Body

{
  "cmd": ["node", "-e", "console.log(process.env.MY_VAR)"],
  "env": {
    "MY_VAR": "hello from env"
  }
}
{
  "cmd": ["node", "-e", "console.log(process.env.MY_VAR)"],
  "env": {
    "MY_VAR": "hello from env"
  }
}

Working directory

Set workingDir to change the working directory for the command. The directory must exist inside the session.

Body

{
  "cmd": ["ls", "-la"],
  "workingDir": "/workspace/my-project"
}
{
  "cmd": ["ls", "-la"],
  "workingDir": "/workspace/my-project"
}

Exit codes

The exit event carries the command exit code. 0 means success. Any non-zero value means the command failed. This mirrors standard Unix exit code conventions.

If the command is killed by a timeout, the exit code will be -1.