Solaflare Agent SDK

Solaflare Agent is a Node.js SDK for running AI agents and raw Linux commands inside sandboxed E2B environments. It wraps sandbox lifecycle, prompt execution, shell execution, file operations, MCP configuration, and session reuse behind a single Agent class.

Installation

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

Environment Requirements

• Node.js >= 22
• An accessible E2B template name such as open-code or open-code:large
• E2B credentials available to the underlying E2B client, typically through sandboxSettings.apiKey or E2B_API_KEY
• At least one AI provider API key only when using execute() or stream()

Typical host environment setup:

ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
GOOGLE_GENERATIVE_AI_API_KEY=your_google_ai_key
E2B_API_KEY=your_e2b_key

Quick Start

Prompt-based usage:

import { Agent } from "solaflare-agent";

const agent = new Agent({
  name: "open-code",
  capabilities: {
    rules: "You are a careful TypeScript assistant.",
  },
});

const output = await agent.execute({
  prompt: "Write a hello world function in TypeScript.",
});

console.log(output);
console.log("Agent ID:", agent.agentId);

await agent.kill();

Direct shell usage:

import { Agent } from "solaflare-agent";

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

const result = await agent.runCommand("pwd && ls -la", {
  timeoutMs: 30_000,
});

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);

await agent.kill();

runCommand() does not require AI provider keys. execute() and stream() do.

Documentation Map

• Technical guide for lifecycle, prompt execution, direct command execution, sessions, file operations, MCP usage, and template behavior
• API reference for every root export, public method, parameter, and return shape
• Lazy initialization notes for sandbox auto-init behavior, including shell-only initialization
• Creating custom templates for authoring init.sh and run.sh based E2B templates

Core Concepts

Template names

The name field is the E2B template identifier used when creating a new sandbox. The bundled template is open-code, and tagged variants such as open-code:large can be used when you need a different size profile.

Lazy initialization

The constructor does not create a sandbox immediately. Initialization happens when you call init() or the first method that needs a live sandbox, such as runCommand(), stream(), execute(), uploadFiles(), listDir(), readFile(), downloadUrl(), or getUrl().

Execution surfaces

• runCommand() executes a raw Linux command inside the sandbox and returns { stdout, stderr, exitCode, error? }
• execute() writes prompt.txt, invokes run.sh, and returns the complete stdout output as a string
• stream() writes prompt.txt, invokes run.sh, and yields Response chunks as output arrives

Prompt continuation

execute() and stream() use ./run.sh -c after the first successful prompt in a session. Reconnected sandboxes start in continue mode immediately. runCommand() does not change this prompt continuation state.

Host environment vs sandbox environment

• providers supplies AI provider credentials for prompt execution
• If providers is omitted, the SDK falls back to host environment variables
• If providers is supplied, the SDK uses that object as-is and does not merge missing keys from the host environment
• env injects arbitrary environment variables into the sandbox
• When the same key exists in both places, provider keys override env

Built-in open-code template

The bundled open-code template uses /home/user as its working directory. On new sandboxes, Solaflare Agent writes MCP configuration into .solaflare-agent/mcps.json, writes rules into AGENTS.md, runs init.sh once, and uses run.sh for prompt execution. runCommand() bypasses prompt.txt and run.sh and executes the provided shell command directly inside the sandbox.

This README stays focused on onboarding. For full technical documentation, use the linked guide and API reference above.