Skip to main content
The Command Execution API enables running shell commands within the sandbox with support for both foreground (streaming) and background (detached) execution modes. Commands can be monitored, interrupted, and their output can be retrieved on demand.

​
Execute Command

curl -X POST http://localhost:44772/command \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /workspace",
    "cwd": "/workspace",
    "background": false,
    "timeout": 30000
  }'
Executes a shell command and streams the output in real-time using SSE (Server-Sent Events). The command can run in foreground or background mode.
​
command
string
required
Shell command to execute
​
cwd
string
Working directory for command execution (defaults to sandbox working directory)
​
background
boolean
default:false
Whether to run command in detached mode.
  • false: Streams output in real-time (foreground)
  • true: Runs in background, retrieve logs via /command/{id}/logs
​
timeout
integer
Maximum allowed execution time in milliseconds before the command is forcefully terminated by the server. If omitted, the server will not enforce any timeout.
​
type
string
Event type: init, status, stdout, stderr, execution_complete, error, ping
​
text
string
Output text for stdout/stderr events
​
timestamp
integer
When the event was generated (Unix milliseconds)
​
execution_time
integer
Total execution duration in milliseconds (on completion)
data: {"type":"init","text":"cmd-abc123","timestamp":1700000000000}

data: {"type":"stdout","text":"total 24\n","timestamp":1700000000100}

data: {"type":"stdout","text":"drwxr-xr-x 3 admin admin 4096 Nov 16 10:30 .\n","timestamp":1700000000101}

data: {"type":"stdout","text":"drwxr-xr-x 5 admin admin 4096 Nov 16 10:25 ..\n","timestamp":1700000000102}

data: {"type":"execution_complete","execution_time":250,"timestamp":1700000000250}

​
Get Command Status

curl -X GET http://localhost:44772/command/status/cmd-abc123 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Returns the current status of a command (foreground or background) by command ID. Includes running flag, exit code, error (if any), and start/finish timestamps.
​
id
string
required
Command ID returned by RunCommand (from the init event)
​
id
string
Command ID
​
content
string
Original command content
​
running
boolean
Whether the command is still running
​
exit_code
integer
Exit code if the command has finished (null if still running)
​
error
string
Error message if the command failed
​
started_at
string
Start time in RFC3339 format
​
finished_at
string
Finish time in RFC3339 format (null if still running)
{
  "id": "cmd-abc123",
  "content": "python server.py",
  "running": true,
  "exit_code": null,
  "error": "",
  "started_at": "2025-12-22T09:08:05Z",
  "finished_at": null
}

​
Get Background Command Logs

curl -X GET http://localhost:44772/command/cmd-abc123/logs \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Returns stdout and stderr for a background (detached) command by command ID. Foreground commands should be consumed via SSE; this endpoint is intended for polling logs of background commands.
This endpoint supports incremental reads similar to a file seek. Pass a starting line via the cursor parameter to fetch output after that line and receive the latest tail cursor for the next poll.
​
id
string
required
Command ID returned by RunCommand
​
cursor
integer
Optional 0-based line cursor (behaves like a file seek). When provided, only stdout/stderr lines after this line are returned. If omitted, the full log is returned.
​
body
string
Plain text output containing stdout and stderr combined
​
EXECD-COMMANDS-TAIL-CURSOR
integer
Highest available 0-based line index after applying the request cursor. Use this value as the next cursor for incremental reads.
line1
line2
warn: something on stderr
line4

​
Interrupt Command Execution

curl -X DELETE "http://localhost:44772/command?id=session-456" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Interrupts the currently running command execution in the specified context. This sends a signal to terminate the execution process and releases associated resources.
​
id
string
required
Session ID of the execution context to interrupt
{}

​
Foreground vs Background Mode

​
Foreground Mode (background: false)

  • Output is streamed in real-time via SSE
  • Connection remains open until command completes
  • Ideal for short-running commands and interactive use
  • Example: ls, grep, find
{
  "command": "ls -la /workspace",
  "background": false
}

​
Background Mode (background: true)

  • Command runs in detached mode
  • Returns immediately with command ID
  • Use /command/status/{id} to check status
  • Use /command/{id}/logs to retrieve output
  • Ideal for long-running processes and servers
  • Example: python server.py, npm run dev
{
  "command": "python server.py",
  "background": true,
  "timeout": 300000
}

​
Timeout Handling

When you specify a timeout (in milliseconds), the server will automatically terminate the command if it exceeds the specified duration: 
{
  "command": "sleep 60",
  "timeout": 5000  // Killed after 5 seconds
}
If the command is terminated due to timeout:
  • The process receives a termination signal
  • The status will show exit_code: null and an error message
  • For foreground commands, you’ll receive an error event in the stream

​
Use Cases

​
Run Tests

{
  "command": "pytest tests/ -v",
  "cwd": "/workspace",
  "background": false,
  "timeout": 60000
}

​
Start Development Server

{
  "command": "npm run dev",
  "cwd": "/workspace/app",
  "background": true
}

​
Build Project

{
  "command": "make build",
  "cwd": "/workspace",
  "background": false,
  "timeout": 300000
}

​
Search Files

{
  "command": "grep -r 'TODO' /workspace --include='*.py'",
  "cwd": "/workspace",
  "background": false
}

Build docs developers (and LLMs) love

Get started for freeTalk to us