Execution providers

An execution provider controls where commands and agent processes run. Constructors define configuration; allocation happens when a session uses it.

Local and Docker return values

Import constructors from @laufwerk/execution (also available through /local and /docker). Both return an object with:

The public ExecutionTarget type from @laufwerk/sdk contains only kind and sandbox. Keep the constructor's inferred type if you need .agent(); annotating it as ExecutionTarget hides the factory method from TypeScript.

createLocalExecution(options = {})

Local execution uses the host user's permissions. It rejects read-only workspace access and injected skills; it is not a security sandbox. Agent bootstrap requires Node.js 22+ on PATH and suitable subscription credentials. Local resume checks the recorded host/platform and requires retained session state.

createDockerExecution(options = {})

Requires a local Docker engine/Desktop in Linux-container mode. Remote Docker contexts are rejected. Custom images must contain Node, pnpm, Git, Bash and setsid. Docker supports copy workspaces and enforced read-only mounts; it does not support direct workspaces. Each session has its own container even when several sessions mount the same workspace.

Standard Codex agents require a prepared image in alpha.13. init --execution docker prepares it; for existing consumers run laufwerk prepare docker before starting workflows and again after recipe-changing upgrades. Session startup reports a missing/stale image rather than preparing it. Explicit image keeps its own bootstrap behavior unless codexBootstrap: "prepared" is selected. Claude uses its normal bootstrap path.

DockerResources

swapBytes: 0 requests no additional swap. Omitted limits leave Docker/host defaults; they do not mean zero resource consumption. Invalid values throw synchronously during provider construction.

import { createDockerExecution, createLocalExecution } from "@laufwerk/execution";

export const docker = createDockerExecution({
  credentials: "codex-subscription",
  resources: {
    cpus: 2,
    memoryBytes: 4 * 1024 ** 3,
    swapBytes: 0,
    pids: 512,
  },
});

export const local = createLocalExecution({ credentials: "codex-subscription" });

These limits are example configuration, not a guarantee every task fits within them. See Execution choices for operational setup.

Prepared Codex images

prepareDockerCodex(options) is exported from @laufwerk/execution/docker (not the package root). It manages the standard Codex image cache and returns Promise<{ image: string; manifestPath: string; reused: boolean }>.

Preparation uses a cache lock and validates the pinned bootstrap recipe and image identity before reusing a receipt. The CLI's prepare docker is the setup path for most consumers. The following lower-level helpers manage explicit receipts.

prepareCodexImage(options): Promise<string> prepares a reusable Docker image using the pinned adapter bootstrap. Run it during setup, outside a workflow.

loadPreparedCodexImage(manifestPath: string, expectedBaseId?: string, signal?: AbortSignal): Promise<string> validates the manifest against the adapter recipe, user/group and Docker image identities, then returns the usable image identity. Stale/mismatched manifests fail; prepare again when the recipe changes. Neither helper attaches customer workspaces or runtime credentials to the reusable image.

import { createDockerExecution, loadPreparedCodexImage, prepareCodexImage } from "@laufwerk/execution";

export async function prepare(baseImage: string, manifestPath: string) {
  await prepareCodexImage({
    image: baseImage, manifestPath,
    resources: { memoryBytes: 4 * 1024 ** 3, cpus: 2 },
  });
  return createDockerExecution({
    image: await loadPreparedCodexImage(manifestPath),
    credentials: "codex-subscription",
  });
}

Legacy createMicrosandbox(options)

Import from @laufwerk/sandbox. Returns HarnessV1SandboxProvider, not the local/Docker object with .agent(). Construct a HarnessAgent directly and omit execution in Workspace.open for this legacy path.

This integration also exports low-level workspace-volume, credential and provider helpers plus Microsandbox's upstream exports. They are infrastructure APIs; workflow authors should use Workspace for managed files and Session for lifecycle. Do not mix a Microsandbox agent with a local/Docker workspace.