Appearance

Getting started ​

Install ​

bash
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):

bash
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 ​

When credentials is omitted, provider keys are read from environment variables such as ANTHROPIC_API_KEY and OPENAI_API_KEY:

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

On a configured development machine, opt into local credentials:

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

All modes (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:

ts
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:

ts
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

First run: a structured task ​

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

ts
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 ​

Validating this repository ​

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