OpenClaw EnterpriseDOCSGitHub

ComputeDriver contract

Interface contents

Overview

Compute manages Namespace infrastructure, Agent workloads, identity, isolation, readiness, and gateway routing. A paired Sandbox Driver can provision Harnesses.

Interface

Exported interface

Properties

Property Requirement Value and meaning
id, implementation Required Identify the Driver; OCC records both on the revision for worker checks before dispatch.
capability Required Must be "compute".
activationOrder Optional Defaults to "afterCommit"; controls traffic switching relative to saving the selected revision.
agentProvisioning Optional Lists supported execution modes; OCC rejects unlisted modes. Omission does not disable provisioning.
computeLifecycleHooks Optional Workload hooks.
namespaceLifecycleHooks Optional Registration-level Namespace hooks.
maintenanceIntervalMs Optional Interval between maintenance passes, in milliseconds; positive safe integer.
requiresAgentRuntimeCredentials Optional When true, OCC checks transport credentials before deployment and can create them before the first revision. Missing status/provisioning methods mean dependency unavailable.
runtimeLogging Optional Defaults to "platform"; "driver" gives Compute ownership of native logging configuration and delivery.
supportsGatewayManagedMode Optional Set true to enforce Gateway administration restrictions. Otherwise managed mode defaults off; OCC refuses explicit enablement.
supportsWorkspaceSetup Optional Set true to deliver initial workspace files. Without it, the worker refuses revisions with workspace setup.

Methods

Method Requirement Caller and behavior
ensureNamespace Required Prepare or verify Namespace isolation before Agents; return namespaceReady when ready.
deleteNamespace Required Remove supported infrastructure for an empty Namespace. Return namespaceDeleted only after teardown. Refuse deletion of infrastructure outside the Driver's ownership.
checkNamespaceDeletion Conditional Read-only eligibility before participant cleanup.
resolveSandboxNamespaceContext Conditional Resolve Sandbox placement and client without provisioning.
prepareRevision Required Create or reuse the gateway and prepare the Harness. Return readiness for the requested Namespace, Agent, and revision. The worker supplies authorized revision context.
stopRevision Required Remove inbound routing and stop execution, including applicable Driver hooks and Sandbox cleanup. Keep Agent credentials, workspace data, and saved revisions. Repeated calls must be safe.
retireRevision Required Revoke workload access, stop the workload, and complete applicable Sandbox cleanup. Preserve the replacement's gateway.
preflight Optional Check startup dependencies. An error blocks startup. Warnings are logged as compute.preflight-warning. Bundled Kubernetes Compute must implement this in production.
setLifecycleDrivers Optional Receive the selected Drivers that supply lifecycle hooks. Startup refuses a hook provider if Compute cannot accept it.
bindAgent Optional The worker supplies the approved Namespace and Agent before revision work. A rejection prevents further runtime work on that attempt.
validateConfiguration Optional Check native Configuration values on save. Preset validation identifies unresolved variables separately.
validateGatewaySettings Optional Refuse gateway settings the Driver cannot honor at deployment. Name the setting without exposing its value. OCC skips this check if omitted.
normalizeHarnessOverrides Optional Normalize overrides; requires resolveHarnessConfiguration. Omission rejects nonempty requests.
resolveHarnessConfiguration Optional Resolve before credentials and egress; save for execution. Omission saves {}.
validateHarnessCredentialSources Optional Check source consent against resolved settings before delivery.
validateHarnessAuth Optional Check the Harness, authentication method, Configuration, and bindings. Deployment and Agent provisioning fail if this check is unavailable.
validateWorkspaceSetup Optional Check whether initial files can be delivered on the selected topology. See admission checks for when OCC calls each validator.
validateAgentProvisioning Optional Required for Agent provisioning; see prerequisites and refusals below.
validateRepositoryCredentialSupport Optional Check support for repository credentials on the selected Sandbox topology. Without it, OCC cannot offer repository options.
validateRepositoryCredentials Optional Check repository bindings against the requested Harness and Sandbox. OCC refuses bindings if it cannot validate them.
validateExecutionAdmission Optional Check whether Compute supports the requested execution at admission and again before release. Without it the platform admits ordinary unprotected execution only.
admitRevision Optional Return Driver-owned admission data for OCC to save with the revision. Without it, OCC stores the revision without Driver admission data.
activateRevision, deactivateRevision Optional Switch traffic to a ready revision or withdraw an unpublished candidate. Production startup checks for both. A Driver selecting beforeCommit must also implement activation in development.
requiresStoppedPredecessors Optional Return true to stop older revisions before preparing a replacement. Otherwise the previous route can serve during preparation.
describePrepareRevisionFailure Optional Supply safe diagnostic fields for a rejected preparation. The worker validates the fields and excludes raw provider errors.
getGatewayEndpoint Optional Private WSS address for workspace-file access and native administration, or undefined.
getGatewayChatEndpoint Optional Revision's WSS chat endpoint and equivalent HTTPS UI. Enforce operator.sessions.write across HTTP, WebSocket, and device grants. Omission/undefined means unsupported; never fall back to getGatewayEndpoint.
getAgentRuntimeCredentialStatus Optional Report whether the Agent's generated transport credentials are stored. Missing support prevents the status read.
provisionAgentRuntimeCredentials Optional Create initial transport credentials for the approved Agent. Missing support prevents provisioning.
deleteAgentRuntimeCredentials Optional Remove Agent-owned credentials after revision retirement. A Driver that provisions them but omits deletion fails Agent deletion permanently.
deleteServiceAccountCredential Optional On forced ServiceAccount deletion, remove the account-owned Secret when the ServiceAccount Driver can no longer revoke the token. OCC skips this call if absent.
resolveSandboxNamespace Optional Return the Namespace as provisioned by Compute. Paired Sandbox and Credential Gateway operations need this placement.
withdrawCredentialSource Optional Confirm that the revision's attachment was revoked or is absent. Without this method the worker fails withdrawal with CREDENTIAL_WITHDRAWAL_UNSUPPORTED.
withdrawHarnessExposure Optional Remove dedicated OpenClaw status exposure after enrollment or permanent candidate failure with a Sandbox retained for diagnosis. The sweep makes at most five attempts per revision per worker start. Without this method the worker skips it.
repositoryWorkerRestartDisposition Optional Assess replacement from existing revision evidence. Omission means unknown.
verifyRepositoryExecution Optional Identify an existing execution without starting or repairing it. Missing support supplies no identity for a repository credential session.
retireExpiredRepositoryAccess Optional For expiry or committed standing/finite withdrawal, report withdrawn only after verifying revoked Git and the same independently authorized, ready inference runtime; otherwise pending or retire-runtime. Without this method, expiry retires the runtime except for policyReductionVersion: 2 egress plans, which use policy reduction.
rejectedExecutionWithdrawal Optional After release is refused, select a callback to withdraw a previously admitted grant. The worker runs it under the active revision's claim. With no callback, the refusal stands.
observeRevision Optional Read Harness state for an unverified repository execution. Failure yields unknown. This cannot establish Git execution identity.
getRuntimeImages Optional Report revision-owned containers, excluding separate Sandbox Driver workloads. Return full lowercase 40-character Git SHAs for known commits and null for unknown image IDs or commits; never infer commits from tags. OCC returns entries without validation. Without a selected revision it reports undeployed; without this method, unsupported.
discoverHarnessModels Optional Accept authMethod, provider, and apiKey. Return native model IDs and names. Never persist the credential. If discovery is unavailable, enter the model ID manually.
diagnoseAgentDeployment Optional Return current checks for one revision. Without support, OCC reports dependency unavailable.
describeAgentRuntime Optional Describe the revision's workloads and log sources. Without this method, the runtime description and log routes return 501.
readAgentRuntimeLogs Optional Return raw lines from a listed, revision-owned container within the request limits. Without it, Compute container logs are unavailable. Sandbox logs use the paired Sandbox Driver.

Model discovery

For model discovery, OCC checks Agent creation permission in the Namespace. The bundled Docker and Kubernetes model discovery client uses a 10-second timeout and accepts up to 4 MiB per response, ten pages, and 10,000 model IDs. It refuses redirects. See model discovery and API egress.

Namespace and gateway results

Namespace results follow the shared lifecycle contract. Worker-log failure reasons allow up to 256 characters: letters, digits, spaces, and . _ : / @ -. Exclude provider output and other tenants' values.

Derive gateway endpoints from trusted settings and approved resource IDs, independently of readiness and authorization.

Optional initial runtime credential provisioning

Agent provisioning requires validateAgentProvisioning({ executionMode, configuration }), credential status and provisioning methods, and Configuration createExact and inspectExact. Missing methods mean dependency unavailable. Validation runs for new requests, replay, retry, and worker writes, not stored-status reads.

Throw ComputeGatewaySettingError for a rejected setting; name its requirement, never its value. OCC returns 409; the worker records permanent PROVISIONING_REJECTED. DependencyUnavailableError remains retryable. Other validator errors become ComputeProvisioningRefusedError with a fixed 409 and a reason in worker logs. Exclude secrets and provider output. An uncertain pending write instead yields retryable PROVISIONING_OUTCOME_UNKNOWN.

For credential status and creation, OCC preserves RuntimeCredentialsForbiddenByClusterError and converts other errors to a fixed dependency-unavailable error.

Read status with Agent read. Initial provisioning also requires operate, a ready Namespace, and no earlier revision. OCC passes approved identities under Namespace and Agent locks. External credential writes can survive a database rollback. Read stored status before retrying. If credentials are missing after a revision exists, restore them before deploying. These methods verify stored transport credentials. They cannot rotate them or verify model authentication. Codex device login belongs to the Credential Refresh Driver.

Startup failure evidence

An ordinary ready: false keeps preparation pending. Return a pendingReason if known. The worker rejects another revision's readiness result. For a held startup failure, return validated runtimeFailure evidence for this revision: component, check, checkedAt, code, and an optional cause. Omit credentials, provider messages, and untrusted observations. The worker flow explains which failures end deployment immediately, such as crash-loop, and which wait until its deadline.

Throw ComputePreparationFailedError for terminal initialization failure. The worker records the failed deployment and queues stopRevision for that candidate in one transaction. After restart it resumes cleanup.

Runtime reads and logging

Diagnostics read the requested revision without changing its deployment or running another model probe. OCC accepts up to 32 checks and validates timestamps and state. With platform logging, OCC applies its Harness logging policy. The Driver rechecks workload ownership before each read. For a cluster 403, raise RuntimeLogsForbiddenByClusterError. OCC redacts and limits each response to 512 KiB. A Driver-managed collector must supply its own access control, redaction, and delivery guarantees. With Driver-owned logging, OCC preserves the validated native settings and both runtime-description and log routes return 501. See Agent logs and image provenance.

IAM

OCC authenticates the caller and uses the IAM Driver to authorize the exact resource. For deployment, the worker rechecks the original actor's deploy on the Agent and read on its Configuration. Both actor and Agent service principal need operate on each bound Secret and applicable credential source. ServiceAccount authentication also requires the actor to read the account. Denied access or unavailable IAM blocks preparation.

Use the Namespace, Agent, revision, and references supplied by OCC. Deliver model credentials only to the selected Harness. Keep Secret values out of Configuration, responses, logs, errors, and audit records. See credential delivery. Installed Drivers run with control-plane privileges.

Lifecycle

Driver initialization and shutdown

Each API or worker process loads its configured Driver, validates its methods, attaches selected hooks, and runs applicable preflight. Process shutdown does not delete Namespace or Agent resources. See Driver loading.

Production revision stages

sequenceDiagram
    participant S as Platform state
    participant W as Worker
    participant C as Compute
    Note over S: API saves revision and queues deployment
    W->>S: Claim deployment
    W->>W: Recheck access
    opt Exclusive replacement
        W->>C: Stop earlier revisions
    end
    W->>C: prepareRevision
    alt Not ready
        C->>W: Return pending or failure evidence
    else Ready
        alt afterCommit (default)
            opt First dedicated deployment
                W->>C: deactivateRevision
            end
            W->>S: Select if expected ID matches
            W->>C: activateRevision
        else beforeCommit
            W->>C: activateRevision
            W->>S: Select if expected ID matches
        end
        W->>C: Retire earlier revisions
    end

Before calling Compute, the worker checks its selected identity and current credential references. Activation must be safe to repeat. A failed activation after selection resumes at finalization. In protected Git startup, both version 5 online-request and version 6 request-hook-observed support selection before readiness. When Compute reports heldForRepositoryGitMaterial and REPOSITORY_GIT_ROUTE_PENDING without a runtime failure, the worker can record the selection. The original work stays queued until that revision is ready; only then does the worker activate it, retire its predecessor, and complete the work.

Exclusive replacement closes earlier credential sessions and stops each earlier revision, including failed candidates, before preparation. A failed stop blocks the successor. Older work and maintenance cannot recreate the stopped execution. Compute must confirm resource release and preserve workspace data on repeated stops. This policy permits downtime. Recover by deploying a newer revision.

SandboxDriver coordination

Bundled Kubernetes Compute prepares Namespace isolation before Sandbox setup. A Sandbox can create the dedicated Harness. Compute owns the gateway, workload identity, readiness decision, and routing. Wait for required credential attachments before activation. Complete Sandbox cleanup even if the workload is already absent.

Optional selected-driver hooks

Startup hooks run in selection order on the embedded workload or the dedicated Harness. Cleanup runs in reverse. Hooks cannot change images, commands, placement, networking, or authorization. Preserve the opaque- environment restriction (up to 64 values, no plaintext credentials or reserved names). Undo completed hooks after preparation fails. On cancellation, rollback uses a separate five-second cleanup signal. See hook execution.

Optional active-runtime maintenance

A Compute interval queues another authorized preparation and activation for the selected revision. Repository access or standing approvals can schedule maintenance independently. The worker uses the earliest applicable interval. A failed maintenance observation leaves the selected revision in place and schedules another authorized pass. A newer deployment or an exclusive replacement can supersede an older pass.

Plugin startup warnings

A ready revision may report PLUGIN_INSTALL_FAILED or PLUGIN_AUTH_REQUIRED for an approved plugin only after disabling it and confirming the rest of the runtime is ready. The worker records warnings on successful deployment. See Kubernetes startup status.

Configuration

Select Compute under drivers.compute in Installation startup YAML. Restart API and worker after changes.

Setting Type Requirement Value, default, and constraints
id string Required Nonempty Driver identity; no default.
configuration object Required Implementation-defined settings; no shared fields or default.
package string Optional Installed package. Omit for bundled Kubernetes or SSH selection.

See selection and validation and the implementation references. Docker uses development environment settings instead. Agent Configuration and Harness bindings are separate inputs saved with each revision.

Limits

Compute uses the revision's recorded identity. Changing Drivers does not migrate it. Stop, retirement, and deletion require confirmation of Driver-owned cleanup. Check the feature matrix for topology, deletion support, and private gateway access.

Troubleshooting

Symptom First check Recovery and expected result
Production startup refuses the Driver Inspect the missing activation method, preflight error, or unsupported hook. Supply the reported capability and restart. A preflight warning alone does not block startup.
Deployment fails before a revision exists Check Harness authentication and admission errors. Correct the rejected setting or missing capability. An accepted request returns a revision ID.
A revision stays pending Check the pending reason, revision ID, and authenticated workload readiness. Fix the named dependency and confirm the worker selects and routes the expected revision.
Stop or retirement stalls Check credential revocation, hooks, and Sandbox cleanup. Retry after restoring access. Confirm the revision no longer accepts traffic and cleanup succeeds.
Credential creation was interrupted Read the Agent's stored transport status. Provision only missing credentials. A configured status establishes storage, not provider login.

Implementations

Search documentation