Interface SandboxHandle

packages/ai-sandbox/src/contracts.ts:166–190

/** The uniform runtime surface a sandbox exposes. */
export interface SandboxHandle {
  /** Provider-assigned id used to reconnect to this sandbox. */
  readonly id: string
  /** Provider name (e.g. "docker", "cloudflare", "local-process"). */
  readonly provider: string
  /**
   * Real filesystem path backing the virtual workspace root (`/workspace`).
   * Harness CLIs and ACP `newSession` interpret cwd literally — use
   * {@link resolveHarnessCwd} rather than the virtual path when the provider
   * maps `/workspace` elsewhere (Daytona, Vercel, local-process).
   */
  readonly workspaceRoot?: string
  /** What this sandbox can do. */
  readonly capabilities: SandboxCapabilities
  readonly fs: SandboxFs
  readonly git: SandboxGit
  readonly process: SandboxProcess
  readonly ports: SandboxPorts
  readonly env: SandboxEnv
  /** Capability-gated: throws UnsupportedCapabilityError if `capabilities.snapshots` is false. */
  snapshot?: (label?: string) => Promise<SnapshotRef>
  /** Capability-gated: throws UnsupportedCapabilityError if `capabilities.fork` is false. */
  fork?: () => Promise<SandboxHandle>
  destroy: () => Promise<void>
}

/** Input passed to {@link SandboxProvider.create}. */
export interface SandboxCreateInput {