Managing instances

Overview

Each instance is an isolated, secured AI agent running in its own container. You pick the agent runtime — OpenClaw, Hermes, or NanoClaw — when you create the instance, and you can run any mix of them side by side. Each instance gets its own browser, terminal, storage, and configuration.

Agent types

Claworc talks to every runtime through the same interface, so most features work identically regardless of the agent type: terminal, file browser, logs, chat, webhooks, skills, connections, backups, shared folders, the LLM gateway, and image updates.

The differences are:

	OpenClaw	Hermes	NanoClaw
Default image	claworc/openclaw	claworc/hermes	claworc/nanoclaw
Config file (Config tab)	openclaw.json — saving restarts the agent	config.yaml — applied without a restart	container.json — saving restarts the agent
Skills folder	~/.openclaw/skills/	~/.hermes/skills/	~/.claude/skills/
Workspace	~/.openclaw/workspace	~/hermes-workspace	~/workspace
LLM providers	Any enabled provider	One provider — the one serving the default model	Anthropic models only
Agent controls the browser	Yes	No — the browser is for you only	No — the browser is for you only
Control UI button	Yes	—	—
Homebrew	Preinstalled	—	—
sudo for apt-get	Yes	—	Yes

~ is the agent’s home directory, /home/claworc.

Custom lets you run your own agent image. The image must implement the Claworc agent shim — the small set of scripts under /opt/claworc/shim/ that Claworc calls over SSH to chat with the agent, configure models, and install skills. Features appear or disappear based on the capabilities the image declares.

Note

The agent type is chosen when the instance is created and cannot be changed from the dashboard afterwards. Clone keeps the agent type of the source instance.

Images

We prepared secured agent images that do not expose anything to the Internet. Every image includes Python for skills and automation; the OpenClaw and NanoClaw images add Node.js, and the OpenClaw images also ship Homebrew.

Image	Runtime 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
claworc/hermes	Pinned Hermes release	Runs Hermes, the terminal, and SSH
claworc/nanoclaw	Pinned NanoClaw release	Runs NanoClaw (on Claude Code), the terminal, and SSH

All 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 the agent, and integration tests pass on both AMD64 and ARM64 architectures.

Admins can change the default image for each agent type under Settings → Agent Defaults (OpenClaw Image, Hermes Image, NanoClaw Image, Custom Agent Image).

Tip

Which OpenClaw image 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. Hermes and NanoClaw have a single image each.

Browser images

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

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

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.

Updating the agent and browser images

Agent runtimes 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, and clicking Update on an instance pulls the new image and restarts the container.

To update an 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 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.

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 agent running inside existing 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
Team	Team the instance belongs to
Display Name	Human-readable name shown in the dashboard
Agent Type	OpenClaw, Hermes, NanoClaw, or Custom. See Agent types. Defaults to OpenClaw; the form remembers your last choice.
Agent Image	Shown only for Custom — your agent image (e.g. myregistry/my-agent:latest). Other types use the default image from Settings → Agent Defaults.
Timezone Override	IANA timezone for the instance. Leave empty for the global default.
Enabled Models	Which LLM models the agent can use, and the default model. See Assign models.
Brave API Key	Key for web search; leave empty to use the global key
CPU / Memory Request and Limit	Resources allocated to the container (e.g., 1.0 CPU, 2Gi memory)
Homebrew / Home Storage	Persistent volume sizes; cannot be changed after creation
Environment Variables	Extra variables injected into the agent container
Browser Image Override	Browser session image — Chrome, Chromium, or Brave. Defaults to the value set in admin Settings.
Resolution Override / User-Agent Override	Browser display resolution and User-Agent. Leave empty for the global defaults.

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, home directory, agent configuration and workspace, and Homebrew packages — 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. On OpenClaw and NanoClaw, sudo is available only for package management (apt-get); Hermes images have no sudo at all.
• 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 agent config file for agent behavior (model selection, tools, integrations), editable from the Config tab: openclaw.json for OpenClaw, config.yaml for Hermes, and container.json for NanoClaw.

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 agent can use. Hermes uses a single provider and NanoClaw uses Anthropic models only — see Agent types.

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