Sandbox Adapters

Use adapters when your agent runtime needs filesystem semantics in a sandbox. Keep your provider-native orchestration and replace custom bootstrapping with a hydrate call from Shelv. For short jobs, hydrate and run. For repeated jobs, hydrate once and snapshot the runtime.

Install adapter package

pnpm add @shelv/adapters

bun add @shelv/adapters

npm install @shelv/adapters

Runtime support:

Official runtime support: Node.js 18+ (ESM)
Bun is supported as a package manager for install
Bun runtime execution is best-effort in v1 and not part of the official runtime guarantee

Licensing:

@shelv/adapters is distributed under the Apache-2.0 license.
Source code: github.com/shelv-dev/shelv-adapters

Hydrate and snapshot

Set your API key as an environment variable (SHELV_API_KEY), then hydrate a sandbox and snapshot it:

import { createShelvClient, createVercelAdapter } from "@shelv/adapters";

const client = createShelvClient({
  apiKey: process.env.SHELV_API_KEY!,
});

const adapter = createVercelAdapter();
await adapter.hydrate({
  client,
  sandbox,
  shelfPublicId,
  mode: "archive-first",
});

const snapshot = await adapter.snapshot({
  sandbox,
  name: `shelf-${shelfPublicId}`,
});

Default mode is archive-first with automatic fallback to tree when archive retrieval fails. Use tree-only for small shelves and archive-only for strictly snapshot-based workflows. createShelvClient uses https://api.shelv.dev by default. Pass apiBaseUrl only when targeting a non-production Shelv API. Checksum verification is built in for archive mode. If checksum or archive parsing fails, archive-first falls back to tree retrieval so your run can continue without custom recovery code.

Provider coverage

Adapter	`hydrate()`	`snapshot()`
`createVercelAdapter()`	Yes	Yes
`createDaytonaAdapter()`	Yes	Yes
`createE2BAdapter()`	Yes	Yes
`createCodeSandboxAdapter()`	Yes	No
`createDenoAdapter()`	Yes	No
`createJustBashAdapter()`	Yes	No

CodeSandbox, Deno, and Just-Bash adapters are hydrate-only — CodeSandbox uses git-backed persistence, Deno sandboxes are ephemeral, and Just-Bash runs in-memory, so none expose a snapshot() method.

Just-Bash integration

Just-Bash is a sandboxed TypeScript bash interpreter with an in-memory virtual filesystem, designed for AI agents. Shelv provides three levels of integration depending on your use case.

Adapter

Use the standard adapter when you already have a Just-Bash Sandbox instance:

import { createShelvClient, createJustBashAdapter } from "@shelv/adapters";
import { Bash } from "just-bash";

const client = createShelvClient({
  apiKey: process.env.SHELV_API_KEY!,
});

const sandbox = new Bash();
const adapter = createJustBashAdapter();

await adapter.hydrate({
  client,
  sandbox,
  shelfPublicId,
  mode: "tree-only",
});

// sandbox now has all shelf files — run commands against it

Bash factory with lazy loading

Use createShelvBash when you want to pass files directly to the Bash constructor. This avoids creating a sandbox first and hydrating it separately. Eager mode (default) fetches all file content upfront:

import { createShelvClient } from "@shelv/adapters";
import { createShelvBash } from "@shelv/adapters";
import { Bash } from "just-bash";

const client = createShelvClient({
  apiKey: process.env.SHELV_API_KEY!,
});

const result = await createShelvBash({
  client,
  shelfPublicId,
  mode: "tree-only",
});

const sandbox = new Bash({ files: result.files });

Lazy mode fetches only file paths upfront and loads content on first read. For a 200-file shelf where the agent reads 10, this means 1 listing call + 10 file calls instead of downloading all 200 files:

const result = await createShelvBash({
  client,
  shelfPublicId,
  lazy: true,
});

// files are () => Promise<string> — Just-Bash evaluates on first read
const sandbox = new Bash({ files: result.files });

bash-tool helper

Use createShelvBashTool for the quickest integration with the AI SDK. It creates a bash-tool instance pre-loaded with shelf files:

import { createShelvClient, createShelvBashTool } from "@shelv/adapters";

const client = createShelvClient({
  apiKey: process.env.SHELV_API_KEY!,
});

const { tools, sandbox } = await createShelvBashTool({
  client,
  shelfPublicId,
  mode: "tree-only",
});

// Pass tools to your AI SDK generateText / streamText call

Requires bash-tool as a peer dependency:

pnpm add bash-tool

Getting Started

Concepts

Agent Integrations

Guides

Sandbox Adapters

Install adapter package

Hydrate and snapshot

Provider coverage

Just-Bash integration

Adapter

Bash factory with lazy loading

bash-tool helper

​Install adapter package

​Hydrate and snapshot

​Provider coverage

​Just-Bash integration

​Adapter

​Bash factory with lazy loading

​bash-tool helper

Install adapter package

Hydrate and snapshot

Provider coverage

Just-Bash integration

Adapter

Bash factory with lazy loading

bash-tool helper