Code Mode in the Sandbox

npm add @rivet-dev/pi @rivet-dev/sandbox-adapter @earendil-works/pi-durable rivetkit@next

ANTHROPIC_API_KEY=sk-ant-...
RIVET_ENDPOINT=https://<namespace>:<rivet-token>@api.rivet.dev

// Outside the workspace, so the agent doesn't commit it.
export const SCRIPT_PATH = "/tmp/call-tool.sh";

// The maximum. The script is rewritten after every wake.
const TOKEN_TTL_SECONDS = 24 * 60 * 60;

// Writes the script into every sandbox the agent connects to.
export function withCallbackScript(provider: SandboxProvider): SandboxProvider {
	return {
		...provider,
		connect: async (c, id) => {
			const sandbox = await provider.connect(c, id);
			if (sandbox) await writeScript(sandbox, c);
			return sandbox;
		},
	};
}

async function writeScript(sandbox: Sandbox, c: SandboxActorContext): Promise<void> {
	// The agent's own client uses your Rivet token. The scoped token reaches only
	// this Actor, but can call every action on it.
	const client = c.client() as Client<typeof registry>;
	const { token } = await client.agent.getForId(c.actorId).issueToken({ subject: "sandbox", expiresIn: TOKEN_TTL_SECONDS });
	await sandbox.writeFile(SCRIPT_PATH, callbackScript(`${gatewayEndpoint()}/gateway/${c.actorId}`, token));
	const chmod = await sandbox.exec(`chmod 700 ${SCRIPT_PATH}`, { cwd: sandbox.cwd });
	if (chmod.exitCode !== 0) throw new Error(`Installing ${SCRIPT_PATH} failed. ${chmod.stderr}`);
}

// Coding tools run in the sandbox. The section tells the model about the script.
const extensions = createRegistry();
extensions.install(CodingTools);
extensions.install(
	defineExtension({
		name: "agent-callbacks",
		sections: [
			section(
				"agent_callbacks",
				() => `To call the app that runs you, use bash to run:
${SCRIPT_PATH} <tool> '<JSON array of arguments>'
It prints {"output": <result>}, or exits non-zero with an error.

Tools:
- progress ["<message>"]: Shows the user a one-line status. Call it as you start each step of a task.
- saveNote ["<text>"]: Saves a note that is kept after the sandbox is deleted.
- listNotes []: Returns every saved note.
- getReadings ["<sensor>", <cursor>]: Returns {"readings": [...], "next": <cursor or null>}, 1,000 readings a page, one a minute for a week. Start at cursor 0. Sensors: ${SENSORS.join(", ")}.

Example: ${SCRIPT_PATH} progress '["Running the tests"]'`,
			),
		],
	}),
);

export const agent = pi({
	model: "anthropic/claude-opus-5-5",
	registry: extensions,
	// Writes call-tool.sh into the sandbox. The image has curl, Node.js, and Python with numpy.
	// Docker is only for local development, where the sandbox can reach the control plane
	// on this machine. In production, switch to a hosted sandbox provider such as Daytona
	// or E2B, and set RIVET_PUBLIC_ENDPOINT to an address the sandbox can reach.
	sandbox: withCallbackScript(dockerProvider({ image: "sandbox-code-mode" })),
	state: { notes: [] as string[] },
	events: {
		progress: event<string>(),
	},
	// The tools call-tool.sh calls. Each one is an action on the agent.
	actions: {
		progress: (c, message: unknown) => {
			c.broadcast("progress", requireText(message));
			return null;
		},
		saveNote: (c, text: unknown) => {
			c.state.notes.push(requireText(text));
			return { saved: c.state.notes.length };
		},
		listNotes: (c) => c.state.notes,
		// In a real app, this queries your metrics database with your keys.
		getReadings: (_c, sensor: unknown, cursor: unknown) => readingsPage(sensor, cursor),
	},
});

function requireText(value: unknown): string {
	if (typeof value !== "string" || value.length === 0) throw new UserError("Pass a non-empty string.");
	return value;
}

npx tsx server.ts

import { createInterface } from "node:readline";
import { createClient } from "rivetkit/client";
import type { registry } from "./server";

// One agent per key. Pass a key to pick up an earlier session: `npx tsx cli.ts my-session`.
const client = createClient<typeof registry>();
const agent = client.agent.getOrCreate([process.argv[2] ?? "demo"]).connect();

// Status the agent sends from the sandbox through call-tool.sh.
agent.on("progress", (message) => console.log(`\n[progress] ${message}`));

// Everything else the agent does: its answer as it streams, and each tool it runs.
let streamed = false;
agent.on("pi.events", ({ events }) => {
	for (const event of events) {
		if (event.type === "message_update") {
			for (const change of event.changes) {
				if (change.type === "text_delta") {
					process.stdout.write(change.delta);
					streamed = true;
				}
			}
		}
		if (event.type === "tool_execution_start") {
			const call = event.toolName === "bash" ? `$ ${event.args.command}` : `${event.toolName} ${JSON.stringify(event.args)}`;
			console.log(`\n> ${call}`);
		}
	}
});
await agent.conversation.watchEvents((await agent.harness.root()).id);

// Reads one prompt per line until Ctrl-D.
const input = createInterface({ input: process.stdin, output: process.stdout, prompt: "\nyou> " });
let closed = false;
input.on("close", () => (closed = true));
input.prompt();
for await (const line of input) {
	if (line.trim()) {
		streamed = false;
		const result = await agent.prompt(line, { requestId: crypto.randomUUID() });
		if (result.status === "unanswered") console.log(`\n(no answer: ${result.reason})`);
		// A short answer can arrive whole, without streaming.
		else if (!streamed) console.log(result.text);
		console.log(`\nnotes: ${JSON.stringify(await agent.listNotes())}`);
	}
	if (!closed) input.prompt();
}
await agent.dispose();

npx tsx cli.ts

you> In a single Python script, pull every reading for every sensor with getReadings, use numpy to find spikes more than 5 standard deviations from a rolling mean, find which two sensors are most correlated, and save a note for each spike. Keep your answer short.

> write {"path":"/workspace/spikes.py","content":"..."}
> $ python3 /workspace/spikes.py
[progress] Fetching readings for 5 sensors
[progress] Saving 4 spike notes
Boiler and pump are the most correlated pair (r = 0.95). I found 4 spikes:

| Sensor | Minute | Value | z     |
|--------|--------|-------|-------|
| tank   | 1234   | 77.18 | +45.9 |
| boiler | 4321   | 90.92 | +29.2 |
| pump   | 7777   | 25.25 | -29.7 |
| tank   | 9001   | 75.64 | +40.4 |

notes: ["Spike: boiler at minute 4321 = 90.92 (z=+29.2)", ...]