---
title: "Vercel AI SDK: a run_code tool and a sandbox session"
description: "@shotcup/ai-sdk for the Vercel AI SDK: shotcupTool() runs model-written code with your tools, and a sandbox session keeps files between steps."
canonical: "https://shotcup.dev/docs/ai-sdk"
last_updated: "2026-10-18"
---
# Vercel AI SDK: a run_code tool and a sandbox session

`@shotcup/ai-sdk` connects Shotcup to the Vercel AI SDK in two ways:
`shotcupTool()` is a `run_code` tool that runs the JavaScript a model
writes in a fresh sandbox, and `createShotcupSandbox()` is a sandbox
session over a saved sandbox, for agents that keep files between steps.

The package is not published to npm yet, and neither is the `shotcup` SDK
it builds on. Until they are, a plain tool that calls the REST API does the
same job ([below](#until-the-package-is-published)). Once they are:

```sh
bun add @shotcup/ai-sdk shotcup ai
```

## A run_code tool

```ts
import { generateText } from "ai";
import { createClient } from "shotcup";
import { shotcupTool } from "@shotcup/ai-sdk";

const shotcup = createClient({ apiKey: process.env.SHOTCUP_API_KEY });

const { text } = await generateText({
  model,
  tools: { run_code: shotcupTool({ client: shotcup }) },
  prompt: "Compute the first 20 Fibonacci numbers and write them to /out/fib.json.",
});
```

The model sends `code` (run as `/main.js`) or `files` with an `entry`, and
may ask for `engine` switches or private artifact links. A file is text,
base64 for binary inputs such as images, or `{ path, url }` to import an
`https` file. The tool answers with the run's status, stdout and stderr
(clipped to `maxOutputChars`, 16,000 characters by default), the exit code,
the paths the run changed, the files under `/out` (inline when small,
otherwise by link) and the run's metrics. When the code used a construct
the language profile leaves out, `hint` says what to write instead, and
`hint.fix` carries the repair when it is mechanical, so the model can fix
its code in its next step.

`shotcupTool()` takes these options besides `client`:

| Option | What it does |
|---|---|
| `sandboxId` | Runs every call in that saved sandbox, so files stay between calls; without it every call is a fresh, disposable run |
| `description` | Replaces the tool's description, which tells the model what the sandbox can do |
| `engine`, `fonts` | Default engine switches (the model may send its own) and catalogue fonts for every run |
| `deterministic`, `timeoutMs` | The run's clock and its time limit; runs are deterministic by default |
| `tools`, `toolHandlers` | Functions the model's code may call, below |
| `onInterrupt` | Receives a paused run's continuation, below |
| `maxOutputChars` | How much stdout, stderr and inline file content goes back to the model |

The AI SDK's `abortSignal` cancels the run.

## Code mode with your own tools

In [code mode](https://shotcup.dev/docs/code-mode) the model's program calls your tools as
functions instead of the model calling them one turn at a time. Give the
tool `toolHandlers`, and the program calls them as `tools.<name>(...)`;
dotted names become nested objects. Each call is answered live by your
handler while the run is going:

```ts
const runCode = shotcupTool({
  client: shotcup,
  description:
    "Runs JavaScript (ES modules, arrow functions, const/let, for...of) in a Shotcup sandbox. " +
    "Call await tools.crm.listCustomers({ segment }) and await tools.billing.getInvoices({ since }) " +
    "for data; print a short answer and write larger results under /out.",
  toolHandlers: {
    crm: { listCustomers: async (query) => crm.customers(query) },
    billing: { getInvoices: async (query, { signal }) => billing.invoices(query, { signal }) },
  },
});
```

The model only knows about these functions if you tell it, in the tool's
`description` or in the system prompt. A handler that declares one more
parameter than the script passes gets a context with a `signal` that
aborts when the run ends. The rows your handlers return stay in the
sandbox; only what the program prints or writes goes back to the model.

A call to a declaration in `tools` with `approval: true` pauses the run
instead of calling a handler. Without `toolHandlers`, a call to any
declared tool pauses it too, except the built-in `echo`. The tool result
then has `status: "interrupted"` and `interrupt` with the pending calls,
so the model sees what is waiting. It never contains the run's
continuation token, because the tool result is the model's context. The
token goes to your `onInterrupt` option instead, with the AI SDK's
`toolCallId`, the run's id and a `resume` function, before the tool result
returns:

```ts
const runCode = shotcupTool({
  client: shotcup,
  tools: [{ name: "payments.refund", approval: true }],
  onInterrupt: async ({ toolCallId, runId, requests, token }) => {
    await approvals.save({ toolCallId, runId, requests, token });
  },
});
```

Keep the token out of the conversation. Once someone has decided,
`shotcup.runs.resume(runId, token, results)` continues the run from any
process. Without `onInterrupt` nothing can resume the run, and the tool
result tells the model so. [Durable code mode](https://shotcup.dev/docs/durable-code-mode)
explains pausing and resuming.

## A sandbox session

`createShotcupSandbox()` implements the AI SDK's experimental sandbox
session (`Experimental_SandboxSession`) over a Shotcup saved sandbox:

```ts
import { createShotcupSandbox } from "@shotcup/ai-sdk";

const sandbox = createShotcupSandbox({ client: shotcup, create: { name: "agent workspace" } });
await sandbox.writeTextFile({ path: "/main.js", content: 'console.log("hi")' });
const { exitCode, stdout } = await sandbox.run({ command: "shotcup run /main.js" });
await sandbox.delete();
```

The session reads and writes the sandbox's files, text or binary, and runs
an entry module. A Shotcup sandbox has no shell: `run({ command })` accepts
`shotcup run <entry>` (or just the entry's absolute path) with the switches
`--compat`, `--ast`, `--vitest` and `--canvas`, and refuses anything
else with an error that says so, so an agent that tries `ls` or `npm test`
learns what to do instead. A run is one shot: `spawn` wraps `run`, and
`kill` only discards the output. `run` returns the exit code, stdout and
stderr; `lastRun()` returns the whole last run, with a paused run's token,
so keep it out of what you hand the model. `mounts` mounts
[drives](https://shotcup.dev/docs/drives) into every run of the session.

## Until the package is published

An AI SDK tool that calls the REST API directly:

```ts
import { tool } from "ai";
import { z } from "zod";

export const runCode = tool({
  description:
    "Runs JavaScript (ES modules, arrow functions, const/let, for...of; no npm, no Node APIs besides fs) " +
    "in a fresh Shotcup sandbox. Write results under /out.",
  inputSchema: z.object({ code: z.string() }),
  execute: async ({ code }, { abortSignal }) => {
    const response = await fetch("https://shotcup.dev/api/v1/runs", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SHOTCUP_API_KEY}`,
        "Content-Type": "application/json",
        // optional: tells Shotcup the run came from this guide
        "X-Shotcup-Integration": "ai-sdk-guide",
      },
      body: JSON.stringify({ code }),
      signal: abortSignal,
    });
    const data = await response.json();
    if (!response.ok) return { error: data.error };
    const { status, error, stdout, stderr, hint, artifacts } = data.run;
    return { status, error, stdout, stderr, hint, artifacts: artifacts.map(({ path, url }) => ({ path, url })) };
  },
});
```

The [quickstart](https://shotcup.dev/docs/quickstart) has the rest of the request and the
answer.
