# runcell

> TypeScript runtime for running AI agents in sandboxes with structured
> results, file outputs, persistent threads, and per-run token/cost usage.
> npm: `runcell`. Chat frontends (assistant-ui, AI SDK useChat) connect with
> zero glue via the UI Message Stream protocol.

## Credentials, the short version

- Default (omit `credentials`): reads env vars. Exact passthrough: any
  `*_API_KEY`, any `*_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `VERCEL_OIDC_TOKEN`.
  Provider variable = provider id upper-cased + `_API_KEY`
  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY` for the
  Vercel AI Gateway).
- `credentials: 'local'`: uses subscription logins from `~/.pi/agent`.
  The login (`npx pi`, then `/login`) is interactive with a browser
  sign-in. A HUMAN must run it once per machine. An AI agent cannot.
  Check `~/.pi/agent/auth.json` exists instead of launching the TUI.
- NEVER create or edit `~/.pi/agent/auth.json` by hand. Never commit it.
- If neither logins nor API keys exist, stop and ask the human. There is
  no credential an agent can generate.
- Production with shared refreshable credentials:
  `credentials: { type: 'shared' }` with `@runcell/postgres-credentials`.
- Fallback: pass an array (`credentials: [sourceA, sourceB]`) to try
  sources in order. The run moves to the next source only on a credential
  error before any tool runs. `onCredentialFallback` reports each move.

## Files and attachments

- File parts in `messages` become workspace files under `attachments/`
  (data URLs only, 20 MB each by default via `maxAttachmentBytes`).
- PDFs: install the optional peers `pdfjs-dist` and `@napi-rs/canvas` to
  enable the built-in `readPdfPages` tool.

## Docs

- Getting started: https://runcell.run/getting-started
- Credentials (decision table + agent rules): https://runcell.run/credentials
- Chat frontends (assistant-ui / useChat): https://runcell.run/integrations/assistant-ui
- Streaming and UI Message Stream: https://runcell.run/streaming
- Sandboxes: https://runcell.run/sandboxes
- Threads: https://runcell.run/threads
- Structured output: https://runcell.run/structured-output
- API reference: https://runcell.run/api