UserSwarm Lifecycle

Every Crawbl user gets their own isolated ZeroClaw runtime.

In plain language, UserSwarm is the system's "make this user's private swarm exist" record. The platform writes that record, and the cluster turns it into the real runtime pod, storage, and services needed for that user.

Technically, the platform manages this through a Kubernetes custom resource called UserSwarm. A Kubernetes operator watches these resources and reconciles the full runtime environment: StatefulSet, persistent storage, services, and configuration.

One UserSwarm becomes one ZeroClaw pod. That pod hosts the user's base Manager agent plus any native delegate agents defined in the generated config.toml.

State Machine

A UserSwarm progresses through a set of phases tracked in status.phase.

These phases describe where a user's runtime is in the provisioning process.

Click diagram to zoom

What Happens at Each Phase

The operator writes these phase values into the UserSwarm status:

1

Step 1

Progressing

The operator has determined the desired child resources and is still converging them.

In practice, this usually means the pod identity, configuration, storage, services, or workload are not ready yet.

2

Step 2

Ready

The workload has at least one ready replica.

At this point the runtime pod is up and the Ready condition is true.

3

Step 3

Suspended

The runtime has been suspended, scaling the workload to zero replicas.

Storage and services stay in place so the runtime can be resumed later without losing state.

4

Step 4

Deleting

The UserSwarm is being torn down.

The operator removes child resources and waits until all of them are gone.

5

Step 5

Error

The operator could not build the desired runtime state.

The usual cause is that bootstrap config or ZeroClaw config could not be rendered correctly.

The backend also derives a user-facing runtime.status from the phase:

• ready when the runtime is verified
• provisioning for Progressing, Deleting, or an empty phase
• offline for Suspended
• failed for Error

What Gets Created

For each UserSwarm, the operator creates these child resources in a dedicated runtime namespace:

1

Step 1

ServiceAccount

Identity for the runtime pod.

2

Step 2

ConfigMap

Bootstrap files mounted into the runtime: personality files, identity files, tool guidance, and per-agent skill entries that an init container later expands onto durable storage.

3

Step 3

PersistentVolumeClaim

Durable storage for user data, sessions, memory, and extracted per-agent skill directories.

4

Step 4

Headless Service

Stable DNS identity for the workload pod.

5

Step 5

ClusterIP Service

Internal-only service the orchestrator calls to reach the runtime.

6

Step 6

StatefulSet

The ZeroClaw runtime pod itself.

7

Step 7

Backup Job

Optional backup job when backup settings are configured.

If you are new to Kubernetes, the main idea is that one high-level record turns into the smaller cluster resources that actually make the runtime usable.

Native Runtime Shape

The important current runtime detail is that the pod is no longer just "one generic agent process."

Each UserSwarm pod starts ZeroClaw with:

• a base Manager identity built from SOUL.md, IDENTITY.md, and TOOLS.md
• runtime defaults from the root of config.toml
• native delegate agents under [agents.<slug>]
• per-agent skill files extracted onto the PVC at workspace/agents/<slug>/

That means one Kubernetes runtime can host a small real swarm without the orchestrator having to rebuild agent identity on every request.

Cleanup

When a UserSwarm is deleted, the operator removes all child resources. It continues reconciling until all observed children are gone, then completes the deletion.

This explicit cleanup step is what tears the runtime down cleanly.

What's Next

See the ZeroClaw Overview to learn what runs inside the agent pod.