Overview
Each instance is an isolated, secured OpenClaw agent running in its own container.
You can run many instances concurrently — each gets its own browser, terminal, storage, and configuration.
Agent images
Each instance runs one of three official agent images, differing only in which browser is bundled:
All images except glukw/openclaw-vnc-chrome support AMD64 and ARM64 architectures.
Use latest to always pull the most recent build.
Updating the agent image
When a new version of the agent image is published under the same tag (e.g. :latest), you can pull it without recreating the instance. Open the instance Settings tab, find the Agent Image field, and click Update. Claworc pulls the latest version of the tag, stops the container, and restarts it with the new image. Persistent volumes (home directory, Homebrew packages) are preserved.
The Update button only appears for admins, only when the instance is running, and only for tag-based images (e.g. :latest). Digest-pinned images (@sha256:...) cannot be updated this way — change the image reference in the instance settings instead.
Creating an instance
Click New instance on the dashboard and fill in the form:
| Field | Description |
|---|
| Display name | Human-readable name shown in the dashboard |
| Image | Agent image to use — choose the browser variant for this instance |
| CPU limit | Maximum CPU cores allocated (e.g., 1.0) |
| Memory limit | Maximum RAM allocated (e.g., 2Gi) |
| API key override | Instance-specific API key; overrides the global key if set |
The display name is converted to a Kubernetes-safe name automatically: lowercased, spaces replaced with hyphens,
prefixed with bot-, truncated to 63 characters. Renaming an instance does not affect its underlying resources.
Resource sizing
A rough guide based on typical workloads:
| Workload | CPU | Memory |
|---|
| Light (simple tasks, browser will be slow) | 500m | 1Gi |
| Moderate (collaboration with the browser) | 1.0 | 2Gi |
| Heavy (multiple tabs, data analysis) | 2.0 | 4Gi |
Instance status
Each instance shows a status from the orchestrator (Kubernetes or Docker), alongside a live connection indicator:
| Status | Meaning |
|---|
| Creating | Container is being provisioned or starting up |
| Running | Container is running |
| Restarting | Restart in progress |
| Stopping | Stop in progress |
| Stopped | Container is stopped |
| Error | Container exited unexpectedly |
| Failed | Container stopped after an error |
Starting, stopping, and restarting
From the dashboard, click the ⋮ menu next to any instance:
- Start — starts a stopped container
- Stop — stops a running container gracefully
- Restart — stops then starts the container; useful when the agent is stuck
- Clone — copies all settings and files into a new instance
- Delete — permanently removes the instance and all its data (PVCs in Kubernetes, volumes in Docker)
Delete is irreversible. All persistent data — Chrome profile, Homebrew packages, OpenClaw configuration, and clawdbot data — is permanently deleted.
Kubernetes resources per instance
In Kubernetes mode, each instance creates and manages these resources in the claworc namespace:
| Resource | Name | Purpose |
|---|
Deployment | bot-{name} | Runs the agent container |
PVC | bot-{name}-homebrew | Homebrew packages |
PVC | bot-{name}-home | Home directory — OpenClaw config, browser profile, personal files |
Docker resources per instance
In Docker mode, each instance creates:
- One container (named
bot-{name})
- Two named volumes:
claworc-{name}-homebrew (Homebrew) and claworc-{name}-home (home directory)
- One published SSH port on
127.0.0.1 with a randomly assigned host port
Connection status
Each instance row shows a small colored dot indicating whether Claworc can reach the instance:
| Dot color | State |
|---|
| Green | Connected |
| Yellow | Connecting or Reconnecting |
| Gray | Disconnected |
| Red | Failed |
Instance settings
Open any instance and switch to the Settings tab to view and edit its configuration. Settings are organized into two cards: Instance Details and Resources.
Instance details
The Instance Details card shows the display name, agent image, VNC resolution, timezone, user-agent, and timestamps. Many of these fields are editable inline — click Edit next to a field, make your change, and click Save.
| Field | Who can edit | Notes |
|---|
| Display Name | Admins | Renaming does not affect the underlying container or Kubernetes resource names. |
| Agent Image | Read-only (use Update to pull latest) | See Updating the agent image. |
| VNC Resolution | Admins | Format: WIDTHxHEIGHT (e.g. 1920x1080). Leave empty for the global default. Requires a restart to take effect. |
| Timezone | All users | IANA timezone string (e.g. America/New_York). Leave empty for the global default. Requires a restart to take effect. |
| User-Agent | All users | Custom Chromium User-Agent string. Leave empty for the global default. Requires a restart to take effect. |
Resources
The Resources card displays CPU and memory requests and limits, plus storage sizes. Admins can click Edit to change CPU and memory values for a running instance.
| Field | Format | Example |
|---|
| CPU Request | Millicores or decimal cores | 500m or 0.5 |
| CPU Limit | Millicores or decimal cores | 2000m or 2 |
| Memory Request | Mebibytes or gibibytes | 512Mi or 1Gi |
| Memory Limit | Mebibytes or gibibytes | 4Gi |
Live resource usage
When viewing the Settings tab of a running instance, Claworc displays live CPU and memory usage next to the limit values. Usage is shown as an absolute value and a percentage of the configured limit (e.g. using 312m / 16%). Stats refresh automatically every 10 seconds.
In Kubernetes mode, live resource stats require the metrics-server to be installed in the cluster. Without it, usage data is unavailable. Configuration hierarchy
Claworc separates configuration into two levels: global defaults that apply to every instance, and per-instance overrides that apply to one instance only. Anything not overridden at the instance level is inherited from the global defaults automatically.
| Level | Where to set it | Scope |
|---|
| Global default | Settings | All instances with no override |
| Per-instance override | Instance detail page | That instance only |
openclaw.json for agent behavior (model selection, tools, integrations).
See Configuration for the full reference, including per-instance override options and examples.
Enabling models for an instance
The Overview tab on each instance detail page includes an Enabled Models section (visible to admins). This controls which LLM providers and models the agent can use.
Before you can enable models on an instance, configure at least one provider in Settings. See Configuration for how to add providers and manage API keys.
Once providers are configured, open the instance, click Edit next to Enabled Models, and check the models you want to make available. You can also set a Default model — the model the agent uses unless instructed otherwise.
Claworc pushes the model configuration to the container over SSH in the background. A toast notification confirms when the update is complete.
Troubleshooting an instance
On the instance Overview tab, the troubleshoot panel lets you:
- Run a connectivity test
- Manually reconnect
- View the SSH key fingerprint used for this instance
If an instance is stuck in Reconnecting, check:
- Whether the container is actually running (
kubectl get pods -n claworc)
- Whether network policies allow egress from the control plane to agent pods on port 22
- The connection event log for the specific failure reason
