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.
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_outwhen it was still running at its timeout and was stopped. Set the limit withtimeoutSeconds: Seconds it may run before it is stopped (1.5for 1,500 ms); it runs to its end when omitted or 0.stdoutTruncatedandstderrTruncated: 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 withGET /v2/sandboxes. - Give it a name (
name) and setgetOrCreateto 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