@openai/agents-core/dist/sandbox/sandboxes/docker.d.ts

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.

import type { Editor } from '../../editor';
import type { ToolOutputImage } from '../../tool';
import { type ChildProcessWithoutNullStreams } from 'node:child_process';
import type { SandboxClient, SandboxClientOptions, SandboxClientCreateArgs, SandboxArchiveLimits, SandboxClientResumeOptions, SandboxConcurrencyLimits, SandboxPreservedSessionReuseOptions, SandboxSessionSerializationOptions, SandboxSessionResumeValidationInput } from '../client';
import { Manifest } from '../manifest';
import { type ResolveSandboxPathOptions } from '../workspacePaths';
import { type ExposedPortEndpoint, type ListDirectoryArgs, type MaterializeEntryArgs, type ReadFileArgs, type SandboxDirectoryEntry, type ViewImageArgs } from '../session';
import type { LocalSandboxSnapshotSpec } from './types';
import { UnixLocalSandboxSession, type UnixLocalSandboxSessionState } from './unixLocal';
type DockerNetworkMode = 'none';
export interface DockerSandboxClientOptions extends SandboxClientOptions {
    image?: string;
    exposedPorts?: number[];
    networkMode?: DockerNetworkMode;
    /**
     * User-defined labels applied to created Docker containers.
     *
     * The SDK-owned ownership, session identity, and mount-authority labels are
     * reserved and cannot be overridden.
     */
    labels?: Record<string, string>;
    workspaceBaseDir?: string;
    snapshot?: LocalSandboxSnapshotSpec;
    concurrencyLimits?: SandboxConcurrencyLimits;
    archiveLimits?: SandboxArchiveLimits | null;
}
export interface DockerSandboxSessionState extends UnixLocalSandboxSessionState {
    sessionIdentity?: string;
    /**
     * Fingerprint of non-mount entries materialized before container creation.
     * Entries applied later at runtime are intentionally not included. This is
     * trusted same-process state and must not be serialized.
     */
    materializedEntriesFingerprint?: string;
    containerId: string;
    image: string;
    defaultUser?: string;
    configuredExposedPorts?: number[];
    networkMode?: DockerNetworkMode;
    labels?: Record<string, string>;
    dockerVolumeNames?: string[];
    snapshotExcludedPaths?: string[];
}
export declare class DockerSandboxSession extends UnixLocalSandboxSession<DockerSandboxSessionState> {
    private containerClosed;
    private closeStarted;
    private stagedMountEnvironment?;
    private readonly mountedPathGrants;
    constructor(args: {
        state: DockerSandboxSessionState;
        defaultShell?: string;
        archiveLimits?: SandboxArchiveLimits | null;
    });
    /** File APIs execute inside the container and never use the host Python backend. */
    get fileIOBackend(): 'docker';
    resolveFilesystemRunAs(runAs?: string): Promise<undefined>;
    createEditor(runAs?: string): Editor;
    protected assertSessionUsable(): void;
    viewImage(args: ViewImageArgs): Promise<ToolOutputImage>;
    pathExists(path: string, runAs?: string): Promise<boolean>;
    directoryExists(path: string, runAs?: string): Promise<boolean>;
    readFile(args: ReadFileArgs): Promise<Uint8Array>;
    listDir(args: ListDirectoryArgs): Promise<SandboxDirectoryEntry[]>;
    materializeEntry(args: MaterializeEntryArgs): Promise<void>;
    private copyEntryIntoContainer;
    private applyContainerCopyPermissions;
    private readContainerCopyArchive;
    private createPrivateGitSourceRoot;
    private readContainerCopyEntry;
    private validateContainerCopyPath;
    private materializeDockerInContainerEntry;
    applyManifest(manifest: Manifest, runAs?: string): Promise<void>;
    private applyDockerManifestExclusive;
    resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
    protected resolveCommandWorkdir(path?: string): string;
    protected spawnShellCommand(command: string, args: {
        cwd: string;
        logicalCwd: string;
        shell?: string;
        login: boolean;
        runAs?: string;
        tty?: boolean;
    }): Promise<ChildProcessWithoutNullStreams>;
    protected translateCommandInput(command: string): string;
    protected translateCommandOutput(output: string): string;
    protected materializeRestoredWorkspaceMounts(): Promise<void>;
    resolveSandboxPath(path?: string, options?: ResolveSandboxPathOptions): string;
    resolveContainerFilesystemPath(path?: string, options?: ResolveSandboxPathOptions): string;
    private assertContainerPathWritable;
    validateContainerFilesystemPath(path?: string, options?: ResolveSandboxPathOptions): Promise<string>;
    readDockerFileAs(path: string, runAs?: string, limits?: {
        maxBytes: number;
        image?: boolean;
    }): Promise<Uint8Array>;
    private runReadableDockerFilesystemCommand;
    writeDockerTextFileAs(path: string, content: string, runAs?: string, exclusive?: boolean, moveSource?: string): Promise<void>;
    deleteDockerPathAs(path: string, runAs?: string): Promise<void>;
    mkdirDockerPathAs(path: string, runAs?: string): Promise<void>;
    runDockerMountCommand(command: string, action: string, options?: {
        input?: string | Uint8Array;
        environment?: Record<string, string>;
    }): Promise<string>;
    private chownContainerPath;
    private runCheckedDockerFilesystemCommand;
    private runDockerFilesystemCommand;
    close(): Promise<void>;
    private closeContainerResources;
    private invalidateAfterFailedPrivilegedManifestTransition;
}
/**
 * Docker file APIs run inside a running container using its default user or runAs.
 * They require /bin/sh and standard GNU filesystem utilities, including realpath.
 * Resource materialization also requires GNU tar inside the container.
 * Editor updates reject source files larger than 10 MB before applying changes.
 * File helpers use an isolated environment; application and mount commands retain
 * their configured environment.
 * File operations do not use host Python or fall back to host paths. Path grants
 * added after creation become container-visible only after resume or recreation.
 */
export declare class DockerSandboxClient implements SandboxClient<DockerSandboxClientOptions, DockerSandboxSessionState> {
    readonly backendId = "docker";
    readonly supportsDefaultOptions = true;
    private readonly options;
    private readonly failedCreateCleanupTokens;
    constructor(options?: DockerSandboxClientOptions);
    create(args?: SandboxClientCreateArgs<DockerSandboxClientOptions> | Manifest, manifestOptions?: DockerSandboxClientOptions): Promise<DockerSandboxSession>;
    resume(state: DockerSandboxSessionState, options?: SandboxClientResumeOptions<DockerSandboxClientOptions>): Promise<DockerSandboxSession>;
    validateSessionStateForResume(input: SandboxSessionResumeValidationInput<DockerSandboxSessionState>, options?: SandboxClientResumeOptions<DockerSandboxClientOptions>): void;
    canReusePreservedOwnedSession(state: DockerSandboxSessionState, options?: SandboxPreservedSessionReuseOptions<DockerSandboxClientOptions>): Promise<boolean>;
    serializeSessionState(state: DockerSandboxSessionState, options?: SandboxSessionSerializationOptions): Promise<Record<string, unknown>>;
    deserializeSessionState(state: Record<string, unknown>): Promise<DockerSandboxSessionState>;
    private restoreIfNeeded;
    private restoreSnapshotIntoNewWorkspace;
    private cleanupDockerResources;
    private restartContainer;
    private retryFailedCreateCleanups;
}
export {};