Solaflare Agent SDK

Fast and simple SDK for spinning up AI agents inside sandboxed environments

Solaflare Agent provides an easy way to create and manage AI agents running in isolated sandbox environments. Built on top of E2B, it offers a clean, type-safe API for deploying agents with custom capabilities, MCP server integrations, and full file system access.

✨ Features

• 🚀 Fast Setup - Spin up sandboxed agents in seconds
• 🔒 Secure Isolation - Agents run in isolated E2B sandboxes
• 🔌 MCP Integration - Connect Model Context Protocol servers (stdio, SSE, HTTP, OAuth)
• 🤖 Multi-Provider - Support for Anthropic, OpenAI, and Gemini
• 📁 File Operations - Upload, read, write, list, and download files
• 🌊 Streaming - Real-time streaming of agent responses
• 💾 Session Persistence - Reconnect to existing sandbox sessions
• 🏗️ Extensible - Abstraction layer supports future sandbox providers

📦 Installation

npm install solaflare-agent
# or
pnpm add solaflare-agent
# or
yarn add solaflare-agent

🚀 Quick Start

import { Agent } from "solaflare-agent";

// Create an agent with a sandbox template
const agent = new Agent({
  name: "open-code", // Sandbox template name
  capabilities: {
    rules: "You are a helpful coding assistant",
  },
});

// Stream responses from the agent
const stream = agent.stream({
  prompt: "Write a hello world function in TypeScript",
});

for await (const chunk of stream) {
  console.log(chunk.response);
}

// Clean up
await agent.kill();

💡 Usage Examples

Basic Agent with Custom Rules

import { Agent } from "solaflare-agent";

const agent = new Agent({
  name: "open-code",
  capabilities: {
    rules: `
You are a Python expert. Follow these rules:
- Always use type hints
- Prefer f-strings for formatting
- Write docstrings for all functions
    `.trim(),
  },
});

const stream = agent.stream({
  prompt: "Create a function to calculate fibonacci numbers",
});

for await (const chunk of stream) {
  process.stdout.write(chunk.response);
}

await agent.kill();

Agent with MCP and File Operations

import { Agent } from "solaflare-agent";
import { readFile } from "fs/promises";

const agent = new Agent({
  name: "open-code", // it could be open-code:small or open-code:large
  capabilities: {
    mcps: [
      {
        type: "http",
        name: "GitHub API",
        url: "https://api.githubcopilot.com/mcp/",
        headers: {
          Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
        },
      },
    ],
    rules: await readFile("./agent-rules.md").toString(),
  },
});

// Upload project files
await agent.uploadFiles([
  {
    path: "/workspace/package.json",
    file: await readFile("./package.json"),
  },
  {
    path: "/workspace/src/index.ts",
    file: await readFile("./src/index.ts"),
  },
]);

// Get the sandbox URL
const url = await agent.getUrl(4096);
console.log(`Sandbox running at: ${url}`);

// Work with the agent
const stream = agent.stream({
  prompt: "Analyze the project structure and suggest improvements",
});

for await (const chunk of stream) {
  console.log(chunk.response);
}

// List generated files
const files = await agent.listDir("/workspace");
console.log("Generated files:", files);

// Read a specific output
const report = await agent.readFile("/workspace/analysis.md");
console.log(report);

await agent.kill();

Session Persistence

import { Agent } from "solaflare-agent";

// Create a new agent
const agent1 = new Agent({
  name: "open-code",
});

await agent1.init();
console.log("Agent ID:", agent1.agentId); // Save this ID

// Do some work...
const stream = agent1.stream({ prompt: "Create a file called data.txt" });
for await (const chunk of stream) {
  console.log(chunk.response);
}

// Later, reconnect to the same sandbox
const agent2 = new Agent({
  name: "open-code",
  agentId: agent1.agentId, // Use the saved ID
});

// Continue from where you left off
const files = await agent2.listDir("/workspace");
console.log("Files from previous session:", files);

await agent2.kill();

Custom Sandbox Settings

import { Agent } from "solaflare-agent";

const agent = new Agent({
  name: "open-code",
  sandboxSettings: {
    timeout: 300000, // 5 minutes
    apiKey: process.env.E2B_API_KEY,
    baseUrl: "https://api.e2b.dev", // for self hosted e2b
  },
  providers: {
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
    OPENAI_API_KEY: process.env.OPENAI_API_KEY!,
    GEMINI_API_KEY: process.env.GEMINI_API_KEY!,
  },
});

🔌 MCP Server Integration

Solaflare Agent supports Model Context Protocol (MCP) servers, allowing agents to access external tools and data sources.

MCP Server Types

Stdio Server

const agent = new Agent({
  name: "open-code",
  capabilities: {
    mcps: [
      {
        type: "stdio",
        name: "File System",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        env: {
          NODE_ENV: "production",
        },
      },
    ],
  },
});

HTTP Server

const agent = new Agent({
  name: "open-code",
  capabilities: {
    mcps: [
      {
        type: "http",
        name: "GitHub MCP",
        url: "https://api.githubcopilot.com/mcp/",
        headers: {
          Authorization: `Bearer ${GITHUB_TOKEN}`,
        },
      },
    ],
  },
});

SSE Server

const agent = new Agent({
  name: "open-code",
  capabilities: {
    mcps: [
      {
        type: "sse",
        name: "Event Stream",
        url: "https://api.example.com/sse",
        headers: {
          "X-API-Key": API_KEY,
        },
      },
    ],
  },
});

OAuth Server

const agent = new Agent({
  name: "open-code",
  capabilities: {
    mcps: [
      {
        type: "oauth",
        name: "OAuth Service",
        url: "https://api.example.com",
        oauth: {
          clientId: "your-client-id",
          clientSecret: "your-client-secret",
          tokenUrl: "https://auth.example.com/token",
          scopes: ["read", "write"],
        },
      },
    ],
  },
});

📚 API Reference

Agent Constructor

new Agent(attributes: AgentAttributes)

AgentAttributes

| Property | Type | Description | Required | |----------|------|-------------|----------| | name | string | Sandbox template name (e.g., "open-code", "open-code:large") | ✅ | | agentId | string | Existing sandbox ID to reconnect to | ❌ | | capabilities | Capabilities | Agent capabilities and rules | ❌ | | sandboxSettings | SandboxSettings | Sandbox configuration | ❌ | | sandboxProvider | SandboxProvider | Sandbox provider type (default: "e2b") | ❌ | | providers | Providers | API keys for AI providers | ❌ |

Capabilities

interface Capabilities {
  mcps?: McpServer[];  // MCP server configurations
  rules?: string;      // Custom rules/instructions for the agent
}

Providers

interface Providers {
  ANTHROPIC_API_KEY: string;
  OPENAI_API_KEY: string;
  GEMINI_API_KEY: string;
}

Note: At least one provider API key must be set (either via providers parameter or environment variables).

Agent Methods

stream(props: ExecuteProps): AsyncGenerator<Response>

Stream responses from the agent.

const stream = agent.stream({
  prompt: "Your prompt here",
});

for await (const chunk of stream) {
  console.log(chunk.response);
}

init(): Promise<void>

Manually initialize the sandbox (optional - automatically called when needed).

await agent.init();

uploadFiles(files: UploadFileProps[]): Promise<void>

Upload files to the sandbox.

await agent.uploadFiles([
  {
    path: "/workspace/config.json",
    file: JSON.stringify({ key: "value" }),
  },
  {
    path: "/workspace/data.txt",
    file: Buffer.from("Hello, world!"),
  },
]);

listDir(path: string): Promise<FileEntry[]>

List files and directories in the sandbox.

const entries = await agent.listDir("/workspace");
entries.forEach(entry => {
  console.log(`${entry.name} (${entry.isDir ? "dir" : "file"})`);
});

readFile(path: string): Promise<string>

Read file content from the sandbox.

const content = await agent.readFile("/workspace/output.txt");
console.log(content);

downloadUrl(path: string): Promise<string>

Get a download URL for a file in the sandbox.

const url = await agent.downloadUrl("/workspace/report.pdf");
console.log(`Download: ${url}`);

getUrl(port: number): Promise<string>

Get the public URL for a service running inside the sandbox.

// If your agent starts a web server on port 3000
const url = await agent.getUrl(3000);
console.log(`Access your app at: ${url}`);

kill(): Promise<void>

Terminate the sandbox and clean up resources.

await agent.kill();

Properties

• agent.name - Sandbox template name
• agent.agentId - Current sandbox ID (undefined if not initialized)
• agent.isNewSandbox - Whether this is a new sandbox session
• agent.capabilities - Agent capabilities configuration
• agent.sandboxSettings - Sandbox settings
• agent.providers - AI provider configuration

🏗️ Architecture

Solaflare Agent is built with extensibility in mind:

┌─────────────────────────────────────┐
│           Agent Class               │
│  (High-level API for users)         │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│        ISandbox Interface           │
│  (Sandbox-agnostic abstraction)     │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│       SandboxFactory                │
│  (Creates sandbox instances)        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│        E2BSandbox Class             │
│  (E2B implementation)               │
└─────────────────────────────────────┘

This architecture allows future support for additional sandbox providers by implementing the ISandbox interface.

🔧 Environment Variables

The SDK uses environment variables for API keys if not provided explicitly:

# AI Provider Keys (at least one required)
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
GEMINI_API_KEY=your_gemini_key

# E2B Configuration
E2B_API_KEY=your_e2b_key

📋 Requirements

• Node.js >= 22
• E2B account and API key (Get one here)
• At least one AI provider API key (Anthropic, OpenAI, or Gemini)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

ISC

🔗 Links

• GitHub Repository
• E2B Documentation
• Model Context Protocol

Made with ❤️ by the Automate Army team