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, codex, or codex: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. The codex template specifically requires OPENAI_API_KEY; Anthropic and Google keys do not authenticate Codex CLI.

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

Live Template Smoke Test

The Codex template has an explicit TypeScript smoke-test command. It creates a real sandbox, calls OpenAI, and logs each SDK step, so run it only when you intend to use external resources:

E2B_API_KEY=your_e2b_key \
OPENAI_API_KEY=your_openai_key \
pnpm test:e2b:codex

The command expects an accessible codex E2B template by default. To test a development build:

SOLAFLARE_TEST_TEMPLATE=codex-dev pnpm test:e2b:codex

Optional overrides include SOLAFLARE_TEST_MODEL and SOLAFLARE_TEST_TIMEOUT_MS.

Core Concepts

Template names

The name field is the E2B template identifier used when creating a new sandbox. Bundled templates include open-code and codex, and tagged variants such as open-code:large or codex: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 { runId, stdout, stderr, exitCode, error?, diagnostics? }
• execute() writes prompt.txt, invokes run.sh, persists per-run logs, and returns the complete stdout output as a string
• stream() writes prompt.txt, invokes run.sh, persists per-run logs, and yields Response chunks with { agentId, runId, response }

Diagnostics

Every command or prompt run gets a run ID. Pass runId explicitly when you need correlation with an external job, ticket, or result envelope:

const output = await agent.execute({
  runId: "aipla-209-attempt-1",
  prompt: "Implement the task packet.",
});

const diagnostics = await agent.getDiagnostics({ runId: "aipla-209-attempt-1" });
const bundle = await agent.downloadDiagnostics({
  runId: "aipla-209-attempt-1",
  includeContents: false,
  includeUrls: true,
});

Bundled templates write run artifacts under .solaflare-agent/runs/<run-id>/, including prompt.txt, stdout.log, stderr.log, agent.log, summary.json, and environment.json.

Task context handoff

Pass task when a higher-level orchestrator has already resolved ticket context. The SDK validates baseBranch: "main" and targetBranch values like feature/solaflare-coding-aipla-209, uploads .solaflare-agent/task.json, and prepends a short instruction telling the coding agent to read it first.

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
• The codex template is powered by Codex CLI and therefore needs OPENAI_API_KEY even though the SDK provider object also supports other providers

Built-in templates

open-code

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.

codex

The bundled codex template installs @openai/codex and RTK inside the E2B image, generates ~/.codex/config.toml, and runs prompts through non-interactive codex exec. Continued Solaflare prompts use codex exec resume --last so the Codex CLI session is restored inside the same sandbox. Use OPENAI_API_KEY for prompt execution.

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