createSandbox

Purpose and behavior

Allocate an environment with sandboxProvider and keep it open for sequential dispatches, commands and terminal sessions until you close it. Without workspace, it opens one that close() also closes, by default on the checkout in the current directory with Docker. If setup fails, it releases what it allocated, closes the workspace it opened and rethrows.

Complete example and detailed rules.

Parameters and properties

• optionsOptional
  SandboxOptions | undefined
  Workspace to use or to open (repository, branch, copies), provider, default agent, setup hooks and remote synchronization settings.
• 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
  DispatchAgent | undefined
  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.

Returns

Promise<Sandbox>

Signature

export declare function createSandbox(
  options?: SandboxOptions,
): Promise<Sandbox>;

Related contracts

• Sandbox
• SandboxOptions