Local development commands

Run these occ dev commands from a repository checkout to start and stop a local profile. They use local development configuration, not the remote connection or output options in the CLI command reference. Kubernetes is the supported local setup for deploying an Agent; follow Local Setup.

The CLI uses the nearest enclosing checkout identified by its OCE go.mod and compose.yaml. The Compose marker must be a regular file or a symlink to one. An absent marker allows the search to continue; an invalid or unresolvable marker stops these commands with the exact path to fix. If go.mod contains CRLF line endings, convert the file to LF and retry. These errors do not fall through to an outer checkout that could own a different stack.

occ dev check uses the current checkout's recorded state and loopback kubeconfig. It requires an available Agent Sandbox controller replica and prints bounded rollout diagnostics on failure. A serving controller remains sufficient while its replacement starts. It does not change workloads or prove Agent, model, or external-service readiness. Docker Compute is unsupported; a recorded stack with no Sandbox Driver reports that no OpenShell dependency was checked. The first-Agent helper runs this check before creating credentials or Agents.

In the Go Kubernetes helpers, a failed exclusive write removes its newly created output, including a partial key file. Existing targets stay unchanged. If removal also fails, the returned error includes both failures.

Compose global options, when needed, must follow --. Keep the cleanup command printed by startup so it selects the same profile and state directory. Without a Compute Driver selection, occ dev down reads the state directory (OCC_DEVELOPMENT_STATE_DIRECTORY, or the default under the temporary directory) and stops the Kubernetes stack recorded there; the Kubernetes control plane or a Sandbox Driver selection also selects that path. Compose options after --, or an absent state directory, stop the Docker profile instead. A state directory that exists but is unreadable or invalid stops cleanup with an error naming it; down never falls back to Docker in that case. Every checkout shares the default state directory, so when the recorded stack belongs to another checkout, unselected cleanup stops nothing and names that checkout: run occ dev down there, or select OCC_DEVELOPMENT_COMPUTE_DRIVER=kubernetes. The final line says which stack was stopped. The Kubernetes-only profile rejects Compose options. Use scripts/dev-up and scripts/dev-down as the common entry points for every profile; both resolve the same defaults. When scripts/dev-up fails on the Docker profile, occ dev up exits with the script's status (2 for a usage or configuration error) and prints nothing beyond the script's own message.

The Go Local Setup commands write [occ-dev-timing] records to the progress output for image builds, pulls, exports/imports, cluster creation, Compose startup, Helm installation, and Kubernetes readiness waits. Each record contains a fixed stage, elapsed milliseconds, and whether the command failed. It excludes arguments, environment values, and subprocess output. Concurrent commands overlap, so their durations must not be added as total startup time. These records do not change command cancellation, readiness checks, or failure handling.

When Kubernetes-only startup returns an error, [occ-dev-startup] reports the selected error's primary_stage, or unknown when no stage is identified. cleanup_failed records failure in tracked network-probe cleanup, registry detachment or startup rollback, including canceled sibling steps; it does not inventory every resource cleanup. parent_context_done says whether the parent context had ended when the CLI reported the result. It does not establish that cancellation initiated failure. Original errors and exit behavior are preserved. The record contains no raw errors, paths or subprocess output.

primary_stage=controller-image-import identifies a failure while preparing or importing the development controller image. Inspect the original CLI build or

or configured registry digest as applicable. Check a local registry's current published binding from the host. Node-side checks require the cluster and registry attachment to still exist; normal rollback removes them. The stage identifies the failed operation, not its underlying cause.

For primary_stage=routing, optional routing_operation identifies the selected failed step: manifest-download, gateway-api-readiness, manifest-filter, manifest-write, manifest-apply, controller-crd-readiness, controller-rollout, gateway-class-apply, gateway-class-readiness, or node-pod-cidr. When known, routing_controller is cert-manager or envoy-gateway; it is absent for the node Pod CIDR lookup. These fields use fixed labels, not error text. A canceled sibling or failed cleanup does not replace the selected failure's routing details. Records from older CLI versions can omit both fields.

Select a profile

Export the selection in the shell that runs startup. Unset OCC_DEVELOPMENT_COMPUTE_DRIVER selects Kubernetes Compute. An unset OCC_DEVELOPMENT_CONTROL_PLANE follows the Compute Driver: kubernetes on Kubernetes Compute and compose on Docker Compute. So OCC_DEVELOPMENT_COMPUTE_DRIVER=kubernetes OCC_DEVELOPMENT_SANDBOX_DRIVER=openshell alone starts the Kubernetes-only OpenShell profile, not the Compose control plane.

The Docker Compute preview runs OCC in Compose and cannot deploy Agents. Its ready text prints Compute Driver: Docker, and its service key is in a temporary directory outside the state directory. Stop it with OCC_DEVELOPMENT_COMPUTE_DRIVER=docker ./bin/occ dev down.