>_ Bashlet
TypeScript SDK

@bashlet/sdk

TypeScript SDK for bashlet - provide sandboxed bash execution as tools for AI agents.

01 Installation

Terminal
npm install @bashlet/sdk

Make sure you have bashlet installed on your system.

02 Quick Start

TypeScript
import { Bashlet } from '@bashlet/sdk';

const bashlet = new Bashlet({
  mounts: [{ hostPath: './src', guestPath: '/workspace' }],
});

// Execute a command
const result = await bashlet.exec('ls -la /workspace');
console.log(result.stdout);

03 AI Framework Support

Vercel AI SDK

Native Zod schemas for type-safe tool definitions

OpenAI Function Calling

JSON Schema format for OpenAI API

MCP (Model Context Protocol)

Full MCP server integration

Framework-Agnostic

Generic tools for custom implementations

Vercel AI SDK

TypeScript
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { Bashlet } from '@bashlet/sdk';

const bashlet = new Bashlet({
  mounts: [{ hostPath: './project', guestPath: '/workspace' }],
});

const result = await generateText({
  model: openai('gpt-4-turbo'),
  tools: bashlet.toVercelTools(),
  prompt: 'List files in /workspace and show package.json',
});

OpenAI Function Calling

TypeScript
import OpenAI from 'openai';
import { Bashlet, createOpenAIToolHandler } from '@bashlet/sdk';

const openai = new OpenAI();
const bashlet = new Bashlet();

const tools = bashlet.toOpenAITools();
const handleToolCall = createOpenAIToolHandler(bashlet);

const response = await openai.chat.completions.create({
  model: 'gpt-4-turbo',
  tools: tools.map(t => ({ type: t.type, function: t.function })),
  messages: [{ role: 'user', content: 'List files' }],
});

// Handle tool calls
for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await handleToolCall(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
}

MCP Server

TypeScript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { Bashlet, createMCPServer } from '@bashlet/sdk';

const bashlet = new Bashlet();
const { tools, handleToolCall } = createMCPServer(bashlet);

const server = new Server(
  { name: 'bashlet-mcp', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler('tools/list', async () => ({ tools }));

server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;
  return handleToolCall(name, args);
});

const transport = new StdioServerTransport();
await server.connect(transport);

04 Available Tools

Tool Description
bashlet_exec Execute shell commands in the sandbox
bashlet_read_file Read file contents from the sandbox
bashlet_write_file Write content to a file in the sandbox
bashlet_list_dir List directory contents

05 API Reference

Bashlet Class

Constructor
new Bashlet({
  binaryPath?: string,       // Path to bashlet binary
  preset?: string,           // Default preset name
  mounts?: Mount[],          // Default mounts
  envVars?: EnvVar[],        // Default environment variables
  workdir?: string,          // Default working directory
  timeout?: number,          // Timeout in seconds (default: 300)
  configPath?: string,       // Path to config file
})

Methods

Method Description
exec(command, options?) Execute a one-shot command
createSession(options?) Create a persistent session
runInSession(id, command) Run command in existing session
terminate(sessionId) Terminate a session
listSessions() List all active sessions
readFile(path) Read file from sandbox
writeFile(path, content) Write file to sandbox
listDir(path) List directory contents
toVercelTools() Generate Vercel AI SDK tools
toOpenAITools() Generate OpenAI function calling tools
toMCPTools() Generate MCP tools
toGenericTools() Generate framework-agnostic tools