Bunnyshell.SDK 0.1.0

Bunnyshell .NET SDK

Official .NET SDK for Bunnyshell - Secure, isolated cloud sandboxes for code execution, data processing, and AI agents.

What are Bunnyshell Sandboxes?

Bunnyshell Sandboxes are secure, ephemeral virtual machines that let you:

• Execute untrusted code safely (Python, JavaScript, Shell)
• Process data in isolated environments
• Build AI agents with code interpretation capabilities
• Run commands and manage files programmatically
• Automate desktop tasks with VNC, screenshots, and keyboard control

Perfect for AI applications, data pipelines, code playgrounds, and automated workflows.

Quick Start

Installation

dotnet add package Bunnyshell.SDK

Basic Usage

using Bunnyshell.SDK;

// Set your API key (get one at https://dashboard.bunnyshell.com)
var sandbox = await Sandbox.CreateAsync(
    template: "code-interpreter",
    apiKey: "your-api-key-here"
);

try
{
    // Execute Python code
    var result = await sandbox.RunCodeAsync(@"
        import numpy as np
        data = [1, 2, 3, 4, 5]
        print(f'Mean: {np.mean(data)}')
    ");
    
    Console.WriteLine(result.Stdout); // Output: Mean: 3.0
}
finally
{
    // Always clean up
    await sandbox.KillAsync();
}

Common Use Cases

1. Code Execution Engine

var sandbox = await Sandbox.CreateAsync(template: "code-interpreter");

// Run Python
var pythonResult = await sandbox.RunCodeAsync("print('Hello from Python!')");

// Run JavaScript
var jsResult = await sandbox.RunCodeAsync(
    "console.log('Hello from Node.js!')", 
    language: "javascript"
);

// Run Shell commands
var shellResult = await sandbox.Commands.RunAsync("ls -la /workspace");

2. File Operations

// Write files
await sandbox.Files.WriteAsync("/workspace/data.txt", "Hello, World!");

// Read files
string content = await sandbox.Files.ReadAsync("/workspace/data.txt");

// Upload from local
await sandbox.Files.UploadAsync("local-file.csv", "/workspace/data.csv");

// Download to local
await sandbox.Files.DownloadAsync("/workspace/results.json", "results.json");

3. Data Processing Pipeline

// Upload raw data
await sandbox.Files.WriteAsync("/workspace/input.csv", csvData);

// Process with Python
await sandbox.RunCodeAsync(@"
    import pandas as pd
    df = pd.read_csv('/workspace/input.csv')
    df['processed'] = df['value'] * 2
    df.to_csv('/workspace/output.csv', index=False)
");

// Download results
await sandbox.Files.DownloadAsync("/workspace/output.csv", "output.csv");

4. AI Agent with Code Interpreter

var sandbox = await Sandbox.CreateAsync(template: "code-interpreter");

// Agent executes code based on user query
var code = GenerateCodeFromUserQuery(userQuery); // Your AI logic
var result = await sandbox.RunCodeAsync(code);

if (result.Success)
{
    Console.WriteLine($"Result: {result.Stdout}");
    
    // Handle plots/charts
    foreach (var output in result.RichOutputs ?? [])
    {
        if (output.Format == "png")
        {
            SaveChart(output.Data); // output.Data is base64 PNG
        }
    }
}

Best Practices

1. Always Clean Up Resources

var sandbox = await Sandbox.CreateAsync(template: "code-interpreter");
try
{
    // Do work
    await sandbox.RunCodeAsync("...");
}
finally
{
    // Always cleanup, even on error
    await sandbox.KillAsync();
}

2. Handle Errors Gracefully

using Bunnyshell.SDK.Exceptions;

try
{
    var result = await sandbox.RunCodeAsync(userCode);
}
catch (CodeExecutionException ex)
{
    Console.WriteLine($"Code error: {ex.Message}");
}
catch (AuthenticationException ex)
{
    Console.WriteLine($"Invalid API key: {ex.Message}");
}
catch (RateLimitException ex)
{
    Console.WriteLine($"Rate limited: {ex.Message}");
    // Implement backoff
}

3. Use Parallel Execution for Performance

// Process multiple tasks in parallel
var tasks = userQueries.Select(query => 
    ProcessQueryAsync(query, sandbox)
);

var results = await Task.WhenAll(tasks);

4. Reuse Sandboxes

// Create once, use multiple times
var sandbox = await Sandbox.CreateAsync(template: "code-interpreter");

try
{
    // State persists between executions (IPython kernel)
    await sandbox.RunCodeAsync("x = 42");
    var result = await sandbox.RunCodeAsync("print(x * 2)");
    // Output: 84
}
finally
{
    await sandbox.KillAsync();
}

Features

Core Capabilities

• ✅ Code Execution - Python, JavaScript, Shell with stdout/stderr capture
• ✅ File Operations - Read, write, upload, download, list directories
• ✅ Command Execution - Run shell commands with full control
• ✅ Environment Variables - Get, set, delete environment configuration
• ✅ Process Management - List and kill processes
• ✅ Desktop Automation - VNC, screenshots, mouse, keyboard (with desktop templates)
• ✅ Async Support - Full async/await for all I/O operations
• ✅ Type Safety - Strong typing with IntelliSense support
• ✅ Error Handling - Typed exceptions for all error cases

Developer Experience

• 🚀 Zero Dependencies - Only requires .NET 8.0
• 📝 Full IntelliSense - Complete XML documentation
• ⚡ Fast - Lightweight 36KB package
• 🎯 Fluent API - Intuitive sandbox.Files.ReadAsync() syntax
• 🔒 Type Safe - Compile-time error checking

Configuration

API Key

Set your API key in one of three ways:

// 1. Pass directly (not recommended for production)
var sandbox = await Sandbox.CreateAsync(
    template: "code-interpreter",
    apiKey: "your-key"
);

// 2. Environment variable (recommended)
Environment.SetEnvironmentVariable("BUNNYSHELL_API_KEY", "your-key");
var sandbox = await Sandbox.CreateAsync(template: "code-interpreter");

// 3. Configuration file (recommended for apps)
var apiKey = Configuration["Bunnyshell:ApiKey"];
var sandbox = await Sandbox.CreateAsync(template: "code-interpreter", apiKey: apiKey);

Custom Resources

var sandbox = await Sandbox.CreateAsync(
    template: "code-interpreter",
    vcpu: 4,              // 4 vCPUs
    memoryMb: 4096,       // 4GB RAM
    diskGb: 20,           // 20GB disk
    timeout: 600          // 10 minute timeout
);

Templates

Available templates:

• code-interpreter - Python + scientific libraries (NumPy, Pandas, Matplotlib)
• nodejs - Node.js environment
• ubuntu-desktop - Full desktop with GUI support

Documentation

• 📖 Complete Documentation
• 🎓 Cookbook Examples
• 🌐 API Reference
• 💬 Discord Community

Examples Repository

Find complete working examples in the cookbook:

1. Basic Operations - Sandbox lifecycle and management
2. Code Execution - Python, JavaScript, Shell execution
3. File Operations - Complete file management
4. Commands - Shell command execution
5. Environment Variables - Configuration management
6. Process Management - Process control
7. Desktop Automation - GUI automation
8. WebSocket Features - Real-time monitoring
9. Advanced Use Cases - Sandbox pooling, pipelines
10. Best Practices - Production patterns

Support

• 🐛 Report Issues
• 📧 Email Support
• 💬 Discord

License

MIT License - see LICENSE file.

Get your API key: https://dashboard.bunnyshell.com
Star us on GitHub: https://github.com/bunnyshell/sdks ⭐