AI Integration

Overview

buntime.sh is designed for AI agents to write and execute code autonomously. This guide shows how to integrate buntime.sh with popular AI platforms including Claude, GPT, and custom agents via MCP (Model Context Protocol) or function calling.

Why AI Agents Need buntime.sh

AI agents can write code, but they can’t test it themselves. With buntime.sh, your AI can:

✅ Execute code and see real results
✅ Iterate on bugs with actual error messages
✅ Build multi-file projects that persist across messages
✅ Run web servers and preview them
✅ Work with databases without external setup

Claude Integration

Using MCP (Model Context Protocol)

Claude Desktop and other MCP-compatible clients can use buntime.sh as a tool:

mcp-config.json

{
  "mcpServers": {
    "buntime": {
      "command": "npx",
      "args": ["-y", "@buntimesh/mcp-server"],
      "env": {
        "BUNTIME_API_KEY": "your_api_key_here"
      }
    }
  }
}

Install the MCP server:

npm install -g @buntimesh/mcp-server

Now Claude can execute code directly:

User: "Can you calculate the fibonacci sequence up to n=10?"

Claude: "I'll write and execute code to calculate that."
[Uses buntime tool to execute code]

Claude: "Here are the results: [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]"

Using Function Calling

Provide buntime.sh as a function in your Claude API calls:

import Anthropic from '@anthropic-ai/sdk';
import { Buntime } from 'buntime.sh';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });

// Create a session for this conversation
const session = await buntime.sessions.create();

const tools = [
  {
    name: "execute_code",
    description: "Execute JavaScript/TypeScript code in a persistent Bun runtime. Files and processes persist across calls. Use this to test code, process data, or run calculations.",
    input_schema: {
      type: "object",
      properties: {
        code: {
          type: "string",
          description: "The JavaScript/TypeScript code to execute"
        },
        files: {
          type: "array",
          description: "Optional files to write before execution",
          items: {
            type: "object",
            properties: {
              path: { type: "string" },
              content: { type: "string" }
            }
          }
        }
      },
      required: ["code"]
    }
  }
];

async function handleToolCall(toolName: string, toolInput: any) {
  if (toolName === "execute_code") {
    const result = await buntime.execute({
      sessionId: session.id,
      code: toolInput.code,
      files: toolInput.files
    });
    
    return {
      stdout: result.stdout,
      stderr: result.stderr,
      exitCode: result.exitCode
    };
  }
}

// Main conversation loop
const messages = [
  { role: "user", content: "Calculate the sum of numbers from 1 to 100" }
];

while (true) {
  const response = await anthropic.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    tools: tools,
    messages: messages
  });

  if (response.stop_reason === "tool_use") {
    for (const block of response.content) {
      if (block.type === "tool_use") {
        const result = await handleToolCall(block.name, block.input);
        
        messages.push({
          role: "assistant",
          content: response.content
        });
        
        messages.push({
          role: "user",
          content: [
            {
              type: "tool_result",
              tool_use_id: block.id,
              content: JSON.stringify(result)
            }
          ]
        });
      }
    }
  } else {
    console.log("Claude's response:", response.content);
    break;
  }
}

OpenAI GPT Integration

Using Function Calling

import OpenAI from 'openai';
import { Buntime } from 'buntime.sh';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });

const session = await buntime.sessions.create();

const tools = [
  {
    type: "function",
    function: {
      name: "execute_code",
      description: "Execute JavaScript/TypeScript code in a persistent runtime",
      parameters: {
        type: "object",
        properties: {
          code: {
            type: "string",
            description: "The code to execute"
          },
          files: {
            type: "array",
            description: "Optional files to create",
            items: {
              type: "object",
              properties: {
                path: { type: "string" },
                content: { type: "string" }
              }
            }
          }
        },
        required: ["code"]
      }
    }
  }
];

const messages = [
  { role: "user", content: "Create a function that reverses a string and test it" }
];

const response = await openai.chat.completions.create({
  model: "gpt-4-turbo-preview",
  messages: messages,
  tools: tools,
  tool_choice: "auto"
});

const toolCall = response.choices[0].message.tool_calls?.[0];

if (toolCall?.function.name === "execute_code") {
  const args = JSON.parse(toolCall.function.arguments);
  
  const result = await buntime.execute({
    sessionId: session.id,
    code: args.code,
    files: args.files
  });
  
  messages.push(response.choices[0].message);
  messages.push({
    role: "tool",
    tool_call_id: toolCall.id,
    content: JSON.stringify({
      stdout: result.stdout,
      stderr: result.stderr,
      exitCode: result.exitCode
    })
  });
  
  const finalResponse = await openai.chat.completions.create({
    model: "gpt-4-turbo-preview",
    messages: messages
  });
  
  console.log(finalResponse.choices[0].message.content);
}

Custom Agent Integration

LangChain

import { Tool } from "@langchain/core/tools";
import { Buntime } from 'buntime.sh';

class BuntimeTool extends Tool {
  name = "buntime_execute";
  description = "Execute JavaScript/TypeScript code in a sandboxed environment. Use this to test code, run calculations, or process data.";
  
  private client: Buntime;
  private sessionId: string;
  
  constructor(apiKey: string) {
    super();
    this.client = new Buntime({ apiKey });
  }
  
  async _call(input: string): Promise<string> {
    // Create session if not exists
    if (!this.sessionId) {
      const session = await this.client.sessions.create();
      this.sessionId = session.id;
    }
    
    try {
      const result = await this.client.execute({
        sessionId: this.sessionId,
        code: input
      });
      
      if (result.exitCode === 0) {
        return `Success!\nOutput: ${result.stdout}`;
      } else {
        return `Error (exit code ${result.exitCode}):\n${result.stderr}`;
      }
    } catch (error) {
      return `Execution failed: ${error.message}`;
    }
  }
}

// Use in LangChain agent
import { initializeAgentExecutorWithOptions } from "langchain/agents";
import { ChatOpenAI } from "@langchain/openai";

const tools = [new BuntimeTool(process.env.BUNTIME_API_KEY!)];
const model = new ChatOpenAI({ temperature: 0 });

const executor = await initializeAgentExecutorWithOptions(tools, model, {
  agentType: "openai-functions",
});

const result = await executor.invoke({
  input: "Calculate the factorial of 10"
});

console.log(result.output);

Vercel AI SDK

import { streamText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { Buntime } from 'buntime.sh';
import { z } from 'zod';

const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });
const session = await buntime.sessions.create();

const result = await streamText({
  model: openai('gpt-4-turbo'),
  messages: [
    { role: 'user', content: 'Calculate fibonacci sequence up to n=10' }
  ],
  tools: {
    executeCode: tool({
      description: 'Execute JavaScript/TypeScript code',
      parameters: z.object({
        code: z.string().describe('The code to execute'),
      }),
      execute: async ({ code }) => {
        const result = await buntime.execute({
          sessionId: session.id,
          code: code
        });
        
        return {
          stdout: result.stdout,
          stderr: result.stderr,
          exitCode: result.exitCode
        };
      },
    }),
  },
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Session Management Strategies

One Session Per Conversation

Best for AI assistants where context persists across messages:

class ConversationHandler {
  private buntime: Buntime;
  private sessions: Map<string, string> = new Map();
  
  constructor(apiKey: string) {
    this.buntime = new Buntime({ apiKey });
  }
  
  async getSession(conversationId: string): Promise<string> {
    if (!this.sessions.has(conversationId)) {
      const session = await this.buntime.sessions.create({
        ttl: 3600, // 1 hour
        metadata: { conversationId }
      });
      this.sessions.set(conversationId, session.id);
    }
    return this.sessions.get(conversationId)!;
  }
  
  async executeInConversation(conversationId: string, code: string) {
    const sessionId = await this.getSession(conversationId);
    return await this.buntime.execute({ sessionId, code });
  }
  
  async endConversation(conversationId: string) {
    const sessionId = this.sessions.get(conversationId);
    if (sessionId) {
      await this.buntime.sessions.delete({ sessionId });
      this.sessions.delete(conversationId);
    }
  }
}

One Session Per Task

Best for independent tasks without shared context:

async function executeTask(task: string) {
  const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });
  
  // Create fresh session
  const session = await buntime.sessions.create({ ttl: 600 }); // 10 minutes
  
  try {
    // AI generates code based on task
    const code = await generateCodeWithAI(task);
    
    // Execute code
    const result = await buntime.execute({
      sessionId: session.id,
      code: code
    });
    
    return result;
  } finally {
    // Clean up
    await buntime.sessions.delete({ sessionId: session.id });
  }
}

Error Handling for AI

Help your AI understand and fix errors:

async function executeWithRetry(
  buntime: Buntime,
  sessionId: string,
  code: string,
  maxRetries = 3
) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const result = await buntime.execute({ sessionId, code });
    
    if (result.exitCode === 0) {
      return {
        success: true,
        output: result.stdout,
        attempts: attempt
      };
    }
    
    if (attempt < maxRetries) {
      // Ask AI to fix the error
      const fixedCode = await askAIToFix(code, result.stderr);
      code = fixedCode;
    } else {
      return {
        success: false,
        error: result.stderr,
        attempts: attempt
      };
    }
  }
}

Prompt Engineering Tips

System Prompt Template

const SYSTEM_PROMPT = `
You are an AI assistant with the ability to execute code using buntime.sh.

When you need to test code, perform calculations, or verify logic:
1. Write clear, well-commented code
2. Use console.log() to output results
3. Handle errors gracefully
4. Test your code before declaring it works

Your code execution environment:
- Runtime: Bun 1.3 (Node.js compatible)
- Supports: TypeScript, JSX, npm packages (auto-installed)
- Persistent: Files and processes persist across executions in the same conversation
- Timeout: 30 seconds (default)

When sharing results:
- Always check the exit code (0 = success)
- Parse stdout for expected output
- Read stderr for error messages
- Iterate if tests fail

Example workflow:
User: "Sort this array: [3, 1, 4, 1, 5]"
You: Let me write and test the code.
[Execute: const arr = [3, 1, 4, 1, 5]; console.log(arr.sort((a,b) => a-b))]
[See output: [1, 1, 3, 4, 5]]
You: The sorted array is [1, 1, 3, 4, 5]
`;

Encourage Good Practices

const CODE_EXECUTION_GUIDELINES = `
When using the code execution tool:

DO:
- Write self-contained, testable code
- Use descriptive variable names
- Add error handling for edge cases
- Log intermediate steps for debugging
- Verify output matches expectations

DON'T:
- Assume code works without testing
- Ignore stderr output
- Write code without console.log for verification
- Create infinite loops or long-running processes
- Hardcode sensitive data (use environment variables)

If code fails:
1. Read the error message carefully
2. Identify the root cause
3. Fix the specific issue
4. Test the fix
5. Only then confirm it works
`;

Real-World Example: Data Analysis Agent

import { Buntime } from 'buntime.sh';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });

async function analyzeData(csvData: string, question: string) {
  // Create session
  const session = await buntime.sessions.create();
  
  // Upload CSV data
  await buntime.files.write({
    sessionId: session.id,
    path: 'data.csv',
    content: csvData
  });
  
  // Ask Claude to analyze
  const response = await anthropic.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 2048,
    tools: [
      {
        name: "execute_analysis",
        description: "Execute data analysis code",
        input_schema: {
          type: "object",
          properties: {
            code: { type: "string" }
          },
          required: ["code"]
        }
      }
    ],
    messages: [
      {
        role: "user",
        content: `I have uploaded a CSV file at data.csv. ${question}\n\nWrite code to analyze it.`
      }
    ]
  });
  
  // Execute Claude's code
  for (const block of response.content) {
    if (block.type === "tool_use" && block.name === "execute_analysis") {
      const result = await buntime.execute({
        sessionId: session.id,
        code: block.input.code
      });
      
      console.log("Analysis results:", result.stdout);
      
      // Clean up
      await buntime.sessions.delete({ sessionId: session.id });
      
      return result.stdout;
    }
  }
}

// Usage
const csvData = `name,age,city
Alice,30,NYC
Bob,25,LA
Charlie,35,Chicago`;

await analyzeData(csvData, "What is the average age?");

Security Considerations

Important security notes:

Never pass untrusted user code directly to buntime.sh
Validate and sanitize AI-generated code
Set appropriate timeouts to prevent abuse
Monitor resource usage for anomalies
Use separate API keys for production and development
Review execution logs regularly

// Example: Sandboxing AI-generated code
function validateCode(code: string): boolean {
  // Check for dangerous patterns
  const dangerousPatterns = [
    /require\s*\(\s*['"]child_process['"]\s*\)/,
    /import.*from\s*['"]child_process['"]/,
    /process\.exit/,
    /while\s*\(\s*true\s*\)/,
  ];
  
  for (const pattern of dangerousPatterns) {
    if (pattern.test(code)) {
      console.warn('Potentially dangerous code detected');
      return false;
    }
  }
  
  return true;
}

async function safeExecute(sessionId: string, code: string) {
  if (!validateCode(code)) {
    throw new Error('Code validation failed');
  }
  
  return await buntime.execute({
    sessionId,
    code,
    timeout: 10 // Short timeout for safety
  });
}

Best Practices

Reuse sessions in conversations

Create one session per conversation to maintain context and file state across multiple code executions.

Set appropriate timeouts

Use shorter timeouts (10-30s) for quick tasks to prevent runaway code from consuming resources.

Parse execution results

Check exitCode, stdout, and stderr to help the AI understand what happened and iterate if needed.

Validate AI-generated code

Review code for dangerous patterns before execution, especially in production environments.

Clean up sessions

Delete sessions when conversations end to free resources and minimize costs.

Examples & Resources

Claude MCP Server

Official MCP server for Claude integration

GPT Function Example

Complete GPT function calling example

LangChain Tool

LangChain integration example

Agent Templates

Pre-built agent templates

Next Steps

Multi-file Projects

Build complex applications with AI

Web Apps

Create web servers with preview URLs

SDK Reference

Explore the TypeScript SDK

API Reference

View complete API documentation

Getting Started

Guides

Concepts

Overview

Why AI Agents Need buntime.sh

Claude Integration

Using MCP (Model Context Protocol)

Using Function Calling

OpenAI GPT Integration

Using Function Calling

Custom Agent Integration

LangChain

Vercel AI SDK

Session Management Strategies

One Session Per Conversation

One Session Per Task

Error Handling for AI

Prompt Engineering Tips

System Prompt Template

Encourage Good Practices

Real-World Example: Data Analysis Agent

Security Considerations

Best Practices

Examples & Resources

Claude MCP Server

GPT Function Example

LangChain Tool

Agent Templates

Next Steps

Multi-file Projects

Web Apps

SDK Reference

API Reference

Getting Started

Guides

Concepts

Documentation Index

​Overview

​Why AI Agents Need buntime.sh

​Claude Integration

​Using MCP (Model Context Protocol)

​Using Function Calling

​OpenAI GPT Integration

​Using Function Calling

​Custom Agent Integration

​LangChain

​Vercel AI SDK

​Session Management Strategies

​One Session Per Conversation

​One Session Per Task

​Error Handling for AI

​Prompt Engineering Tips

​System Prompt Template

​Encourage Good Practices

​Real-World Example: Data Analysis Agent

​Security Considerations

​Best Practices

​Examples & Resources

Claude MCP Server

GPT Function Example

LangChain Tool

Agent Templates

​Next Steps

Multi-file Projects

Web Apps

SDK Reference

API Reference

Overview

Why AI Agents Need buntime.sh

Claude Integration

Using MCP (Model Context Protocol)

Using Function Calling

OpenAI GPT Integration

Using Function Calling

Custom Agent Integration

LangChain

Vercel AI SDK

Session Management Strategies

One Session Per Conversation

One Session Per Task

Error Handling for AI

Prompt Engineering Tips

System Prompt Template

Encourage Good Practices

Real-World Example: Data Analysis Agent

Security Considerations

Best Practices

Examples & Resources

Next Steps