How to use with Vercel AI SDK and sandbox?

how can i use this with the vercel ai sdk and within a vercel sandbox?

use case: i'm building a "chat with a github repo" product in which posts/threads can be done to a different git ref, but will use the same sandbox (we'll clone the repo at that ref and place it in a specific worktree). then i want the agent's edits to live in a specific agentfs database. the database should be persisted to the sandbox itself (that's done automatically by vercel sandbox, or will be done soon). help me build this.

To build a "chat with a GitHub repo" product within a Vercel Sandbox using the Vercel AI SDK and AgentFS, you can leverage AgentFS Overlays. This allows you to treat a specific git worktree as a read-only base while capturing all agent edits in a persistent SQLite database.

Since a Vercel Sandbox provides a full Linux environment with a persistent filesystem, the best approach is to combine git worktree with the agentfs CLI.

###Recommended Workflow

1. Setup Worktrees: For each different git ref (post/thread), create a dedicated worktree in the sandbox.
2. Initialize AgentFS Overlay: Use agentfs init --base <worktree_path> to create a database that "layers" on top of that worktree.
3. Execute Tools via AgentFS: Use the agentfs run command as the execution environment for your AI tools (like just-bash). This ensures all file modifications are captured in the database without touching the original worktree.

###Implementation Guide

####1. Prepare the Sandbox Environment

In your Vercel Sandbox, you can programmatically set up the worktrees and the AgentFS database:

import { execSync } from 'node:child_process';

async function setupThreadEnvironment(ref: string, threadId: string) {
  const worktreePath = `./worktrees/${threadId}`;
  
  // 1. Create a git worktree for the specific ref
  execSync(`git worktree add ${worktreePath} ${ref}`);
  
  // 2. Initialize AgentFS with the worktree as the read-only base
  // This creates .agentfs/${threadId}.db
  execSync(`agentfs init --base ${worktreePath} ${threadId}`);
  
  return { worktreePath, databaseId: threadId };
}

####2. Integrate with Vercel AI SDK & just-bash

When using just-bash with the Vercel AI SDK, you want the bash commands to run inside the AgentFS sandbox. You can do this by wrapping the execution in agentfs run.

import { createBashTool } from 'just-bash/ai';
import { streamText } from 'ai';

const { worktreePath, databaseId } = await setupThreadEnvironment('main', 'thread-123');

const bashTool = createBashTool({
  // Override the default executor to use agentfs run
  // This ensures all bash commands (ls, cat, npm install, etc.) 
  // happen inside the persistent overlay.
  execute: async (command) => {
    // Run the command inside the session
    const output = execSync(
      `agentfs run --session ${databaseId} -- ${command}`, 
      { cwd: worktreePath }
    ).toString();
    return output;
  }
});

const result = streamText({
  model: myModel,
  tools: { bash: bashTool },
  messages: history,
});

###Key Advantages of this Setup

• Zero-Copy Efficiency: Using git worktree + AgentFS Overlay means you don't have to copy the entire repository for every thread. The base remains the local git checkout, and only the diffs are stored in SQLite.
• Persistent Sandbox Edits: Because you use --session ${databaseId}, the agent can run npm install, edit files, and run tests. All these changes persist in .agentfs/${threadId}.db across different LLM turns.
• Automatic Persistence: Vercel Sandbox automatically persists the .agentfs directory. When the sandbox resumes, your agent's state is exactly where it left off.
• Auditability: You can inspect the agent's edits at any time using the CLI:

  # See what the agent changed compared to the original repo
  agentfs diff thread-123
  
  # List files from the agent's perspective
  agentfs fs ls thread-123
  

###Optional: Pure Programmatic Access

If you want to read the agent's edits directly in your Node.js code (e.g., to show a diff in your UI), use the agentfs-sdk:

import { AgentFS } from 'agentfs-sdk';

const agent = await AgentFS.open({ id: 'thread-123' });

// Read a file the agent might have edited
const content = await agent.fs.readFile('/src/index.ts', 'utf-8');

// The SDK handles the database automatically
const toolCalls = await agent.tools.getRecent();

###Summary of Commands

nice! why do we need just-bash with this setup? vs creating our own bash tool?

The reason to use just-bash alongside AgentFS—rather than just wrapping execSync yourself—is that it provides filesystem virtualization and security features that are difficult to build from scratch.

While AgentFS handles the storage of the files, just-bash handles the execution environment and the bridge to the LLM. Here is why they are better together:

###1. Ready-Made AI SDK Integration

just-bash comes with createBashTool, which is already optimized for the Vercel AI SDK. It includes:

• Built-in Zod Schemas: Correct parameter definitions so the LLM knows how to call it.
• Optimized Prompting: It automatically injects "System Instructions" that teach the agent how to use common tools (ls, cat, grep) in a virtualized environment.
• Output Handling: It handles streaming large outputs and error formatting in a way that LLMs understand.

###2. State-Aware Path Normalization

If you use a custom tool with execSync, you have to manually handle cd commands. If the agent runs cd src, your next execSync call will still be in the root directory unless you manually track and prepend the path.

just-bash maintains a persistent virtual state (like the Current Working Directory) across multiple tool calls. When the agent runs:

1. bash: { command: "cd src" }
2. bash: { command: "ls" }

just-bash ensures the ls happens inside src, even if your Node.js process stays in the root.

###3. Combining "Real" and "Virtual" Files

This is the "killer feature" for your use case. just-bash allows you to mount different things into the same view:

• The Repo (Real): Mounted as the base via AgentFS.
• AgentFS (Overlay): Where edits go.
• In-Memory files: You can inject ephemeral files (like a .env or a temporary script) into the bash environment without ever writing them to the sandbox disk.

###4. Integration with agentfs-sdk/just-bash

The SDK provides a specific adapter that makes AgentFS "look like" a standard filesystem to just-bash.

Instead of shelling out to agentfs run, you can use the SDK's internal implementation for much lower latency and better control:

import { agentfs } from "agentfs-sdk/just-bash";
import { createBashTool } from "just-bash/ai";

// 1. Create a just-bash compatible FS handle
// This uses the SDK's logic to handle reads/writes to the SQLite DB
const fs = await agentfs({ id: "my-thread-db" });

// 2. Pass it directly to the tool
const bashTool = createBashTool({ 
  fs,
  // just-bash handles the execution logic, AgentFS handles the persistence
});

###When should you build your own?

You should build your own tool only if you need to execute commands that just-bash cannot handle internally (like launching a long-running web server or a Docker container) and you don't want to use the agentfs run CLI wrapper.

For a "Chat with Repo" product where the agent is mostly reading code, running grep, and making edits, the just-bash + agentfs combo is significantly more robust.

i'm confused: so the overaly aspect is not an agentfs feature? like if i run agentfs run --session <> -- rm -rf: what will happen? and i mean without just-bash.

The overlay is definitely an AgentFS feature—it is one of its most powerful capabilities.

To clear up the confusion: AgentFS provides the overlay logic; just-bash provides the AI tool interface.

###What happens when you run agentfs run --session t1 -- rm -rf .?

If you run that command without just-bash:

1. FUSE/NFS Mount: AgentFS creates a sandbox and mounts a virtual filesystem over your current directory. This virtual filesystem is a "stack":
   • Top (Writable): Your AgentFS SQLite database (t1.db).
   • Bottom (Read-Only): Your actual GitHub repo worktree.
2. The Deletion: When rm -rf runs, the Linux kernel sends "unlink" requests to AgentFS.
3. Whiteouts: AgentFS does not delete the files from your repo. Instead, it writes "whiteout" markers into the SQLite database.
4. The Result:
   • Inside the sandbox: The directory looks empty. The files are "gone."
   • Outside the sandbox (the host): Your repo is completely untouched. All the original files are still there.
   • Persistence: Because you used --session t1, if you run agentfs run --session t1 -- ls later, the directory will still look empty, because the "deletions" are saved in the database.

###So why the confusion?

There are actually two ways to use the AgentFS overlay, and this is usually where the confusion starts:

####1. The "Sandbox" way (CLI)

You use the agentfs run command. This uses kernel-level tricks (FUSE on Linux, NFS on macOS) to make the entire operating system see the overlay. Any program (bash, python, ls, rm) works perfectly because the OS handles the translation.

• Best for: Complex tasks, running existing scripts, or when you want 100% compatibility with real bash.

####2. The "Virtual" way (SDK)

You use the agentfs-sdk inside your Node.js code. There is no "mount" on the disk. Instead, you have a JavaScript object (fs) that behaves like a filesystem. When you call fs.readFile(), the SDK logic decides whether to read from the base repo or the SQLite database.

• Best for: "Pure" Node.js agents, Cloudflare Workers (where you can't mount FUSE), and high-performance "Chat with Repo" tools.

###Where just-bash fits in

just-bash is a library designed to be a "Bash Emulator" for LLMs.

• Without just-bash: You have to write a tool that takes a string, executes it via agentfs run, and captures the output. You have to handle errors, timeouts, and state yourself.
• With just-bash: You give it an AgentFS fs object (from the SDK). just-bash then provides the "Bash Tool" to the LLM. When the LLM wants to "edit a file," just-bash calls the AgentFS SDK, which writes to the SQLite database.

###Summary: Your Use Case

Since you are in a Vercel Sandbox (which is a real Linux environment), you have the luxury of using Method 1 (The CLI). It is the most robust.

The "No-Confusion" Plan for you:

1. Git Worktree: For the repo source.
2. AgentFS CLI: To provide the Overlay and Sandbox.
3. Your own tool or just-bash: Just as a way to send strings from the LLM to the agentfs run command.

If you run agentfs run --session thread-1 -- rm -rf ., you have effectively "deleted" the repo for that specific agent session, but you can "undo" it instantly just by deleting the .db file or starting a new session. Your original worktree remains pristine.

nice. yeah aligned that just cli is the best! cool, that's clear. one other thing i'm confused about: can i run many concurrent "sessions" at the same time? which target the same worktree? will they conflict?

Yes, you can run unlimited concurrent sessions against the same worktree, and they will not conflict.

This is one of the core architectural strengths of AgentFS. Because it uses an Overlay Filesystem approach, it treats your GitHub worktree as a "Golden Image" (Read-Only) and stores all changes in a "Layer" (the SQLite database).

Here is exactly how it works when you have multiple concurrent sessions:

###1. Isolation (Different Sessions)

If you run two different agents on the same worktree using different session IDs:

• Agent A: agentfs run --session thread-A -- bash
• Agent B: agentfs run --session thread-B -- bash

What happens:

• Both agents see the exact same code from your GitHub worktree.
• If Agent A deletes README.md, it disappears only for Agent A.
• Agent B still sees README.md perfectly fine.
• No Conflicts: Their changes are written to thread-A.db and thread-B.db respectively. They never even know the other agent exists.

###2. Collaboration (Same Session)

If you want two different processes to see the same changes (e.g., one process running a test suite and another where the agent is typing), you use the same session ID:

• Terminal 1: agentfs run --session shared-thread -- npm run dev
• Terminal 2: agentfs run --session shared-thread -- bash

What happens:

• Both processes share the same delta layer.
• If the agent in Terminal 2 edits a file, the dev server in Terminal 1 will immediately see that edit and reload.
• Concurrency Control: AgentFS uses SQLite under the hood with WAL (Write-Ahead Logging) mode enabled. This means multiple processes can read and write to the filesystem database simultaneously without corrupting it.

###3. The "Base" Layer Safety

Even if you have 100 sessions running, your Git Worktree is never modified.

• AgentFS mounts the worktree using "Bind Mounts" or internal SDK logic that treats the source as read-only.
• You could even run git checkout on the worktree while agents are running (though this might confuse the agents if the files they are looking at suddenly change versions, it won't crash AgentFS).

###Summary for your "Chat with Repo" Product:

Pro Tip for Vercel Sandbox: Since you are in a Vercel Sandbox, all these .db files will live in the .agentfs/ directory. If you want to "reset" a thread, you don't need to touch the git worktree; you just delete that specific .db file. It's much faster than git reset --hard.

brilliant! really noice. ok, outline a simple plan for implementing this myself. assume the whole setup is there (except for the Bash tool (i don't wanna use just-bash btw) and the agentfs setup). in fact, see what's there https://forums.basehub.com/basehub-ai/forums/1

Based on the architecture of Forums and your specific requirements (Vercel Sandbox + AI SDK + Custom Tools), here is a simple plan to implement AgentFS as your persistent, isolated overlay layer.

###I. The Setup Logic (Sandbox Entry)

When your Workflow spawns the Vercel Sandbox, you need to prepare the environment for the specific thread.

// agent/env-setup.ts
import { execSync } from 'node:child_process';

export function setupAgentFS(ref: string, threadId: string) {
  const worktreePath = `/tmp/worktrees/${threadId}`;
  const sessionId = `thread-${threadId}`;

  // 1. Create a git worktree for this specific version of the code
  // This allows concurrent threads to target different branches/commits safely
  execSync(`git worktree add ${worktreePath} ${ref}`, { stdio: 'inherit' });

  // 2. Initialize the AgentFS Overlay
  // --base tells AgentFS to treat the worktree as the read-only source
  // The database will be created at .agentfs/thread-${threadId}.db
  execSync(`agentfs init --base ${worktreePath} ${sessionId}`, { stdio: 'inherit' });

  return { worktreePath, sessionId };
}

###II. The Custom Bash Tool

Instead of just-bash, you can build a clean tool that wraps everything in agentfs run. This is the most robust way to ensure that even if the agent tries to rm -rf /, it only affects its own SQLite-backed virtual layer.

// agent/tools/bash.ts
import { tool } from 'ai';
import { execSync } from 'node:child_process';
import { z } from 'zod';

export const createBashTool = (sessionId: string, worktreePath: string) => 
  tool({
    description: 'Execute bash commands in a persistent, sandboxed environment.',
    parameters: z.object({
      command: z.string().describe('The bash command to run.'),
    }),
    execute: async ({ command }) => {
      try {
        // We wrap the command in 'agentfs run'
        // --session ensures edits persist across multiple tool calls in this thread
        const output = execSync(
          `agentfs run --session ${sessionId} -- bash -c ${JSON.stringify(command)}`,
          { 
            cwd: worktreePath,
            env: { ...process.env, AGENTFS_ID: sessionId } 
          }
        );
        return output.toString();
      } catch (error: any) {
        return `Error: ${error.stdout?.toString() || error.message}`;
      }
    },
  });

###III. Optimized Retrieval Tools (High Performance)

For reading code (which agents do a lot), using agentfs run every time has a tiny bit of overhead because it has to set up the mount. You can use the agentfs fs CLI commands for instant read-only access to the overlay state.

// agent/tools/read.ts
export const readTool = (sessionId: string) => tool({
  description: 'Read a file from the repository (including agent edits).',
  parameters: z.object({ path: z.string() }),
  execute: async ({ path }) => {
    // This queries the SQLite DB and Base Worktree directly (no mount needed)
    return execSync(`agentfs fs cat ${sessionId} ${path}`).toString();
  }
});

export const lsTool = (sessionId: string) => tool({
  description: 'List files in a directory.',
  parameters: z.object({ path: z.string().default('/') }),
  execute: async ({ path }) => {
    return execSync(`agentfs fs ls ${sessionId} ${path}`).toString();
  }
});

###IV. Orchestration in response-agent.ts

Finally, wire it all together using the Vercel AI SDK.

// agent/response-agent.ts
import { streamText } from 'ai';
import { setupAgentFS } from './env-setup';
import { createBashTool } from './tools/bash';

export async function runAgent(ref: string, threadId: string, prompt: string) {
  const { worktreePath, sessionId } = setupAgentFS(ref, threadId);

  const result = await streamText({
    model: yourModel,
    tools: {
      bash: createBashTool(sessionId, worktreePath),
      read: readTool(sessionId),
      ls: lsTool(sessionId),
      // ... your other tools (WebSearch, ReadPost)
    },
    system: `You are a coding agent researching a GitHub repo. 
             You are working in an AgentFS overlay on top of worktree: ${worktreePath}. 
             All your file edits are persistent.`,
    messages: [{ role: 'user', content: prompt }],
  });

  return result;
}

###Why this plan works for you:

1. Worktree Isolation: By creating a git worktree per ref, you avoid "branch hopping" conflicts.
2. Zero Dirty Files: Since the worktree is the base, the agent can run npm install or go build. The hundreds of megabytes of node_modules or binaries stay in the .agentfs/*.db file, not in your git repo.
3. Persistence: If the sandbox sleeps and wakes up, the .agentfs/*.db file is still there. The user can continue the conversation and the agent will see its previous edits.
4. No just-bash: You have full control over the execSync logic and how errors are reported back to the LLM.

what about Linux OverlayFS? can i just use that if i have the sandbox to myself?

the permission is the most compelling thing IMO. agentfs run ensures all mutations go to the db, even if the agent was prompt injected and CDs into another dir

if i do agentfs run -- <complex command to go to root and rm -rf>, what protects root from not being deleted?

does bubblewrap achieve the same security guarantees?