Managing instances

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.

Images

Each OpenClaw instance runs an agent image plus a separate Chrome session image. The agent image is always running; the Chrome session image is provisioned on demand the first time you use the browser and stopped after an idle period.

Agent image

Image	OpenClaw version	Purpose
claworc/openclaw	Latest published OpenClaw release	Runs OpenClaw, the terminal, and SSH
claworc/openclaw-stable	Latest version flagged stable by isitstable.com/openclaw	Same as above, but pinned to a community-vetted OpenClaw release

Both images are rebuilt nightly. Each build must pass the full Claworc test suite before it is pushed to Docker Hub, so a tag advancing to a new digest means the new version booted, ran OpenClaw, and survived the agent integration tests on both AMD64 and ARM64.

Tip

Which one should I use? Pick claworc/openclaw-stable if you want the safest path — it lags claworc/openclaw by however long the community needs to vet a new OpenClaw release on isitstable.com, so you skip the days when an upstream release introduces a regression. Use claworc/openclaw if you want new OpenClaw features the moment they ship.

Browser images

Image	Browser
glukw/claworc-browser-chrome	Chrome
glukw/claworc-browser-chromium	Chromium
glukw/claworc-browser-brave	Brave

All images except glukw/claworc-browser-chrome support AMD64 and ARM64 architectures. Use latest to always pull the most recent build.

Homebrew is preinstalled in the agent image, so you can install additional packages inside any instance using brew install without extra setup.

Note

Legacy images. Earlier instances ran the browser inside the agent container using glukw/openclaw-vnc-chrome, glukw/openclaw-vnc-chromium, or glukw/openclaw-vnc-brave. These images remain published and continue to work for instances created before the agent / browser split. New instances use the pair above. To switch an existing instance, see Migrating to on-demand browser.

Updating the agent and browser images

OpenClaw cannot be updated from inside a running container — the agent image must be rebuilt with the new version. Claworc handles this for you: the agent images on Docker Hub are rebuilt nightly with the latest OpenClaw release (or the latest stable release, for claworc/openclaw-stable), and clicking Update on an OpenClaw instance pulls the new image and restarts the container.

To update an OpenClaw instance, open its 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, browser profile) are preserved. The same Update button updates the browser image.

Note

The Update button only appears for admins, only when the OpenClaw 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 OpenClaw instance settings instead.

Tip

Recommended way to keep OpenClaw up to date. Set the agent image to claworc/openclaw-stable:latest and click Update on a regular cadence (for example, weekly). Each build of claworc/openclaw-stable pins the OpenClaw version flagged stable by isitstable.com/openclaw, so you get vetted upgrades without tracking releases yourself. Updating Claworc itself does not update the OpenClaw running inside existing OpenClaw instances — you still need to click Update on each one.

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 — runs OpenClaw and the terminal. Defaults to claworc/openclaw.
Browser image	Chrome session image — Chrome, Chromium, or Brave. Defaults to the value set in admin Settings.
Idle timeout (min)	How long the Chrome session stays running while idle before being stopped. Leave empty to inherit the global default (15 minutes). See Accessing instances.
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

Note

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

You can adjust CPU and memory after creation on the instance Settings tab. See Resources for details.

Note

CPU and memory defaults configured in Settings → Default Resource Limits are applied only when a new instance is created. Changing them later does not affect existing instances. To update resources on an existing instance, edit it on the instance Settings → Resources card.

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)

Caution

Delete is irreversible. All persistent data — Chrome profile, Homebrew packages, OpenClaw configuration, and clawdbot data — is permanently deleted.

Container security

Agent containers run with hardened defaults:

• No privileged mode. Containers use the Docker/Kubernetes default set of Linux capabilities. Seccomp is enabled.
• Privilege escalation blocked. SUID bits are removed from unnecessary binaries. sudo is available only for package management (apt-get).
• No kernel access. Mount, module loading, and /proc writes are blocked.

These settings apply automatically to all new and restarted instances in both Kubernetes and Docker modes.

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

Open an instance and switch to the Settings tab to see full connection health and event history.

Instance settings

Open any instance and switch to the Settings tab to view and edit its configuration. The tab is organized into several cards: Instance Details, Resources, Environment Variables, Enabled Models (admins only), SSH Connection Status, and Backups (admins only).

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 and browser images.
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

Requests must not exceed their corresponding limits. Claworc validates this before saving.

Resource changes are applied immediately to the running container — no restart is needed. Storage sizes (Homebrew and Home) are set at creation time and cannot be changed afterward.

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.

Note

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

This model lets you configure once globally and selectively customize where needed.

Each instance also has its own openclaw.json for agent behavior (model selection, tools, integrations).

See Configuration for the full reference, including per-instance override options and examples.

Backups

Admins can create compressed snapshots of any instance’s filesystem and restore them later. You can back up on demand from the instance detail page or set up scheduled backups from the Backups page in the sidebar.

See Backups for the full guide.

Shared folders

Shared folders let you mount a named volume into multiple instances so they can read and write the same files. Any authenticated user can create shared folders from the Shared Folders page in the sidebar.

See Shared folders for setup and limitations.

Enabling models for an instance

The Settings tab on each instance detail page includes an Enabled Models section (visible to admins). This controls which LLM providers and models the OpenClaw agent can use.

You can use global providers configured in Settings, or click Add provider to create a provider that belongs only to this instance. Instance-specific providers are useful when you need a dedicated API key or a provider that other instances should not access. See Configuration for details on both options.

Once providers are available, 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 Settings tab, the SSH Connection Status card 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:

1. Whether the container is actually running (kubectl get pods -n claworc)
2. Whether network policies allow egress from the control plane to agent pods on port 22
3. The connection event log for the specific failure reason