| tags |
|
|
|---|---|---|
| last_verified | 2026-11-18 |
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.
- Linux or macOS, with commands run from the OCE repository root.
- Docker Engine or Podman, k3d, kubectl, Helm, jq, Bash, and Python 3.
- Go 1.27.3, pnpm 11.15.1, and Node.js
>=24.22.1 <26 || >=26.12.1. - About 20 GB of free container-engine storage for the first build; on macOS, this must be inside the Docker or Podman VM.
- Free local ports
3000(API),8443(browser console), and6443(Kubernetes), or configured alternatives. - An OpenAI API key to deploy an Agent; no model credential is needed to install the platform.
Check container storage with podman machine ssh df -h /var or
docker run --rm alpine df -h /. Insufficient space causes startup to fail and
roll back the cluster. Startup also checks the ports and names any container
holding one. To stop an earlier Docker-compatible occ dev up stack, run
OCC_DEVELOPMENT_COMPUTE_DRIVER=docker ./bin/occ dev down.
By default, startup builds this checkout. To use published images, first select the published pair.
go build -trimpath -o bin/occ ./cmd/occ
./bin/occ dev upThe 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.
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.
Use the API URL and service-key file printed at startup. On Linux, the defaults are usually:
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 getOn 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.
./bin/occ namespace listExpect 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.
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.
set -euo pipefail
export 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_NAMESPACEContinue 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.
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:
./bin/occ dev downThis 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.
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:
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.
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.
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.