Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mattpocock/sandcastle/llms.txt

Use this file to discover all available pages before exploring further.

The Vercel provider runs Sandcastle agents inside Vercel Firecracker microVM sandboxes via the @vercel/sandbox SDK. Unlike the Docker and Podman providers, Vercel is an isolated provider: the sandbox has its own filesystem, so Sandcastle syncs your repository into the VM and extracts commits back to your host when the agent finishes. This makes Vercel a good fit for CI pipelines, cloud-based workflows, or any situation where you cannot or prefer not to run a local container daemon.

​
Prerequisites

Install @vercel/sandbox as a peer dependency alongside Sandcastle: 
npm install --save-dev @vercel/sandbox
You also need a Vercel account and an access token. Set VERCEL_TOKEN in your environment, or pass token directly to vercel(). In Vercel-hosted environments, VERCEL_OIDC_TOKEN is preferred and is read automatically by the SDK.

​
Import

import { vercel } from "@ai-hero/sandcastle/sandboxes/vercel";

​
Basic usage

Pass vercel() as the sandbox option to run(): 
import { run, claudeCode } from "@ai-hero/sandcastle";
import { vercel } from "@ai-hero/sandcastle/sandboxes/vercel";

await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: vercel(),
  promptFile: ".sandcastle/prompt.md",
});

​
How isolated providers work

Isolated providers differ from bind-mount providers in two important ways:
  • Code sync in: Sandcastle copies your repository into the sandbox filesystem before the agent runs. This replaces bind-mounting, which requires direct filesystem access to the host.
  • Commits out: After the agent runs, Sandcastle extracts the commits it created and applies them to the appropriate branch on your host.
Because isolated providers manage their own filesystem, the head branch strategy is not available — you cannot write directly to the host working directory from inside a VM. The default branch strategy for isolated providers is merge-to-head.
You do not need to build a container image to use the Vercel provider. Each run creates a fresh ephemeral microVM.

​
Branch strategy

Vercel is an isolated provider, so it defaults to merge-to-head. You can override this to use a named branch: 
await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: vercel(),
  branchStrategy: { type: "branch", branch: "agent/fix-42" },
  promptFile: ".sandcastle/prompt.md",
});
The head strategy ({ type: "head" }) is not supported for isolated providers and will produce a compile-time type error.

​
Options

All options are passed to vercel(): 
sandbox: vercel({
  token: process.env.VERCEL_TOKEN,
  runtime: "node24",
  resources: { vcpus: 2 },
  timeout: 300_000,
  env: { MY_TOKEN: "value" },
})
​
token
string
Vercel access token. Falls back to the SDK’s default auth behavior, which reads VERCEL_OIDC_TOKEN (recommended for Vercel-hosted environments) or VERCEL_TOKEN from the environment.
​
runtime
string
The runtime for the sandbox (e.g., "node24", "node22", "python3.13"). Defaults to "node24".
​
template
string
Shorthand alias for runtime (e.g., "node-22"). When both runtime and template are set, runtime takes precedence.
​
resources
{ vcpus: number }
Resources to allocate to the sandbox. Each vCPU gets 2048 MB of memory.
​
timeout
number
Timeout in milliseconds before the sandbox auto-terminates.
​
timeoutMs
number
Alias for timeout, kept for discoverability. When both are set, timeout takes precedence.
​
ports
number[]
Array of port numbers to expose from the sandbox (up to 4).
​
source
object
The source of the sandbox — a git repo, tarball, or snapshot. Omit to start an empty sandbox (Sandcastle syncs your code in separately).
// Git source
source: { type: "git", url: "https://github.com/org/repo", depth: 1 }

// Tarball source
source: { type: "tarball", url: "https://example.com/archive.tar.gz" }

// Snapshot source
source: { type: "snapshot", snapshotId: "snap_abc123" }
​
networkPolicy
Record<string, unknown>
Network policy for the sandbox. Defaults to full internet access if not specified.
​
projectId
string
Vercel project ID to associate sandbox operations with.
​
teamId
string
Vercel team ID to associate sandbox operations with.
​
env
Record<string, string>
Environment variables to inject into the sandbox at launch time. Merged with env from the agent provider and the run-level env option.

​
Complete example

import { run, claudeCode } from "@ai-hero/sandcastle";
import { vercel } from "@ai-hero/sandcastle/sandboxes/vercel";

await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: vercel({
    token: process.env.VERCEL_TOKEN,
    runtime: "node24",
    resources: { vcpus: 2 },
    // Auto-terminate the sandbox after 5 minutes
    timeout: 300_000,
    env: { MY_API_KEY: process.env.MY_API_KEY! },
  }),
  // Isolated providers default to merge-to-head
  branchStrategy: { type: "branch", branch: "agent/fix-42" },
  promptFile: ".sandcastle/prompt.md",
  hooks: {
    sandbox: {
      onSandboxReady: [{ command: "npm install" }],
    },
  },
});
The @vercel/sandbox package is loaded dynamically at runtime. If it is not installed, the Vercel provider will throw when you call run(). Install it as a dev dependency before using this provider.

Build docs developers (and LLMs) love

Get started for freeTalk to us