Skip to main content

​
Vercel Sandbox Provider

@smthrs/vercel is a first-class Smithers SandboxProvider backed by the Vercel Sandbox SDK: it ships a <Sandbox> child workflow’s request JSON into the sandbox workdir, runs the entry command, and reads the result JSON back. The shared provider-kit owns request shipping, egress, result parsing, secret scrubbing, and cleanup; this package supplies only the Vercel createSession seam. The provider id is vercel-sandbox (VERCEL_SANDBOX_PROVIDER_ID); default workdir /vercel/sandbox.

​
Credentials

@vercel/sandbox is an optional dependency, lazily imported inside the session. Install it to use the real provider:
OIDC is preferred, the access-token trio a fallback. Auth resolves and validates before the SDK is touched, so a misconfigured provider fails fast with INVALID_INPUT. These values create the sandbox only, never written into the request JSON or forwarded into the remote command env.
  • VERCEL_OIDC_TOKEN, or
  • VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID.
Each can also be passed as a factory option (oidcToken, token, teamId, projectId).

​
Usage

Or register it once and reference it by id:

​
Request/result contract

The kit writes the request JSON to .smithers/sandbox-request.json in the workdir and hands the entry command two env vars:
  • SMITHERS_SANDBOX_REQUEST_PATH: where to read the request JSON.
  • SMITHERS_SANDBOX_RESULT_PATH: where to write the result JSON.
The entry command prints the result JSON to stdout or writes it to SMITHERS_SANDBOX_RESULT_PATH: either { bundlePath } or a structured { status, output|outputs, patches?, diffBundle?, runId? }. Declared ports surface their reachable sandbox.domain(port) through a heartbeat.

​
Factory options

  • runtime: Vercel Sandbox runtime (default node24).
  • vcpus: vCPU count passed to resources.
  • ports: ports whose domains are surfaced.
  • timeoutMs / maxDurationMs: see duration cap below.
  • persist: stop() (pause) instead of delete() on teardown.
  • command: entry command.
  • workdir: default /vercel/sandbox.
  • cleanup: "destroy" (default) or "keep".
  • env: merged into the command env.
  • client / createOptions: inject the SDK class or extra Sandbox.create options.

​
Duration and plan cap

Default session timeout: 5 minutes; options.timeoutMs (or request.toolTimeoutMs) maps to the create timeout. Durations above 5 minutes warn through a heartbeat and call sandbox.extendTimeout(), up to options.maxDurationMs (default 45 minutes); above that cap, a request throws INVALID_INPUT instead of overrunning the plan. Raise maxDurationMs for Pro (up to 5 hours).

​
Cleanup and cost

Ephemeral sandboxes delete permanently on teardown (cleanup: "destroy", the default); persist: true calls stop() (pause) instead so it can resume, and cleanup: "keep" skips teardown entirely. You pay Vercel Sandbox wall-clock from create to teardown. createMockVercelSandboxEnvironment(handler, config?) is an in-memory SDK double for tests. Pass it as options.client; it needs zero credentials, so unit tests run in CI without touching Vercel.