Processes & code execution

Run one-shot commands and code snippets inside a sandbox. Use exec for commands and run-code for snippets. For anything that has to outlive the request, use managed processes. For an interactive shell that stays alive, use the terminal.

Run a command

POST /v1/sandboxes/:id/exec runs one process. The call returns when the process exits or timeout_ms fires. The default timeout is 30 s. The maximum is 300 s.

For a server, build, watcher, or other task that should outlive the request, use a managed process instead.

An argv array runs with execve. A string runs with sh -c. sh() is shorthand for the string form. check() throws on a non-zero exit code.

const r = await sbx.exec(["python3", "-c", "print(2+2)"], { timeoutMs: 30_000 });
r.check();
const out = await sbx.sh("ls -la /tmp && date");

r = sbx.exec(["python3", "-c", "print(2+2)"], timeout_ms=30_000)
r.check()
out = sbx.sh("ls -la /tmp && date")

pt sandbox exec $ID 'python3 -c "print(2+2)"'

curl -X POST "$PT_API_URL/v1/sandboxes/$ID/exec" \
  -H "Authorization: Bearer $PT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd": ["python3", "-c", "print(2+2)"], "timeout_ms": 30000}'

The REST response wraps the result: { "result": { "ok": true, "stdout": "4\n", "exit_code": 0 } }.

No state between calls

Each call starts a new process. No state carries between calls. There is no per-call cwd or env. env values set at sandbox create (Sandboxes) apply to every call.

For a working directory, use a shell string: "cd /workspace && make".

Background processes

exec is for one-shot commands. To keep a server, build, or watcher running, start a managed process instead.

Run code

POST /v1/sandboxes/:id/run-code runs a code snippet in one call. lang is python (default), node, bash, or sh.

The matching interpreter must be installed in the sandbox. A missing interpreter exits 127 with empty output and no error, so check exit_code. Combined stdout + stderr over 16 MiB fails the call. Redirect large output to a file and download it.

const r = await sbx.runCode("print(2+2)", { lang: "python" });

r = sbx.run_code("print(2+2)", lang="python")

pt sandbox run-code $ID 'print(2+2)' --lang python

curl -X POST "$PT_API_URL/v1/sandboxes/$ID/run-code" \
  -H "Authorization: Bearer $PT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(2+2)", "lang": "python"}'

The response is flat: { stdout, stderr, exit_code, duration_ms, lang }.

Output is text only (stdout/stderr). For plots, images, or other files, write them to disk. Then fetch them with the filesystem API.

See also

• Managed processes — start a process that outlives the call
• Filesystem — read, write, and search files; watch for changes
• Terminal — interactive PTY over WebSocket
• Python SDK — async client AsyncPlatinum mirrors these methods 1:1
• API reference — full request/response schemas