Sandbox

import type { Sandbox } from "@elie-laloum/outpost";

Parameters and properties

diagnoseRequired
(options?: SandboxDiagnosticOptions) => Promise<SandboxDiagnosticReport>
Probe node, git and command execution in this sandbox, plus an agent CLI and file transfers when requested. Resolves with a report whose hasFailures flags failed checks; it never installs the agent.
workspaceRequired
Workspace
Workspace this sandbox runs in. close() also closes it only when createSandbox() opened it; close a supplied workspace after the sandbox.
rootRequired
string
Repository path inside the sandbox; commands without a directory run there.
dispatchRequired
<T = undefined>(options: DispatchOptions<T>) => Promise<WarmDispatchResult<T>>
Run a brief in a new conversation on this sandbox and resolve with a warm result whose resume() and fork() stay here. The branch is not integrated and the sandbox stays open, also on failure, where the error’s recovery names the branch and directory.
resumeRequired
<T = undefined>(id: string, options: DispatchOptions<T>) => Promise<WarmDispatchResult<T>>
Continue the native conversation with this id on this sandbox, restoring it first when it was captured elsewhere. The agent must support resume.
forkRequired
<T = undefined>(id: string, options: DispatchOptions<T>) => Promise<WarmDispatchResult<T>>
Continue a copy of the native conversation with this id on this sandbox, leaving the original unchanged. The agent must support automated fork.
attachRequired
(options?: AttachOptions) => Promise<AttachResult>
Start the agent’s CLI in your terminal inside this sandbox, with an optional brief or continuation, and resolve when you quit with its status and commits. Requires a single CLI agent; the session is stopped after 86400000 (24 hours).
commandRequired
(command: Command) => Promise<CommandResult>
Run one executable in this sandbox and resolve with its status and output, even when the status is nonzero; it rejects on its deadline, its signal or sandbox close. On a remote provider, the sandbox’s changes are then pulled into the host worktree.
closeRequired
(options?: { readonly preserve?: boolean; }) => Promise<Disposal>
Abort the running operation, release the environment and, when createSandbox() opened the workspace, close it; resolves with retainedDirectory when the worktree is kept. preserve: true keeps the worktree; repeated calls return the first call’s promise.
[Symbol.asyncDispose]Required
() => Promise<void>
Call close() without options, so await using closes the sandbox when its block ends.

Signature

export interface Sandbox {
  diagnose(
    options?: SandboxDiagnosticOptions,
  ): Promise<SandboxDiagnosticReport>;
  readonly workspace: Workspace;
  readonly root: string;
  dispatch<T = undefined>(
    options: DispatchOptions<T>,
  ): Promise<WarmDispatchResult<T>>;
  resume<T = undefined>(
    id: string,
    options: DispatchOptions<T>,
  ): Promise<WarmDispatchResult<T>>;
  fork<T = undefined>(
    id: string,
    options: DispatchOptions<T>,
  ): Promise<WarmDispatchResult<T>>;
  attach(options?: AttachOptions): Promise<AttachResult>;
  command(command: Command): Promise<CommandResult>;
  close(options?: { readonly preserve?: boolean }): Promise<Disposal>;
  [Symbol.asyncDispose](): Promise<void>;
}

Parameters and properties

Signature

Related contracts