attach

Purpose and behavior

Open a CLI agent’s own interactive terminal in a sandbox allocated for this call, then return the session’s exit status and commits. Status 0 applies the branch policy and closes the sandbox; a nonzero status or a failure closes it and keeps the worktree. The agent process has a deadline of 86400000 (24 hours).

Complete example and detailed rules.

Parameters and properties

• optionsRequired
  SandboxOptions & AttachOptions & RequiredAgent
  Sandbox settings (repository, branch, provider, hooks) combined with the CLI agent, brief, continuation and terminal streams.
• options.includeUncommittedOptional
  boolean | undefined
  Remote providers only: also send the managed worktree’s uncommitted changes and untracked, non-ignored files, default false. Without it, synchronization fails with code workspace when the sandbox touches one of those files, which includes any copies entry not ignored by a committed .gitignore.
• options.agentOptional
  CliAgent | CustomAgent | ReplayAgent
  Default agent for dispatch(), resume(), fork() and attach() on this sandbox; an operation’s own agent replaces it. On a remote provider with bootstrap on, its first candidate is installed during allocation; attach() rejects a fallback agent on every provider.
• options.sandboxProviderOptional
  SandboxProvider | undefined
  Provider that allocates the environment, default createDockerSandboxProvider(). A remote provider requires a named or integrate branch and defaults branch to integrate.
• options.workspaceOptional
  Workspace | undefined
  Open workspace to run in, from openWorkspace(); close() leaves it open. Combining it with repository, branch, copies or storageQuota, or passing a workspace already bound to an open sandbox, fails with code configuration.
• options.hooksOptional
  LifecycleHooks | undefined
  Setup commands, each required to exit 0 within its deadlineMs, default 600000 (10 minutes): workspaceReady on the host once a new worktree exists, then hostReady (host, in order) and sandboxReady (sandbox, all at once) concurrently; a nonzero exit fails setup with code process. With a supplied workspace, workspaceReady does not run and hooks given here replace the workspace’s hostReady and sandboxReady.
• options.signalOptional
  AbortSignal | undefined
  Aborting it cancels sandbox setup: allocation, repository seeding, agent installation and setup hooks. createSandbox() stops watching it once the sandbox is returned.
• options.loggingOptional
  Logging | undefined
  Journal of each dispatch on this sandbox, default a local journal under .outpost/storage; stdout prints progress instead, false disables it, and an object sets transporter, verbose and replayable. A dispatch’s own logging replaces it.
• options.bootstrapOptional
  boolean | undefined
  Install a built-in CLI agent missing from a remote sandbox, at its pinned version, before its first use; default true. Mounted and host providers never install: the CLI must be in the image or on the host.
• options.conversationHomeOptional
  string | undefined
  Host directory used in place of your home directory to store and find captured native conversations. Default: your home directory for Claude and Codex transcripts, the repository for Copilot and Kimi session bundles.
• options.recoveryTransportOptional
  Transport | undefined
  Remote providers only: before pulled changes are applied, archive the host backup to this transport as well as to .outpost/recovery. Archives outlive the sandbox.
• options.activityTransportOptional
  Transport | undefined
  Transport for this sandbox’s resource activity record, default local storage under .outpost/storage. The record is deleted after a clean close and kept with a failure phase when cleanup fails.
• options.observationOptional
  ObservationHub | undefined
  Hub that receives this workspace’s Git, copy, hook, integration and cleanup operations. The caller keeps ownership; the workspace never closes it.
• options.storageQuotaOptional
  Omit<StorageReservationOptions, "signal"> | undefined
  Storage admission checked before the workspace opens: reserves reserveBytes and fails with code configuration when usage under .outpost plus active reservations would exceed maxBytes. The reservation is released when the workspace closes.
• options.repositoryOptional
  string | undefined
  Path inside the host Git checkout, default the process working directory. Outpost works from the checkout’s top-level directory; an unavailable directory fails with code workspace.
• options.branchOptional
  BranchPolicy | undefined
  Branch policy: current, named or integrate. Default { mode: “current” }; createSandbox() and dispatch() on a remote provider default to integrate.
• options.copiesOptional
  readonly string[] | undefined
  Repository-relative files or directories copied from the host checkout into the new worktree before workspaceReady; missing entries are skipped. Requires named or integrate, and absolute, .. or .git paths fail with code configuration. An untracked or ignored copy keeps the worktree when it closes. On a remote provider without includeUncommitted, a copy not ignored by a committed .gitignore makes the first synchronization fail with code workspace.
• options.limitsOptional
  StageLimits | undefined
  Deadlines in milliseconds for copying, Git preparation, commit collection and integration. Past a deadline the stage fails with code timeout, or conflict for integration.
• options.labelOptional
  string | undefined
  Name used in the integrate branch (outpost/<label>-<id>), the worktree directory under .outpost/workspaces and the startup-failure journal; lowercased, other characters replaced by -, cut to 48.
• options.askOptional
  VariableQuestion | undefined
  Answers each {{name}} variable a file brief leaves without a value, one call per name, before the terminal opens. Without it, Outpost asks on the host terminal and rejects with code configuration when stdin is not a TTY.
• options.briefOptional
  Brief | undefined
  First message given to the agent: literal text or a file brief. Without it, the terminal opens with no message.
• options.continuationOptional
  { readonly id: string; readonly fork?: boolean; } | undefined
  Native conversation to reopen, by id; fork: true opens a copy and leaves the original unchanged. Rejects with code configuration when the agent cannot resume or fork.
• options.terminalOptional
  { readonly input?: Readable; readonly output?: Writable; readonly error?: Writable; } | undefined
  Streams used instead of the host terminal: input feeds the agent, output and error receive what it writes. Omitted, the agent reads and writes the host process’s stdin and stdout.

Returns

Promise<AttachResult>

Signature

export declare function attach(
  options: SandboxOptions & AttachOptions & RequiredAgent,
): Promise<AttachResult>;

Related contracts

• AttachOptions
• AttachResult
• RequiredAgent
• SandboxOptions