openWorkspace

Purpose and behavior

Open a workspace on a host Git checkout: take its lock, prepare the checkout or worktree the branch policy selects, copy copies, then run workspaceReady. It serves successive sandboxes, one at a time, until close(). A lock held by a live process fails with code conflict instead of waiting.

Complete example and detailed rules.

Parameters and properties

• optionsOptional
  WorkspaceOptions | undefined
  Repository, branch policy, copies, hooks, stage deadlines, storage quota, label, cancellation signal and observation hub.
• 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.signalOptional
  AbortSignal | undefined
  Cancels opening: checked before allocation and passed to the storage reservation and workspaceReady commands. An open workspace ignores it.
• 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.hooksOptional
  LifecycleHooks | undefined
  Setup commands: workspaceReady once when the workspace opens, then hostReady and sandboxReady for each sandbox on it unless that sandbox passes its own hooks. Each command stops after 600000 (10 minutes) unless it sets deadlineMs; a nonzero exit fails with code process.

Returns

Promise<Workspace>

Signature

export declare function openWorkspace(
  options?: WorkspaceOptions,
): Promise<Workspace>;

Related contracts

• Workspace
• WorkspaceOptions