Commands and processes
Run a command to its end#
POST /v2/sandboxes/{id}:exec takes an ExecRequest and returns the Process it ran as, with its stdout and stderr. Runs a command as a process and returns it once it ended, with its output; with wait false, at once, while it runs. A paused sandbox is resumed first. Asked again with the same Idempotency-Key, it runs nothing more: it returns the first run's process, waiting for its end while it runs.
| Field | |
|---|---|
cmd |
The command: text, run by bash -lc ("npm test"), or a list, the program and its arguments run without a shell (["npm", "test"]). |
cwd |
The directory it runs in; the user's home when omitted. |
env |
Environment variables to add. |
stdin |
Bytes sent to its standard input. |
timeoutSeconds |
Seconds it may run before it is stopped (1.5 for 1,500 ms); it runs to its end when omitted or 0. |
For pipes, && or shell variables, run the command through a shell: ["bash", "-c", "cd /tmp && ls | wc -l"]. Keep untrusted input out of the shell's text: pass it in env or stdin.
Pythonimport base64from withruntime.generated import Runtimeruntime = Runtime()sandbox = runtime.sandboxes.create()try: words = base64.b64encode(b"one two three\n").decode() result = runtime.sandboxes.exec(sandbox.id, cmd=["wc", "-w"], stdin=words) print(result.stdout.strip()) # 3 assert result.stdout.strip() == "3", resultfinally: runtime.sandboxes.delete(sandbox.id)Start a process#
POST /v2/sandboxes/{id}:exec with wait false starts a program and returns its Process at once, while it runs. Use it for servers, watchers and interpreters.
GET /v2/sandboxes/{id}/processes/{process}/outputreads its output from a byte cursor.waitSeconds: Seconds to wait for output past the cursor or its exit, at most 8.POST /v2/sandboxes/{id}/processes/{process}:writesends it input, when it was started withstdinOpen.POST /v2/sandboxes/{id}/processes/{process}:signalsends it a signal, such asSIGTERM.- Each output read returns the process too: its
state, and itsexitCodeonce it ended.
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const sandbox = await runtime.sandboxes.create({});try { const p = await runtime.sandboxes.exec(sandbox.id, { cmd: "for i in 1 2 3; do echo line $i; done", wait: false }); let cursor = 0; let text = ""; for (let reads = 0; reads < 10; reads++) { const out = await runtime.sandboxes.processOutput(sandbox.id, p.id, { cursor, waitSeconds: 2 }); for (const chunk of out.chunks) text += chunk.text; cursor = out.nextCursor; if (out.process && out.process.state !== "running") break; } console.log(text); if (!text.includes("line 3")) throw new Error(text);} finally { await runtime.sandboxes.delete(sandbox.id);}Give this to your agent#
Paste this into your coding agent:
Read https://withruntime.com/docs/commands.md. In this project, run short commands with exec and servers or interactive programs as processes, and make sure every process is stopped or its sandbox deleted when the work ends.
This page as Markdown: https://withruntime.com/docs/commands.md