API reference

Every export of ai-sandbox-local, with its signature and the behavior the types don't show.

import {
	createLocalSandboxSession,
	createLocalSandboxProvider,
	LocalNetworkSandboxSession,
	LocalSandboxProvider,
	LocalSandboxSession,
	type LocalSandboxSessionOptions,
	type LocalSandboxProviderSettings,
} from 'ai-sandbox-local';

Experimental_SandboxSession, Experimental_SandboxProcess, HarnessV1NetworkSandboxSession, and HarnessV1SandboxProvider come from @ai-sdk/provider-utils and @ai-sdk/harness; their fields are defined there.

createLocalSandboxSession

function createLocalSandboxSession(
	options: LocalSandboxSessionOptions,
): Promise<LocalNetworkSandboxSession>;

The entry point. Pass the result to agent.createSession({ sandboxSession }). It resolves options.workingDirectory and options.homeDirectory to absolute paths, creates both with mkdir -p, and leases one port. It rejects before doing any of that if abortSignal is already aborted.

On this path the agent never calls the harness’s onFirstCreate hook. The harness runs its bootstrap itself.

LocalSandboxSessionOptions

type LocalSandboxSessionOptions = {
	readonly workingDirectory: string;
	readonly homeDirectory?: string;
	readonly env?: Readonly<Record<string, string>>;
	readonly abortSignal?: AbortSignal;
};

LocalNetworkSandboxSession

class LocalNetworkSandboxSession
	extends LocalSandboxSession
	implements HarnessV1NetworkSandboxSession
{
	readonly id: string;
	readonly defaultWorkingDirectory: string;
	readonly ports: ReadonlyArray<number>;

	constructor(options: {
		defaultWorkingDirectory: string;
		port: number;
		env?: Readonly<Record<string, string>>;
	});

	spawn(options: SpawnOptions): Promise<Experimental_SandboxProcess>;
	restricted(): Experimental_SandboxSession;
	getPortUrl: (options: GetPortUrlOptions) => Promise<string>;
	getPortEndpoint: (
		options: GetPortEndpointOptions,
	) => Promise<{ readonly url: string }>;
	stop: () => Promise<void>;
	destroy: () => Promise<void>;
}

Create one with createLocalSandboxSession. The constructor takes an already-resolved directory and port, and doesn’t lease the port, so nothing stops another session in the process from being handed the same number.

GetPortUrlOptions, GetPortEndpointOptions, and SpawnOptions are the parameter types of the matching HarnessV1NetworkSandboxSession and Experimental_SandboxSession members: { port: number; protocol?: 'http' | 'https' | 'ws' } for the port methods, and the options below for spawn.

LocalSandboxSession

class LocalSandboxSession implements Experimental_SandboxSession {
	constructor(
		cwd: string,
		sandboxEnv?: Readonly<Record<string, string>>,
	);

	get description(): string;
	run(options: RunOptions): Promise<{
		exitCode: number;
		stdout: string;
		stderr: string;
	}>;
	spawn(options: SpawnOptions): Promise<Experimental_SandboxProcess>;
	readFile(options: ReadFileOptions): Promise<ReadableStream<Uint8Array> | null>;
	readBinaryFile(options: ReadFileOptions): Promise<Uint8Array | null>;
	readTextFile(options: ReadTextFileOptions): Promise<string | null>;
	writeFile(options: WriteFileOptions): Promise<void>;
	writeBinaryFile(options: WriteBinaryFileOptions): Promise<void>;
	writeTextFile(options: WriteTextFileOptions): Promise<void>;
}

The sandbox session without the lifecycle and port members, and what restricted() returns. RunOptions and SpawnOptions are both { command: string; workingDirectory?: string; env?: Record<string, string>; abortSignal?: AbortSignal }. The file option types are the matching Experimental_SandboxSession parameter types: path and abortSignal for reads, plus content for writes, plus encoding, startLine, and endLine on readTextFile.

Exit codes for a process ended by a signal are 128 + signal number. The environment for run and spawn is built as described in Configuration. Relative paths resolve against cwd; absolute paths and .. are not restricted.

createLocalSandboxProvider

function createLocalSandboxProvider(
	settings: LocalSandboxProviderSettings,
): LocalSandboxProvider;

Returns a LocalSandboxProvider. For the deprecated HarnessAgent({ sandbox }) option; see Getting started.

LocalSandboxProviderSettings

type LocalSandboxProviderSettings = Omit<
	LocalSandboxSessionOptions,
	'abortSignal'
>;

LocalSandboxProvider

class LocalSandboxProvider implements HarnessV1SandboxProvider {
	readonly specificationVersion: 'harness-sandbox-v1';
	readonly providerId = 'local-sandbox';

	constructor(settings: LocalSandboxProviderSettings);

	createSession: (
		options?: CreateSessionOptions,
	) => Promise<LocalNetworkSandboxSession>;
}

CreateSessionOptions is the parameter of HarnessV1SandboxProvider['createSession']: sessionId, abortSignal, identity, and onFirstCreate. Only abortSignal and onFirstCreate are used.

Each createSession call goes through createLocalSandboxSession with the provider’s settings, so every call gets its own session and port in the same directory. When onFirstCreate is given, it runs with restricted() of the new session. If it throws, the session is stopped and the error propagates.

The provider has no resumeSession, so the harness throws HarnessCapabilityUnsupportedError when you try to resume through it.