Skip to content

Run an agent's code

An agent that writes code needs a place to run it that can't reach your machine. Give each agent session one sandbox: the model's code runs there, and files and installed packages stay between steps.

Updated .md

The loop#

Each step writes the model's code to a file, runs it with POST /v2/sandboxes/{id}:exec and returns the result to the model. A command that fails returns a result with a non-zero exitCode and its stderr, so the model can read the error and try again.

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();// Stand-ins for what your model writes: a first attempt with a bug, then the fix.const attempts = ["rows = [i * i for i in range(5)]\nprint(total)\n", "rows = [i * i for i in range(5)]\nprint(sum(rows))\n"];const sandbox = await runtime.sandboxes.create({ labels: { session: "example" } });try {  for (const [step, code] of attempts.entries()) {    const path = `/tmp/step${step}.py`;    await runtime.sandboxes.write(sandbox.id, new TextEncoder().encode(code), { path });    const result = await runtime.sandboxes.exec(sandbox.id, { cmd: ["python3", path], timeoutSeconds: 30 });    // Return this to the model as the tool's result.    const feedback = { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, state: result.state };    console.log(step, JSON.stringify(feedback));    if (result.exitCode === 0) break;  }} finally {  await runtime.sandboxes.delete(sandbox.id);}
Pythonfrom withruntime.generated import Runtimeruntime = Runtime()attempts = ["print(total)\n", "print(sum(i * i for i in range(5)))\n"]sandbox = runtime.sandboxes.create(labels={"session": "example"})try:    for step, code in enumerate(attempts):        path = f"/tmp/step{step}.py"        runtime.sandboxes.write(sandbox.id, code.encode(), path=path)        result = runtime.sandboxes.exec(sandbox.id, cmd=["python3", path], timeout_seconds=30)        print(step, result.exit_code, result.stdout or result.stderr.splitlines()[-1])        if result.exit_code == 0:            breakfinally:    runtime.sandboxes.delete(sandbox.id)

What to return to the model#

Return exitCode, stdout and stderr. Two more fields say when the output is not the whole story:

  • state: timed_out when it was still running at its timeout and was stopped. Set the limit with timeoutSeconds: Seconds it may run before it is stopped (1.5 for 1,500 ms); it runs to its end when omitted or 0.
  • stdoutTruncated and stderrTruncated: stdout holds only part of what it wrote (its first 1 MiB). Have the model write large output to a file and read the part it needs.

Long-running and interactive code#

POST /v2/sandboxes/{id}:exec runs a command to its end. For a server, a watcher or an interpreter the model keeps talking to, start it with POST /v2/sandboxes/{id}:exec and wait false, send it input with POST /v2/sandboxes/{id}/processes/{process}:write and read its output with GET /v2/sandboxes/{id}/processes/{process}/output. See commands and processes.

One sandbox per session#

  • Create the sandbox when the session starts, and delete it when the session ends. Label it (labels) with the session's ID, so you can find and delete sandboxes a crashed worker left behind with GET /v2/sandboxes.
  • Give it a name (name) and set getOrCreate to reuse the session's sandbox after a restart: With a name: the sandbox of that name when there is one, else a new one.
  • Between steps, a sandbox with nothing happening pauses by itself and resumes on the next call. See pause and resume.
  • To start many sessions from the same prepared state, prepare one sandbox and fork it with POST /v2/sandboxes/{id}:fork. See snapshots and forks.

Limit what the code can reach#

The model's code runs as root inside its own kernel, never on your servers. To control what it can reach on the network, set the sandbox's network rules with PUT /v2/sandboxes/{id}/network (networking). To let it call an API without seeing the key, store the key as a secret.

Give this to your agent#

Paste this into your coding agent:

Read https://withruntime.com/docs/agent-loop.md. Add a code-execution tool to this project's agent that runs each piece of model-written code in one Runtime sandbox per session, returns stdout, stderr and the exit code to the model, and deletes the sandbox when the session ends.

This page as Markdown: https://withruntime.com/docs/agent-loop.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