OpenClaw EnterpriseDOCSGitHub

Installation Driver Package Loading Flow

Overview

The API and worker independently load trusted Installation YAML and construct their selected IAM, Compute, Configuration, Secret, and optional Sandbox capabilities. Only the API constructs the optional Backend client and ServiceAccount Driver. This trace follows package resolution through process composition and stops at request serving or worker reconciliation. Development without startup YAML uses the defaults traced in platform startup.

Entry Points

Flow

graph TD
  subgraph Startup["Independent API or worker startup"]
    A["Read trusted Installation selections"] --> B{"Bundled or packaged"}
    B -->|bundled| C["Resolve built-in implementation"]
    B -->|packaged| D["Resolve package identity and import code"]
    C --> E["Validate Driver configuration and capability"]
    D --> E
    E --> F["Construct Configuration, optional Sandbox, Compute, Secret, and IAM factory"]
  end

  subgraph OCC["Control-plane ownership"]
    F --> P{"API with ServiceAccount selection?"}
    P -->|yes| Q["Build Backend client and ServiceAccount Driver factory"]
    P -->|no| G["Construct IAM with platform state"]
    Q --> G
    G --> H["Select exact Drivers and attach lifecycle owners"]
    H --> I["Authorize requests and reconcile Namespace lifecycle"]
  end

Execution Trace

1. Resolve and validate selected Driver implementations

apps/controller/src/composition/installation-config.ts:loadInstallationConfiguration

Each process reads the same trusted startup YAML. Configuration, IAM, Compute, and optional Sandbox selections may name an operator-installed package; implementation identity comes from its installed metadata. Secret selection is required in this YAML path and accepts only bundled Kubernetes Secrets. Optional service_account selection identifies the bundled Backend member; it has no package-loading path. The operator installation guide defines the package, pinning, registry, and configuration contract. TypeBox checks each selected Driver's closed schema before implementation-owned semantic validation; invalid package exports, identity, capability, or lifecycle wiring reject startup without fallback.

For packageless Compute, the exact id compute-ssh selects SshComputeDriver with implementation occ/ssh. Every other packageless id retains Kubernetes selection. The SSH reference owns the host contract. Its helper is read at module import and sent through bounded SSH operations; bindAgent supplies authoritative Namespace and ServicePrincipal identity before revision operations.

Installed packages run arbitrary, unsandboxed code with controller database, credential, Kubernetes, tenant, and authorization authority. An untrusted or malicious package can violate authorization and tenant isolation; package validation and lockfile integrity do not establish publisher trust.

2. Construct the single authoritative runtime bundle

apps/controller/src/composition/installation-config.ts:loadInstallationConfiguration

The loader constructs Configuration, optional Sandbox, Compute, and Secret Drivers and returns them with the validated Installation and required createIAMDriver(state) function. A selected Sandbox Driver is passed to bundled Kubernetes Compute; selecting it with SSH or packaged Compute rejects startup. Bundled and packaged IAM receive the same controller-owned platform state. The bundled IAM Driver loads current policy for each identity lookup and authorization decision; packaged Drivers must do the same, which operator review verifies because the runtime cannot enforce package internals. Packaged factories must return their exact server-owned capability and identity.

Kubernetes-specific image and projected-credential requirements apply only to bundled Kubernetes Compute. SSH preflight verifies local SSH files and probes each configured host. Startup enforces the production revision-stage contract before returning any production runtime; development can use a four-operation Driver, and the worker still fails closed if a required stage becomes unavailable.

3. Construct the API-only Backend branch

server.mjs:start handles a selected ServiceAccount Driver after loading the common bundle. It requires PostgreSQL, Compute credential-storage methods, and an owning Backend definition. It reads that Backend's apiKeyPath, constructs ChatGPTClient, and supplies the ServiceAccount Driver factory to controller composition. The worker keeps only nonsecret Backend metadata; it constructs neither the client nor this Driver. The managed credential flow continues through account creation, issuance, and deployment checks.

4. Load current policy and hand off lifecycle ownership

apps/controller/src/worker.ts:ControllerWorker.start

API and worker construct separate process-local Driver instances. Production composition validates persisted policy, creates the selected IAM Driver with platform state, and selects the exact common Driver identities with OCC. The API also registers its selected ServiceAccount Driver after composition. Worker startup checks persisted identities, including Secret and optional Sandbox, and attaches selected lifecycle owners once. The bundled IAM Driver loads current policy for identity lookup and authorization; installed IAM Drivers must honor the same contract. Neither is rebuilt or replaced after account or policy changes.

OCC owns exact-resource authorization and invokes Compute only during Namespace or AgentRevision reconciliation. Embedded OpenClaw and dedicated Codex retain their existing Harness-owned runtime topology.

Debugging and Verification

Search documentation