SandAgent Manager - Manages sandbox and runner lifecycle, defines core interfaces
npm install @sandagent/managerCore manager package for SandAgent - manages sandbox and runner lifecycle, defines core interfaces.
This package is the core runtime that wires sandbox adapters + a runner spec into an AI SDK UI stream you can consume from your server or CLI.
@sandagent/manager is the foundational package that provides:
- SandAgent: Main class for managing sandboxed agent instances
- Core Interfaces: SandboxAdapter, SandboxHandle, RunnerSpec, etc.
- Transcript Writers: Tools for logging agent execution (JSONL, Memory, Console, Multi)
- Type Definitions: Shared types for messages, streams, and sandbox operations
This package is typically used as a dependency by higher-level packages like @sandagent/sdk and sandbox adapters.
``bash`
npm install @sandagent/manager
`typescript
import { SandAgent } from '@sandagent/manager';
import { E2BSandbox } from '@sandagent/sandbox-e2b';
const agent = new SandAgent({
sandbox: new E2BSandbox({ apiKey: 'xxx' }),
runner: {
kind: 'claude-agent-sdk',
model: 'claude-sonnet-4-20250514',
outputFormat: 'stream',
},
env: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
},
});
// Stream a task
const stream = await agent.stream({
messages: [
{ role: 'user', content: 'Create a hello world program' }
],
workspace: {
path: '/workspace',
},
});
// Read the stream
const reader = stream.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(value);
}
// Cleanup
await agent.destroy();
`
`typescript
import { SandAgent, JsonlTranscriptWriter } from '@sandagent/manager';
const transcriptWriter = new JsonlTranscriptWriter('./transcript.jsonl');
const stream = await agent.stream({
messages: [{ role: 'user', content: 'Do something' }],
workspace: { path: '/workspace' },
transcriptWriter,
});
`
`typescript`
await agent.uploadFiles([
{ path: 'hello.txt', content: 'Hello World!' },
{ path: 'data.json', content: JSON.stringify({ key: 'value' }) },
], '/workspace');
Interface that sandbox implementations must follow:
`typescript`
interface SandboxAdapter {
attach(): Promise
getHandle(): SandboxHandle | null;
getEnv?(): Record
getWorkdir?(): string;
}
Interface for interacting with an attached sandbox:
`typescript`
interface SandboxHandle {
exec(command: string[], opts?: ExecOptions): AsyncIterable
upload(files: Array<{ path: string; content: Uint8Array | string }>, targetDir: string): Promise
readFile?(filePath: string): Promise
runCommand?(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>;
destroy(): Promise
getWorkdir?(): string;
}
Specification for the runner to execute inside the sandbox:
`typescript`
interface RunnerSpec {
kind: 'claude-agent-sdk' | string;
model: string;
systemPrompt?: string;
maxTurns?: number;
allowedTools?: string[];
outputFormat?: 'stream' | 'json';
}
Available transcript writers:
- JsonlTranscriptWriter: Write to JSONL file
- MemoryTranscriptWriter: Store in memory
- ConsoleTranscriptWriter: Log to console
- MultiTranscriptWriter: Write to multiple writers
`typescript
import {
JsonlTranscriptWriter,
MemoryTranscriptWriter,
MultiTranscriptWriter
} from '@sandagent/manager';
const transcriptWriter = new MultiTranscriptWriter([
new JsonlTranscriptWriter('./transcript.jsonl'),
new ConsoleTranscriptWriter(),
]);
`
#### Constructor
`typescript`
new SandAgent(options: SandAgentOptions)
Options:
- sandbox (required): A SandboxAdapter instancerunner
- (required): RunnerSpec configurationenv`: Environment variables for the sandbox
-
#### Methods
stream(input: StreamInput): Promise
Stream a task through the agent. Returns a ReadableStream of AI SDK UI messages.
uploadFiles(files: Array<{ path: string; content: Uint8Array | string }>, targetDir?: string): Promise
Upload files to the agent's workspace.
destroy(): Promise
Destroy the sandbox and release resources.
- Node.js 20+
- A sandbox adapter (@sandagent/sandbox-e2b, @sandagent/sandbox-local, etc.)
Apache-2.0