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.

Agent images

Each instance runs one of three official agent images, differing only in which browser is bundled:

Image	Browser	Docker Hub
clawforceone/agent-chrome	Chrome	hub.docker.com/r/clawforceone/agent-chrome
clawforceone/agent-chromium	Chromium	hub.docker.com/r/clawforceone/agent-chromium
clawforceone/agent-brave	Brave	hub.docker.com/r/clawforceone/agent-brave

All images except clawforceone/agent-chrome support AMD64 and ARM64 architectures. For production environments, prefer immutable tags or digests over latest. Use latest only for low-risk development or evaluation environments.

Every agent image comes with Homebrew pre-installed, so you can install additional packages inside any instance using brew install without extra setup.

Updating the agent image

When a new version of the agent image is published under the same tag (for example :latest), you can pull it without recreating the instance. Open the instance Settings tab, find the Agent Image field, and click Update. Clawforce 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.

For production rollouts, prefer moving instances between explicit image tags and use Backups before rollout. See Safe updates.

Note

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

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.

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

The colored dot next to each instance reflects live connection health independently of the container status.

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.

Kubernetes resources per instance

In Kubernetes mode, each instance creates and manages these resources in the clawforce 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: clawforce-{name}-homebrew (Homebrew) and clawforce-{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 Clawforce can reach the instance:

Dot color	State
Green	Connected
Yellow	Connecting or Reconnecting
Gray	Disconnected
Red	Failed

Open an instance to view full connection health and event history on the Overview tab.

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

Requests must not exceed their corresponding limits. Clawforce 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, Clawforce 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

Clawforce 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 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.

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.

Clawforce 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:

1. Whether the container is actually running (kubectl get pods -n clawforce)
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