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.
agentOptional
CliAgent | CustomAgent | ReplayAgent | FallbackAgent
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.
sandboxProviderOptional
SandboxProvider | undefined
Provider that allocates the environment, default createDockerSandboxProvider(). A remote provider requires a named or integrate branch and defaults branch to integrate.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
branchOptional
BranchPolicy | undefined
Branch policy: current, named or integrate. Default { mode: “current” }; createSandbox() and dispatch() on a remote provider default to integrate.
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.
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.
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.
briefRequired
Brief
Task given to the agent: literal text or a file brief.
passesOptional
number | undefined
Maximum passes, default 1. Each pass reruns the brief in a new conversation and the dispatch stops at the first pass whose text contains a completion marker. Must be 1 with response or continuation.
untilOptional
string | readonly string[] | undefined
Completion marker or markers searched in the last turn’s text, default <outpost>done</outpost>. An empty list disables matching, so every pass runs; empty strings are rejected.
idleMsOptional
number | undefined
Longest silence allowed from the agent, default 600000 (10 minutes). Past it the turn stops with code timeout.
idleWarningMsOptional
number | undefined
Silence after which a warning event is emitted, then repeated at the same interval; default 60000.
settleMsOptional
number | undefined
Wait after a completion marker before stopping an agent that is still running, default 60000. The turn still succeeds.
deadlineMsOptional
number | undefined
Maximum duration of each agent process, default 3600000 (one hour). Past it the turn fails with code timeout.
expansionMsOptional
number | undefined
Deadline for each shell expansion in a file brief, default 30000. Past it the dispatch fails with code timeout.
steeringOptional
Steering | undefined
Controller from createSteering(), attached for the whole dispatch and released when it ends. resume() and fork() do not reuse it.
continuationOptional
{ readonly id: string; readonly fork?: boolean; } | undefined
Native conversation to continue, by id; fork: true continues a copy and leaves the original unchanged. Requires one pass and an agent that supports resume.
responseOptional
ResponseSpec<T> | undefined
Typed response contract: the tagged answer is parsed and validated, and an invalid answer gets up to repairs correction turns. Requires one pass.
telemetryOptional
DispatchTelemetry | undefined
Instrumentation spanning the whole dispatch, including preparation, synchronization and cleanup. Its failures do not change the outcome.
observeOptional
((event: AgentObservation) => void) | undefined
Receives each normalized agent event with its pass number and timestamp. An exception thrown here is collected in observerErrors and does not change the outcome.
warnOptional
((message: string) => void) | undefined
Receives nonfatal warnings, such as an idle agent or a conversation storage problem.
diagnosticOptional
((message: string) => void) | undefined
Receives diagnostic messages, such as the estimated token size of each expanded brief command.