Skip to content

Commands and processes

Updated .md

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.

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

Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial