Getting started

Install

npm install runcell

If you want structured output, also install a Standard Schema-compatible validation library. The examples use Zod (v3 and v4 both work):

npm install runcell zod

The default virtual sandbox is bundled, so a basic run needs no additional sandbox package. Providers such as Vercel Sandbox are separate installs; see Sandboxes.

Credentials

The fastest path is a subscription you already have — Claude Pro/Max, ChatGPT Plus/Pro, or GitHub Copilot. Log in once through the bundled Pi CLI, then use credentials: 'local':

npx pi     # then type /login and pick your provider

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

For production, omit credentials and provider keys are read from environment variables such as ANTHROPIC_API_KEY and OPENAI_API_KEY:

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

All modes (subscriptions, API keys, shared stores, custom directories) are covered in Credentials.

Models

model accepts a model id, a display name, or a provider-qualified id. When the same model id exists under several providers, qualify it to pin the one you hold credentials for:

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

First run: a plain turn

Without a schema, the model's text is the output:

import { createAgent } from 'runcell';

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

const reply = await agent.run({ prompt: 'Say hello in one sentence.' });
console.log(reply.text); // the reply
console.log(reply.finishReason); // "stop"
console.log(reply.data); // undefined because no schema was given
console.log(reply.usage); // token counts + costUsd for this run

Every result includes usage: per-run token counts and the estimated cost in US dollars at API list price. Subscription logins report the same as-if-API price, so you can track what a run would have cost.

First run: a structured task

With a schema, the agent must submit a payload matching it, and result.data is the validated, typed output:

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

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

const result = await agent.run({
  prompt: 'Summarize this project and suggest next steps.',
  schema: z.object({
    summary: z.string(),
    nextSteps: z.array(z.string()),
  }),
});

console.log(result.data.summary); // typed

Next steps

• Build a chat agent
• Persist a sandbox workspace
• Persist a thread
• Stream text to a UI
• Track token usage and cost

Validating this repository

npm run check                     # build, lint, typecheck, tests
RUNCELL_LIVE=1 RUNCELL_LIVE_CREDENTIALS=local npm run test:live