Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jaypopat/cf_ai_duet/llms.txt

Use this file to discover all available pages before exploring further.

Executes a shell command in the isolated sandbox environment associated with a room. Unlike the message endpoint, this executes commands directly without AI interpretation.

​
Endpoint

POST /api/rooms/{roomID}/sandbox/exec

​
Path Parameters

​
roomID
string
required
Unique identifier for the room. Each room has its own isolated sandbox instance named sandbox-{roomID}.

​
Request Body

​
cmd
string
required
The shell command to execute. Must be at least 1 character long.
cmd: z.string().min(1, "Command cannot be empty")

​
Response

​
result
ExecResult
The execution result containing stdout and stderr streams.
​
sandboxName
string
The name of the sandbox instance that executed the command (format: sandbox-{roomID}).

​
Example Request

curl -X POST https://your-worker.workers.dev/api/rooms/room-123/sandbox/exec \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "echo 'Hello from sandbox'"
  }'

​
Example Response

{
  "result": {
    "stdout": "Hello from sandbox\n",
    "stderr": ""
  },
  "sandboxName": "sandbox-room-123"
}

​
Error Responses

​
400 Bad Request

Returned when request validation fails: 
{
  "error": "invalid request",
  "details": {
    "cmd": ["Command cannot be empty"]
  }
}

​
404 Not Found

Returned when the room ID is missing or the endpoint path is incorrect.

​
405 Method Not Allowed

Returned when using a method other than POST.

​
500 Internal Server Error

Returned when sandbox execution fails: 
{
  "error": "sandbox execution failed: <error details>"
}

​
Use Cases

  • Direct command execution for scripting and automation
  • Testing and debugging sandbox environments
  • File system operations in the isolated environment
  • Running build commands or test suites

​
Implementation Reference

The handler uses Cloudflare’s sandbox API: 
// cf-worker/index.ts:210-242
const sandbox = getSandbox(this.env.Sandbox, `sandbox-${roomId}`);
const result = await sandbox.exec(data.cmd);
return Response.json({ result, sandboxName });

​
Sandbox Lifecycle

Each room has a persistent sandbox instance that:
  • Is created on first use
  • Maintains file system state between commands
  • Is isolated from other rooms’ sandboxes
  • Can be destroyed using the DELETE /api/rooms/ endpoint

Build docs developers (and LLMs) love

Get started for freeTalk to us