Runtime

How to run an AI SDK HarnessAgent in a Runtime sandbox

Pass createRuntimeSandbox() as the HarnessAgent's sandbox, and Claude Code, Codex or Pi runs its whole loop in a microVM.

The agent definition stays the same: only the sandbox line changes, and 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 own loop, with its bootstrap, its bridge and every shell command, 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.124 was the current npm release on 25 September 2026, and on that day 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. Swap @ai-sdk/harness-claude-code for 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) reach a bridge process in the sandbox over a WebSocket on the first port in ports; Pi runs on the host and needs none. 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, so no model is called and every step is repeatable:

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, and 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, the default for batch jobs that should leave nothing behind.

Keys and limits

  • The model key stays with the harness configuration you pass; Runtime sees commands and files.
  • A refused Runtime key raises the AI SDK's HarnessSandboxAuthenticationError, so an app can tell a configuration mistake from an outage.
  • create sets the machine: vcpu, memoryMiB, image, network and the lease, as Sandbox.create takes them.
  • A daily spending limit on the key bounds every session together (daily limits).

What it costs

CPU is billed as used at $0.025 per vCPU-hour, with a floor of 50 millicores, and reserved memory at $0.0075 per GiB-hour. A harness spends most of a turn waiting for model tokens, near the floor; a turn that compiles and tests keeps both CPUs busy at $0.08 an hour for 2 vCPU and 4 GiB (pricing). New accounts get 100 free sandbox hours without a card.

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 September 2026.

Facts on this page were checked on 25 September 2026.

Claim 100 hours free