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 |