Set up OpenClaw Enterprise locally

Start an OpenClaw Enterprise installation that can deploy Agents on your machine. The OpenClaw Control Plane (OCC), PostgreSQL, and Agent workloads run in a local Kubernetes cluster created with k3d. This setup is for development and uses loopback addresses. occ dev up starts this Kubernetes-only profile when no profile is selected. Other local profiles need an explicit selection and have fewer capabilities. To install OCC itself in a cluster you already operate, use Kubernetes Setup.

For local OpenShell with native Git or Codex plugins, start with Setup OCE on local k3d. The instructions below use the profile without OpenShell.

Before you start

Run the commands below from the repository root on Linux or macOS. You need:

Docker Engine, k3d, kubectl, Helm, jq, Bash, and Python 3. Podman users should first check the local Kubernetes requirements.
The Go version in go.mod, Node.js 24.22.1 or later, and the pnpm version pinned in package.json.
About 20 GB of free container-engine storage for the first build. On macOS that space is inside the Podman or Docker virtual machine rather than on your host disk; check it with podman machine ssh df -h /var, or for Docker Desktop with docker run --rm alpine df -h /. Without it, startup fails late with no space left on device and rolls back the cluster.
Free local ports 3000 for the API, 8443 for the browser console, and 6443 for Kubernetes. Startup checks them first and names the container that holds a port. If that is a Docker-compatible stack from an earlier occ dev up, stop it with OCC_DEVELOPMENT_COMPUTE_DRIVER=docker ./bin/occ dev down. Otherwise, override OPENCLAW_DEV_PORT, OCC_DEVELOPMENT_BROWSER_PORT, or OCC_DEVELOPMENT_KUBERNETES_API_PORT; see development settings.

You do not need a model credential to install the platform. Have an OpenAI API key available when you continue to deploy an Agent.

Start the local stack

By default, startup builds this checkout. To use published images, first select the published pair.

bash

go build -trimpath -o bin/occ ./cmd/occ./bin/occ dev up

The first start builds and imports both images unless you selected published images. With no build cache, the runtime build first compiles Node.js from source, which takes 15-60 minutes or longer depending on CPUs and memory; later starts reuse the cache. Wait for OpenClaw Enterprise development stack is ready. and Deployment: Kubernetes only. The command prints the browser console URL and CA certificate, then the API URL, Installation ID, service-key file, administrator password file, kubeconfig, Kubernetes context, and cleanup command. Keep this output. The service-key and password files are administrator credentials and must remain on your machine.

If startup stalls on cert-manager, follow local startup troubleshooting.

none selects no OpenShell Sandbox Driver. Startup still checks the Codex sandbox on the node. If that check fails, follow local Codex sandbox troubleshooting.

Open the platform console

Trust the printed public browser-ca.crt on the computer running your browser, then open the printed HTTPS console URL. Startup generates a local CA; it does not install it in a trust store. Without that step, the browser can report NET::ERR_CERT_AUTHORITY_INVALID even when the stack is ready. Follow local browser CA trust and verification for macOS instructions, certificate checks, and removal. The CA can vouch only for that installation's console and Agent hosts, and startup discards its private key. Keep the entire state directory private.

Open the printed URL on the machine that ran ./bin/occ dev up. Kubernetes-only mode publishes the console port on that machine's loopback, and the hostname ends in .localhost, so another computer resolves it to itself. When the browser is on a different computer, follow Open the console from another machine.

Sign in as admin@development.openclaw.invalid using the generated password in the administrator password file printed by startup. That file and the service key are private credentials; keep them on your machine. The separate HTTP API URL remains available on loopback for CLI service-key requests.

After signing in, continue with the CLI access check below. For console-created Agents later, the default Namespace includes Standard Codex and Standard OpenClaw Presets; follow the Standard Codex prerequisites before using that Preset.

Read the Installation with the bootstrap service key

Use the API URL and service-key file printed at startup. On Linux, the defaults are usually:

bash

export OCC_URL='http://127.0.0.1:3000'export OCC_SERVICE_KEY_FILE='/tmp/openclaw-development/initial-admin-service-key.json'./bin/occ installation get

On macOS or with a custom state directory, use the printed key path instead. Expect an Installation row with the ID printed at startup. The CLI reads the key from the file; do not pass the credential value as an argument or share it.

Find the initial Namespace

bash

./bin/occ namespace list

Expect one Namespace named default. Wait for STATUS to become ready and note its server-assigned ID. This platform Namespace is separate from Kubernetes' built-in default namespace.

Deploy an Agent

Prepare the shared deployment guide's operator variables in Bash from this checkout. Keep OCC_URL and OCC_SERVICE_KEY_FILE from the authenticated check above. The launcher already configured this installation's private routing, Envoy source CIDRs, and tenant RoleBindings; keep those grants instead of applying the production examples with different release and ServiceAccount names. Use this shell and the bootstrap service key as the operator session; this local installation needs no separate operator shell or service principal.

bash

set -euo pipefailexport PATH="$(pwd)/bin:$PATH"LOCAL_STATE=${OCC_DEVELOPMENT_STATE_DIRECTORY:-$(node -p 'require("node:path").join(require("node:os").tmpdir(), "openclaw-development")')}export KUBECONFIG_FILE="$LOCAL_STATE/kubeconfig"export CONTEXT="k3d-$(jq -er .cluster "$LOCAL_STATE/state.json")"test "$(kubectl --kubeconfig "$KUBECONFIG_FILE" config current-context)" = "$CONTEXT"NAMESPACE_ID=$(occ namespace list --output json |  jq -er '[.[]|select(.name=="default" and .status=="ready")]|select(length==1)|first.id')export NAMESPACE_ID OCC_NAMESPACE="$NAMESPACE_ID"TENANT_NAMESPACE=$(kubectl --kubeconfig "$KUBECONFIG_FILE" --context "$CONTEXT" \  get namespaces -l "openclaw.dev/namespace=$NAMESPACE_ID" -o json |  jq -er '.items|select(length==1)|first.metadata.name')export TENANT_NAMESPACE

Continue at Prepare each Agent, select the embedded OpenClaw example, supply its model credential, and complete the deployment and model-response checks. Start at that section; do not repeat the production installation or Namespace RoleBinding steps.

Clean up and stop

When you are finished, run the cleanup command printed by startup. In any shell from this checkout, occ dev down stops the Kubernetes stack recorded in the default state directory:

bash

./bin/occ dev down

This deletes the local cluster, database, Agents, stored credentials, and audit history. If cleanup fails, restore access to the container engine and run the same command again. See local Kubernetes cleanup if you used a custom state directory or service-key location.

Optional: use matching published images

Follow Use published controller and runtime images to pull the latest or stable pair and select its matching source checkout. Keep its resolved image variables in the shell used for startup:

bash

export OCC_DEVELOPMENT_CONTROLLER_IMAGE="${CONTROLLER_IMAGE:?Select the published controller image first}"export OCC_KUBERNETES_RUNTIME_IMAGE="${RUNTIME_IMAGE:?Select the published runtime image first}"

Return to Start the local stack in that checkout. To build from source instead, unset both variables before startup.

Workspace access

Local setup configures private gateway routing. After deploying an Agent, verify its workspace files. Dedicated Agents also need RWO workspace storage; the stock local-path StorageClass supports the Harness-only claim.

Open an Agent's native admin UI

Follow local native admin setup. It requires exact-Agent administer permission and the Agent's native access policy. The first-Agent helper can opt in a new Agent when Local setup uses the Compose control plane with Kubernetes Compute and OpenShell; other profiles use a separate console-managed Agent.