Getting Started

Install bashkit, set up a sandbox, and run your first agentic loop.

Installation

Install bashkit along with its peer dependencies and an AI provider of your choice:

npm install bashkit ai zod @ai-sdk/anthropic

Any Vercel AI SDK provider works — @ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/google, etc.

For web search and fetch capabilities, add the optional parallel-web package:

npm install parallel-web

Basic Setup

The simplest way to get started is with LocalSandbox, which uses Bun/Node APIs directly — no network overhead, no extra dependencies.

import { createLocalSandbox, createAgentTools } from 'bashkit';

// Create a sandbox pointing at your working directory
const sandbox = createLocalSandbox({
  workingDirectory: '/path/to/project',
});

// Create the tool set
const { tools } = await createAgentTools(sandbox);

// tools now contains: Bash, Read, Write, Edit, Glob, Grep

With Configuration

You can customize tool behavior with the config object:

const { tools } = await createAgentTools(sandbox, {
  defaultTimeout: 30000,
  tools: {
    Bash: {
      timeout: 10000,
      blockedCommands: ['rm -rf /', 'dd if='],
    },
    Write: {
      maxFileSize: 1_000_000,
    },
  },
});

With Web Tools

To enable WebSearch and WebFetch, pass a webSearch config with your Parallel API key:

const { tools } = await createAgentTools(sandbox, {
  webSearch: {
    apiKey: process.env.PARALLEL_API_KEY,
  },
});

// tools now also includes: WebSearch, WebFetch

Agentic Loop

Here's a complete example using the Vercel AI SDK's generateText with bashkit tools in an agentic loop:

import { createLocalSandbox, createAgentTools } from 'bashkit';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const sandbox = createLocalSandbox({ workingDirectory: '.' });
const { tools } = await createAgentTools(sandbox);

const { text } = await generateText({
  model: anthropic('claude-sonnet-4-5'),
  tools,
  maxSteps: 50,
  system: `You are a helpful coding assistant. Use the tools
available to you to help the user with their request.
Always read files before modifying them.`,
  prompt: 'Find all TypeScript files with TODO comments and list them.',
});

console.log(text);

// Clean up when done
await sandbox.destroy();

With Budget Tracking

Track costs and stop when a budget is exceeded:

import { createLocalSandbox, createAgentTools } from 'bashkit';
import { generateText, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const sandbox = createLocalSandbox({ workingDirectory: '.' });
const { tools, budget } = await createAgentTools(sandbox, {
  modelRegistry: { provider: 'openRouter' },
  budget: { maxUsd: 2.00 },
});

const { text } = await generateText({
  model: anthropic('claude-sonnet-4-5'),
  tools,
  maxSteps: 50,
  stopWhen: [stepCountIs(50), budget.stopWhen],
  onStepFinish: (step) => {
    budget.onStepFinish(step);
    const status = budget.getStatus();
    console.log(`Cost: $${status.totalCostUsd.toFixed(4)}`);
  },
  prompt: 'Refactor the utils directory to use consistent naming.',
});

console.log(text);
await sandbox.destroy();