How to run an AI SDK HarnessAgent in a Runtime sandbox

Only the sandbox line changes in the agent definition. The microVM costs $0.03125 an hour for 2 vCPU and 4 GiB while the harness waits on its model. HarnessAgent from @ai-sdk/harness runs a coding agent's loop. That loop includes its bootstrap, its bridge and every shell command. It runs in whatever sandbox provider it is given. Runtime's provider gives each session a Firecracker microVM with its own Linux kernel. @ai-sdk/harness 1.0.164 was the current npm release on 25 October 2026. On 25 September 2026, the provider passed all 19 checks of its end-to-end script against production sandboxes in 12.6 seconds.

Install

Terminalnpm install withruntime @ai-sdk/harness @ai-sdk/harness-claude-codenpx withruntime login

The login opens a browser approval and saves the key on the machine. A deployed app sets RUNTIME_API_KEY instead. Replace @ai-sdk/harness-claude-code with the harness package you use.

One session, one turn

TypeScriptimport { HarnessAgent, type HarnessAgentAdapter } from "@ai-sdk/harness/agent";import { createRuntimeSandbox } from "withruntime/ai-harness";export async function reviewRepo(harness: HarnessAgentAdapter) {  const agent = new HarnessAgent({    harness,    sandbox: createRuntimeSandbox({ ports: [4000] }),    instructions: "Read the repository and list its three riskiest functions.",  });  const session = await agent.createSession();  try {    const result = await agent.generate({ session, prompt: "Start with src/." });    return result.text;  } finally {    await session.destroy();  }}

harness is the adapter from the harness package, such as claudeCode from @ai-sdk/harness-claude-code. Bridge harnesses (Claude Code, Codex, OpenCode, Deep Agents) connect to a bridge process in the sandbox over a WebSocket. The bridge listens on the first port in ports. Pi runs on the host and needs no port. session.destroy() stops the machine, so billing ends with the session.

What the live run exercised

The script drives a real HarnessAgent with a scripted harness adapter. No model is called, so every step can be repeated:

Step	What was checked against a production sandbox
Session and turn	Create, the bootstrap recipe, env, working directory, stdin, a timeout, file I/O
Port for a bridge	A private preview reached over HTTPS with its token, and by WebSocket with the token in a header
Network policy	`deny-all` refuses an outbound request; `allow-all` brings it back
Pause and resume	`pauseOnStop` pauses; `resumeFrom` wakes the same machine with its files
Destroy	The sandbox reads `stopped`, and nothing carrying the run's label is left running

Keep a session between requests

A chat app that answers one turn per HTTP request can keep the same machine for a user:

Name it. agent.createSession({ sessionId: "user-42" }) names the sandbox ai-harness-user-42.
Pause instead of stopping. createRuntimeSandbox({ pauseOnStop: true }) makes session.stop() pause. Memory, processes and files are kept. Only paused storage is billed (paused storage).
Resume. agent.createSession({ sessionId: "user-42", resumeFrom }) wakes that machine where it left off.

Without pauseOnStop, session.stop() stops the sandbox. That is the default for batch jobs that should leave nothing behind.

Keys and limits

The model key stays in the harness configuration you pass. Runtime sees only commands and files.
A refused Runtime key raises the AI SDK's HarnessSandboxAuthenticationError. An app can then tell a configuration mistake from an outage.
create sets the machine: vcpu, memoryMiB, image, network and a time limit, as Sandbox.create takes them.
A daily spending limit on the key bounds all sessions together (daily limits).

What it costs

CPU is billed as used at $0.025 per vCPU-hour, with a floor of 50 millicores. Reserved memory is billed at $0.0075 per GiB-hour. A harness spends most of a turn waiting for model tokens, so its cost stays near the floor. A turn that compiles and tests keeps both CPUs busy. That costs $0.08 an hour for 2 vCPU and 4 GiB (pricing). A new account gets 100 free hours of a 1 GB machine in its first 30 days. No card is needed.

The full option table is in the Vercel AI SDK guide. To give a plain generateText call four sandbox tools instead of a whole harness, see Vercel AI SDK tools. The harnesses on their own are in Claude Code, Codex and OpenCode.

Sources

Checked 25 October 2026.

AI SDK HarnessAgent: the sandbox option, sessions and resumeFrom
@ai-sdk/harness on npm: version 1.0.164
withruntime on npm: version 0.35.0, which exports withruntime/ai-harness

Facts on this page were checked on 25 October 2026.