runcell

Give an agent a workspace. Get back validated results.

Runcell is a TypeScript runtime for agents that work with files and tools. Select a catalog model or register a provider, seed a sandbox with files, and receive streamed text, file changes, or schema-validated data. Threads and snapshots serialize to JSON for application-managed persistence.

import { createAgent, createThread } from 'runcell';
import { z } from 'zod';

const agent = createAgent({ model: 'anthropic/claude-sonnet-4-5' });

// A chat turn: no schema, the streamed text is the reply.
const thread = createThread();
const { textStream, result } = agent.stream({ prompt: 'Hi!', thread });
for await (const delta of textStream) process.stdout.write(delta);
await result;

// A structured task: result.data is validated against the schema.
const review = await agent.run({
  prompt: 'Review index.ts and report risks.',
  files: [{ path: 'index.ts', text: source }],
  schema: z.object({ risks: z.array(z.string()) }),
});

What it does

runcell gives an agent a sandbox workspace and gives you back values your application can rely on:

• Streaming: agent.stream() returns { textStream, result }. Pipe deltas to a UI and await the final result.
• Structured output: pass any Standard Schema validator (Zod 3/4, Valibot, ArkType). Runcell validates the agent's submission, runs repair turns when the model misses, and fails the run when repairs do not help. Omit the schema for plain text turns.
• Sandboxes: ephemeral by default. Or create a caller-owned handle: reuse it across runs, exec/read/write it directly, snapshot() it to JSON and restore it elsewhere. Runcell does not destroy caller-owned sandboxes.
• Threads: conversation state represented by a readable message log and continuation data. Store toJSON() in your database and resume it on another sandbox or machine.
• Files, tools, and events: seed files, retrieve changed files as bytes, expose host functions, receive lifecycle callbacks, and use extension hooks to block tool calls.
• Local credentials: credentials: 'local' can use supported provider logins on a development machine. Provider terms govern subscription use. Production use requires explicit opt-in.
• Shared credentials: credentials: { type: 'shared' } takes a lockable store for deployments that share refreshable credentials. The official Postgres implementation is @runcell/postgres-credentials.
• Credential fallback: pass an array of sources. If a run fails with a credential error before any tool runs, runcell retries it on the next source.

Install

npm install runcell        # zod is optional and used for structured output

Quick start

import { createAgent, createVirtualSandbox, createThread } from 'runcell';

// Credentials default to environment variables; use 'local' on a dev machine.
const agent = createAgent({
  model: 'anthropic/claude-sonnet-4-5',
  credentials: 'local',
});

// The application owns and persists sandbox and thread state.
const sandbox = await createVirtualSandbox();
const thread = createThread();

await agent.run({ prompt: 'Scaffold a TypeScript project.', sandbox, thread });
await agent.run({ prompt: 'Now add tests.', sandbox, thread }); // same files, remembers

console.log(await sandbox.readTextFile('package.json'));
await db.save(thread.id, thread.toJSON());
await sandbox.destroy();

Sandbox modes

await agent.run({ prompt }); // virtual (bundled, default)
await agent.run({
  prompt,
  sandbox: { type: 'host', rootDir, isolation: 'external' },
});
await agent.run({ prompt, sandbox: { type: 'vercel', runtime: 'node24' } });
await agent.run({ prompt, sandbox: { type: 'custom', provider } });

host is for externally-isolated environments only (CI, containers, VMs). vercel requires Node.js 22+ and the optional @ai-sdk/sandbox-vercel peer dependency.

Models

model accepts an id, a display name, or a provider-qualified id when the same model exists under several providers:

createAgent({ model: 'anthropic/claude-sonnet-4-5' });
createAgent({ model: 'openai-codex/gpt-5.5' });

Documentation

Visit runcell.run for guides covering chat agents, sandboxes, threads, streaming, structured output, credentials, and the full API reference.