ClawManager

https://github.com/yuan-lab-llm/clawmanager
Admin
ClawManager is a Kubernetes-native control plane for AI agent instance management, featuring...
Tokens:63,780
Snippets:744
Trust Score:5.2
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Perform first-time local E2E setup

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/specs/2026-06-03-clawmanager-v2-e2e-design.md

Install dependencies and the required browser engine before running tests for the first time.

```bash
cd e2e
npm ci
npx playwright install chromium
```

--------------------------------

### Install dependencies

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/backend/README.md

Run this command to install the necessary project dependencies.

```bash
make deps
```

--------------------------------

### Start the server

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/backend/README.md

Launches the backend server application.

```bash
make run
```

--------------------------------

### Development Server

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/frontend/README.md

Starts the development server for local testing.

```bash
npm run dev
```

--------------------------------

### Configure and start RuntimeScheduler

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Initialize Redis services and the scheduler, then start the scheduler if enabled in the configuration.

```go
platformRedis, err := services.NewPlatformRedisClient(cfg.Runtime.RedisURL)
if err != nil {
	log.Printf("platform redis disabled: %v", err)
}
runtimeEvents := services.NewRuntimeEventService(platformRedis)
agentClient := services.NewRuntimeAgentClient(cfg.Runtime.AgentControlToken)
leader := services.NewRuntimeLeaderService(k8sClient, cfg.Runtime.Namespace, cfg.Runtime.BackendReplicaID)
runtimeDeployments := k8s.NewRuntimeDeploymentService(k8sClient)
runtimeScheduler := services.NewRuntimeScheduler(instanceRepo, runtimePodRepo, bindingRepo, rolloutRepo, agentClient, runtimeEvents, leader, runtimeDeployments, cfg.Runtime.SchedulerTick)
if cfg.Runtime.SchedulerEnabled {
	runtimeScheduler.Start(ctx)
}
```

--------------------------------

### Environment Configuration

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/frontend/README.md

Example content for the .env.development file.

```text
VITE_API_URL=http://localhost:9001/api/v1
```

--------------------------------

### Install k3s

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Commands to install k3s on standard or mainland China networks.

```bash
curl -sfL https://get.k3s.io | sh -
```

```bash
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh |   INSTALL_K3S_MIRROR=cn sh -
```

--------------------------------

### Commit Configuration and Setup

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-03-clawmanager-v2-e2e-p0.md

Stage and commit the newly created Playwright configuration and setup files to the repository.

```bash
git add e2e/playwright.config.ts e2e/setup
git commit -m "test: configure e2e playwright setup"
```

--------------------------------

### Start MySQL with Docker

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/backend/README.md

Initializes the MySQL database container using Docker.

```bash
make docker-up
```

--------------------------------

### Check for Existing Installation

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/cluster/README.md

Verify that no previous Longhorn or ClawManager resources exist before starting a fresh install.

```sh
kubectl get ns longhorn-system clawmanager-system clawmanager-user-1 --ignore-not-found
kubectl get sc longhorn longhorn-rwx --ignore-not-found
kubectl get crd | grep longhorn.io || true
```

--------------------------------

### Check Installation State

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k8s/single-node/README.md

Verify that no existing ClawManager resources are present before proceeding with a fresh installation.

```sh
kubectl get ns clawmanager-system clawmanager-user-1 --ignore-not-found
kubectl get pv | grep clawmanager || true
kubectl get pvc -A | grep clawmanager || true
```

--------------------------------

### Start Command Execution

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Notify the ClawManager that command execution has begun.

```http
POST {CLAWMANAGER_AGENT_BASE_URL}/api/v1/agent/commands/{id}/start
Authorization: Bearer {session_token}
Content-Type: application/json
```

```json
{
  "agent_id": "hermes-123-main",
  "started_at": "2026-04-27T14:31:00Z"
}
```

--------------------------------

### Initialize E2E Test Environment

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/e2e/README.md

Install project dependencies and the required Playwright browser binaries.

```bash
npm ci
npx playwright install chromium
```

--------------------------------

### Prepare Nodes for Longhorn

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/cluster/README.md

Install necessary storage and networking packages on cluster nodes.

```sh
apt-get update
apt-get install -y open-iscsi nfs-common cryptsetup dmsetup
systemctl enable --now iscsid || systemctl enable --now open-iscsi
```

```sh
yum install -y iscsi-initiator-utils nfs-utils cryptsetup device-mapper
systemctl enable --now iscsid
```

```sh
command -v iscsiadm
command -v mount.nfs
command -v mount.nfs4
systemctl is-active iscsid || systemctl is-active open-iscsi
```

--------------------------------

### Prepare Nodes for Longhorn (RHEL/CentOS/Rocky/Alma)

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k8s/cluster/README.md

Install required storage packages on RHEL-based distributions.

```sh
yum install -y iscsi-initiator-utils nfs-utils cryptsetup device-mapper
systemctl enable --now iscsid
```

--------------------------------

### Prepare Nodes for Longhorn (Ubuntu/Debian)

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k8s/cluster/README.md

Install required storage packages on Ubuntu or Debian nodes.

```sh
apt-get update
apt-get install -y open-iscsi nfs-common cryptsetup dmsetup
systemctl enable --now iscsid || systemctl enable --now open-iscsi
```

--------------------------------

### Manage V2 Instance Lifecycle

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Implements Start and Stop operations for V2 instances, delegating to legacy methods for non-V2 types.

```go
func (s *instanceService) Start(ctx context.Context, userID int, instanceID int) error {
	instance, err := s.mustOwnInstance(ctx, userID, instanceID)
	if err != nil {
		return err
	}
	if _, ok := NormalizeV2RuntimeType(instance.Type); ok {
		return s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "creating", instance.RuntimeGeneration+1, nil)
	}
	return s.startLegacy(ctx, instance)
}

func (s *instanceService) Stop(ctx context.Context, userID int, instanceID int) error {
	instance, err := s.mustOwnInstance(ctx, userID, instanceID)
	if err != nil {
		return err
	}
	if _, ok := NormalizeV2RuntimeType(instance.Type); ok {
		binding, err := s.bindingRepo.GetByInstanceID(ctx, instance.ID)
		if err == nil {
			pod, podErr := s.runtimePodRepo.GetByID(ctx, binding.RuntimePodID)
			if podErr == nil && pod.AgentEndpoint != nil {
				_ = s.agentClient.DeleteGateway(ctx, *pod.AgentEndpoint, binding.GatewayID)
			}
			_ = s.bindingRepo.DeleteByInstanceID(ctx, instance.ID)
			_ = s.runtimePodRepo.ReleaseSlot(ctx, binding.RuntimePodID)
		}
		return s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "stopped", instance.RuntimeGeneration, nil)
	}
	return s.stopLegacy(ctx, instance)
}
```

--------------------------------

### Start MySQL Service via PowerShell

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-03-clawmanager-v2-e2e-p0.md

Use this command to initialize the MySQL container for E2E testing in a PowerShell environment.

```powershell
docker compose -f docker/docker-compose.e2e.yml up -d mysql
```

--------------------------------

### Install Lucide React dependency

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Run these commands within the frontend directory to add the icon library.

```powershell
cd frontend
npm install lucide-react
cd ..
```

--------------------------------

### Smoke Test Frontend

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Start the frontend development server for local smoke testing.

```powershell
cd frontend
npm run dev -- --host 127.0.0.1
```

--------------------------------

### POST /api/v1/agent/commands/{id}/start

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Notifies the ClawManager that the agent has started executing a specific command.

```APIDOC
## POST /api/v1/agent/commands/{id}/start

### Description
Signals the start of command execution.

### Method
POST

### Endpoint
{CLAWMANAGER_AGENT_BASE_URL}/api/v1/agent/commands/{id}/start

### Request Body
- **agent_id** (string) - Required - Current agent ID.
- **started_at** (string) - Required - ISO 8601 timestamp of start time.
```

--------------------------------

### Configure Skill Root Directory

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

The default location for installed skills within the instance.

```text
/config/.hermes/skills
```

--------------------------------

### Manage k3s service

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Commands to verify the k3s service status and enable it to start on boot.

```bash
sudo systemctl status k3s --no-pager
sudo systemctl enable k3s
```

--------------------------------

### Identify Frontend Port

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Example output showing the NodePort mapping for the frontend service.

```text
443:30443/TCP
```

--------------------------------

### Zip Structure Example

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

The required directory structure for skill packages, containing exactly one top-level directory.

```text
hermes-weather/
  skill.json
  main.py
  README.md
```

--------------------------------

### Download Skill Version Package Request

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

HTTP request to download a specific skill version package during the installation process.

```http
GET {CLAWMANAGER_AGENT_BASE_URL}/api/v1/agent/skills/versions/{skill_version}/download
Authorization: Bearer {session_token}
```

--------------------------------

### Download Skill Package via HTTP

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Use this GET request to download a skill zip package when a version identifier is provided.

```http
GET {CLAWMANAGER_AGENT_BASE_URL}/api/v1/agent/skills/versions/{external_version_id}/download
Authorization: Bearer {session_token}
```

--------------------------------

### Initialize repositories in main.go

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Instantiate runtime-related repositories using the existing database session.

```go
runtimePodRepo := repository.NewRuntimePodRepository(sess)
bindingRepo := repository.NewInstanceRuntimeBindingRepository(sess)
rolloutRepo := repository.NewRuntimeRolloutRepository(sess)
```

--------------------------------

### Create V2 Instance Logic

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Handles the creation of V2 instances by setting runtime-specific parameters and initializing workspace paths.

```go
runtimeType, isV2 := NormalizeV2RuntimeType(req.Type)
if isV2 {
	instance := &models.Instance{
		UserID:            userID,
		Name:              strings.TrimSpace(req.Name),
		Description:       normalizeStringPtr(req.Description),
		Type:              runtimeType,
		RuntimeType:       "gateway",
		Status:            "creating",
		CPUCores:          req.CPUCores,
		MemoryGB:          req.MemoryGB,
		DiskGB:            req.DiskGB,
		StorageClass:      strings.TrimSpace(req.StorageClass),
		MountPath:         "/workspaces",
		RuntimeGeneration: 1,
	}
	if err := s.instanceRepo.Create(ctx, instance); err != nil {
		return nil, err
	}
	workspacePath := RuntimeWorkspacePath(runtimeType, userID, instance.ID)
	if err := os.MkdirAll(workspacePath, 0750); err != nil {
		return nil, err
	}
	if err := s.instanceRepo.SetWorkspacePath(ctx, instance.ID, workspacePath); err != nil {
		return nil, err
	}
	instance.WorkspacePath = &workspacePath
	return instance, nil
}
```

--------------------------------

### GET /gateways

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md

Lists all gateways managed by the agent.

```APIDOC
## GET /gateways

### Description
Lists all gateways managed by the agent.

### Method
GET

### Endpoint
/gateways
```

--------------------------------

### Clone and enter project directory

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Download the ClawManager source code from the repository.

```bash
git clone https://github.com/Yuan-lab-LLM/ClawManager.git
cd ClawManager
```

--------------------------------

### GET /healthz

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md

Checks the health status of the agent.

```APIDOC
## GET /healthz

### Description
Returns the health status of the agent.

### Method
GET

### Endpoint
/healthz
```

--------------------------------

### Initialize Database for ARM64 Deployment

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/arm64-deployment_en.md

Manually create the database user and schema required for the initial deployment.

```bash
kubectl exec -it -n clawmanager-system mysql-xxx -- mysql -u root

# Execute in MySQL
CREATE USER IF NOT EXISTS 'clawmanager'@'%' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON *.* TO 'clawmanager'@'%' WITH GRANT OPTION;
CREATE DATABASE IF NOT EXISTS clawmanager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
FLUSH PRIVILEGES;
```

--------------------------------

### List Recommended Deployment Manifests

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Paths to the recommended YAML configuration files for various Kubernetes deployment scenarios.

```bash
deployments/k3s/single-node/clawmanager.yaml
deployments/k3s/cluster/clawmanager.yaml
deployments/k8s/single-node/clawmanager.yaml
deployments/k8s/cluster/clawmanager.yaml
```

--------------------------------

### GET /capacity

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md

Retrieves the current capacity information of the agent.

```APIDOC
## GET /capacity

### Description
Retrieves the current capacity information of the agent.

### Method
GET

### Endpoint
/capacity
```

--------------------------------

### Verify Deployment Status

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/single-node/README.md

Check the status of PVCs and deployments after installation.

```sh
kubectl -n clawmanager-system get pvc
kubectl -n clawmanager-system rollout status deployment/clawmanager-app --timeout=15m
kubectl -n clawmanager-system rollout status deployment/openclaw-runtime --timeout=15m
kubectl -n clawmanager-system rollout status deployment/hermes-runtime --timeout=15m
kubectl -n clawmanager-system get deploy,pod,pvc -o wide
```

--------------------------------

### GET http://{pod_ip}:19090/v1/metrics

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Retrieves metrics from the agent.

```APIDOC
## GET http://{pod_ip}:19090/v1/metrics

### Description
Retrieves metrics from the agent.

### Method
GET

### Endpoint
http://{pod_ip}:19090/v1/metrics
```

--------------------------------

### Production Build

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/frontend/README.md

Compiles the application for production deployment.

```bash
npm run build
```

--------------------------------

### GET http://{pod_ip}:19090/v1/health

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Checks the health of the agent.

```APIDOC
## GET http://{pod_ip}:19090/v1/health

### Description
Checks the health of the agent.

### Method
GET

### Endpoint
http://{pod_ip}:19090/v1/health
```

--------------------------------

### GET /api/v1/agent/commands/next

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Polls for the next pending command assigned to the agent.

```APIDOC
## GET /api/v1/agent/commands/next

### Description
Polls the ClawManager for the next pending command. If the returned command is null, no action is required.

### Method
GET

### Endpoint
{CLAWMANAGER_AGENT_BASE_URL}/api/v1/agent/commands/next
```

--------------------------------

### GET /gateways/{instance_id}

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md

Retrieves details for a specific gateway instance.

```APIDOC
## GET /gateways/{instance_id}

### Description
Retrieves details for a specific gateway instance.

### Method
GET

### Endpoint
/gateways/{instance_id}

### Parameters
#### Path Parameters
- **instance_id** (string) - Required - The unique identifier of the gateway instance.
```

--------------------------------

### GET /v1/health

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/clawmanager-agent-v2-contract.md

Checks if the agent is ready to accept control-plane commands.

```APIDOC
## GET /v1/health

### Description
The agent reports whether it can accept control-plane commands. Requires the X-ClawManager-Control-Token header.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **status** (string) - The readiness status
```

--------------------------------

### Initialize Platform Redis Client

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Constructor function for creating a new platform-specific Redis client instance.

```go
func NewPlatformRedisClient(rawURL string) (PlatformRedisClient, error) {
	return newRedisBus(rawURL)
}
```

--------------------------------

### Implement Runtime Capacity Helpers

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Core utility functions for managing runtime types, workspace paths, and Linux IDs.

```go
package services

import "fmt"

const (
	RuntimeTypeOpenClaw = "openclaw"
	RuntimeTypeHermes   = "hermes"

	RuntimeGatewayPortStart = 20000
	RuntimeGatewayPortEnd   = 20299
	RuntimePodCapacity      = 100
	RuntimeLinuxIDBase      = 200000
)

func NormalizeV2RuntimeType(instanceType string) (string, bool) {
	switch instanceType {
	case RuntimeTypeOpenClaw:
		return RuntimeTypeOpenClaw, true
	case RuntimeTypeHermes:
		return RuntimeTypeHermes, true
	default:
		return "", false
	}
}

func RuntimeWorkspacePath(runtimeType string, userID int, instanceID int) string {
	return fmt.Sprintf("/workspaces/%s/user-%d/instance-%d", runtimeType, userID, instanceID)
}

func RuntimeLinuxID(instanceID int) int {
	return RuntimeLinuxIDBase + instanceID
}
```

--------------------------------

### GET /gateways/{instance_id}/logs

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md

Retrieves logs for a specific gateway instance.

```APIDOC
## GET /gateways/{instance_id}/logs

### Description
Retrieves logs for a specific gateway instance.

### Method
GET

### Endpoint
/gateways/{instance_id}/logs

### Parameters
#### Path Parameters
- **instance_id** (string) - Required - The unique identifier of the gateway instance.

#### Query Parameters
- **tail** (integer) - Optional - Number of lines to tail.
```

--------------------------------

### Run repository build checks

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-03-clawmanager-v2-e2e-p0.md

Execute build and test commands for frontend and backend components.

```bash
npm run build
```

```bash
go test ./...
```

--------------------------------

### GET /api/v1/admin/session-usage/overview

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/session-token-usage.md

Provides a cross-instance overview of session usage for admin monitoring.

```APIDOC
## GET /api/v1/admin/session-usage/overview

### Description
Returns managed OpenClaw/Hermes running instances sorted by total tokens, including per-instance summaries and global totals.

### Method
GET

### Endpoint
/api/v1/admin/session-usage/overview

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **limit** (integer) - Optional - Number of items per page.
- **search** (string) - Optional - Filters instances by name or identifier.
- **since** (string) - Optional - RFC3339 timestamp filter for start time.
- **until** (string) - Optional - RFC3339 timestamp filter for end time.
```

--------------------------------

### Channel Injection JSON Configuration

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Example structure for the CLAWMANAGER_HERMES_CHANNELS_JSON environment variable.

```json
{
  "feishu": {
    "enabled": true,
    "domain": "feishu",
    "defaultAccount": "main",
    "accounts": {
      "main": {
        "appId": "cli_xxx",
        "appSecret": "secret",
        "enabled": true
      }
    },
    "requireMention": true
  },
  "telegram": {
    "enabled": true,
    "botToken": "123456:xxx",
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}
```

--------------------------------

### Test Runtime Deployment Configuration

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Verifies that the runtime deployment is correctly configured with shared workspace mounts and the expected agent port.

```go
package k8s

import "testing"

func TestBuildRuntimeDeploymentUsesSharedWorkspaceAndAgentPort(t *testing.T) {
	dep := BuildRuntimeDeployment(RuntimeDeploymentSpec{
		Name:              "openclaw-runtime",
		Namespace:         "clawmanager-system",
		RuntimeType:       "openclaw",
		Image:             "example/openclaw:latest",
		Replicas:          2,
		WorkspaceNFSServer: "workspace-store.clawmanager-system.svc.cluster.local",
		WorkspaceNFSPath:   "/exports/workspaces",
		AgentControlToken:  "control",
		AgentReportToken:   "report",
	})

	if dep.Name != "openclaw-runtime" || *dep.Spec.Replicas != 2 {
		t.Fatalf("unexpected deployment identity %#v", dep)
	}
	container := dep.Spec.Template.Spec.Containers[0]
	if container.Ports[0].ContainerPort != 19090 {
		t.Fatalf("agent port missing: %#v", container.Ports)
	}
	foundWorkspace := false
	for _, mount := range container.VolumeMounts {
		if mount.Name == "workspaces" && mount.MountPath == "/workspaces" {
			foundWorkspace = true
		}
	}
	if !foundWorkspace {
		t.Fatalf("workspace mount missing: %#v", container.VolumeMounts)
	}
}
```

--------------------------------

### Error Response Examples

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/clawmanager-agent-v2-contract.md

Plain text error responses for command failures.

```http
HTTP/1.1 409 Conflict
Content-Type: text/plain

no free port
```

```http
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

failed to start gateway process
```

--------------------------------

### Frontend Build Command

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/team-agent-profile-acceptance.md

Builds the frontend application to verify changes.

```bash
cd frontend
npm run build
```

--------------------------------

### Verify Playwright report

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-03-clawmanager-v2-e2e-p0.md

Start the Playwright report server to verify test results.

```bash
npm run test:report -- --host 127.0.0.1
```

--------------------------------

### Apply Manifest

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k8s/single-node/README.md

Deploy the ClawManager resources using the provided manifest file.

```sh
kubectl apply -f clawmanager.yaml
```

--------------------------------

### ListPods JSON Response

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Example JSON structure returned by the ListPods admin endpoint.

```json
{
  "pods": [
    {
      "id": 9,
      "runtime_type": "openclaw",
      "pod_name": "openclaw-runtime-abcde",
      "pod_ip": "10.42.0.31",
      "node_name": "node-a",
      "state": "ready",
      "used_slots": 37,
      "capacity": 100,
      "draining": false,
      "cpu_millis_used": 13600,
      "memory_bytes_used": 42949672960,
      "disk_bytes_used": 214748364800,
      "network_rx_bytes": 9223372,
      "network_tx_bytes": 19223372,
      "last_seen_at": "2026-06-01T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Build Backend for ARM64

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/arm64-deployment_en.md

Perform a static compilation of the backend server for ARM64 architecture.

```bash
cd backend
CGO_ENABLED=0 go build -ldflags="-s -w -extldflags=-static" -o bin/clawreef-server ./cmd/server
```

--------------------------------

### Navigate to Deployment Directory

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/single-node/README.md

Change to the single-node deployment directory.

```sh
cd deployments/k3s/single-node
```

--------------------------------

### Wire Workspace Routes

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Dependency injection and route registration for the workspace file handler in the main server file.

```go
workspaceAuditRepo := repository.NewWorkspaceFileAuditRepository(sess)
workspaceFileService := services.NewWorkspaceFileService(workspaceAuditRepo)
workspaceFileHandler := handlers.NewWorkspaceFileHandler(instanceService, workspaceFileService)

instances := api.Group("/instances")
instances.GET("/:id/workspace/files", workspaceFileHandler.List)
instances.GET("/:id/workspace/preview", workspaceFileHandler.Preview)
instances.GET("/:id/workspace/download", workspaceFileHandler.Download)
instances.POST("/:id/workspace/upload", workspaceFileHandler.Upload)
instances.POST("/:id/workspace/folders", workspaceFileHandler.Mkdir)
instances.PATCH("/:id/workspace/entries", workspaceFileHandler.Rename)
instances.DELETE("/:id/workspace/entries", workspaceFileHandler.Delete)
```

--------------------------------

### Navigate to Deployment Directory

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/cluster/README.md

Change to the directory containing the K3s manifest files.

```sh
cd deployments/k3s/cluster
```

--------------------------------

### Check deployment resources

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Verify the status of namespaces, pods, and services in the clawmanager-system namespace.

```bash
kubectl get ns
kubectl get pods -n clawmanager-system
kubectl get svc -n clawmanager-system
```

--------------------------------

### s6-overlay Service Run Script

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

The execution script for the Hermes agent, which checks for the enabled flag before starting.

```bash
#!/usr/bin/with-contenv bash
set -euo pipefail

if [ "${CLAWMANAGER_AGENT_ENABLED:-false}" != "true" ]; then
  echo "ClawManager Hermes agent disabled"
  sleep infinity
fi

exec /usr/local/bin/hermes-agent
```

--------------------------------

### Initialize Workspace Scope

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Standard pattern for creating a workspace scope from instance data within handlers.

```go
scope := services.WorkspaceFileScope{
	InstanceID: instance.ID,
	UserID: userID,
	WorkspacePath: *instance.WorkspacePath,
}
```

--------------------------------

### GET /api/v1/agent/skills/versions/{external_version_id}/download

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Downloads a skill package zip file for a specific version identifier.

```APIDOC
## GET /api/v1/agent/skills/versions/{external_version_id}/download

### Description
Downloads the zip package for a specific skill version. This is used when the agent supports platform-managed skill installation.

### Method
GET

### Endpoint
{CLAWMANAGER_AGENT_BASE_URL}/api/v1/agent/skills/versions/{external_version_id}/download

### Parameters
#### Path Parameters
- **external_version_id** (string) - Required - The unique identifier for the skill version to download.
```

--------------------------------

### Deploy ClawManager with Single-Node Profile

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/deployment.md

Commands to label a node and apply the single-node deployment manifest.

```bash
kubectl get nodes
kubectl label node <node> clawmanager.io/storage-node=true --overwrite
kubectl apply -f deployments/k8s/single-node/clawmanager.yaml
kubectl get pvc -n clawmanager-system
kubectl get pods -n clawmanager-system
```

--------------------------------

### Verify StorageClass configuration

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/use_guide_en.md

Commands to list available storage classes and confirm the existence of required providers.

```bash
kubectl get storageclass
```

```bash
kubectl get storageclass longhorn longhorn-rwx
```

--------------------------------

### GET /api/v1/instances/:id/session-usage/detail

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/session-token-usage.md

Retrieves detailed breakdown and recent traces for a specific session within an instance.

```APIDOC
## GET /api/v1/instances/:id/session-usage/detail

### Description
Returns model breakdown (tokens and cost) and recent traces for a specific session. Respects time window filters and excludes blocked invocations.

### Method
GET

### Endpoint
/api/v1/instances/:id/session-usage/detail

### Parameters
#### Path Parameters
- **id** (string) - Required - The instance identifier.

#### Query Parameters
- **session_id** (string) - Required - The specific session identifier.
- **since** (string) - Optional - RFC3339 timestamp filter for start time.
- **until** (string) - Optional - RFC3339 timestamp filter for end time.
```

--------------------------------

### Run database migration

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/backend/README.md

Executes database schema migrations.

```bash
make migrate
```

--------------------------------

### Dockerfile for Hermes Runtime

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Base Dockerfile configuration for installing the Hermes agent and registering it as an s6 longrun service.

```dockerfile
FROM lscr.io/linuxserver/webtop:ubuntu-xfce

USER root

# 1. Install Hermes runtime dependencies.
# Keep this as an example. The Hermes project should own the real install steps.
# RUN apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/*

# 2. Install Hermes itself.
# COPY hermes /opt/hermes

# 3. Install the ClawManager Hermes agent.
COPY hermes-agent /usr/local/bin/hermes-agent
RUN chmod +x /usr/local/bin/hermes-agent

# 4. Register an s6 longrun service so the agent starts with the Webtop container.
COPY root/ /

ENV TITLE="Hermes Runtime"
ENV SUBFOLDER="/"

EXPOSE 3001
```

--------------------------------

### Implement Instance Service Frame

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Renders an iframe for the instance service, with conditional states for starting or unavailable instances.

```tsx
interface InstanceServiceFrameProps {
  instanceId: number;
  availability: "available" | "starting" | "unavailable";
}

export function InstanceServiceFrame({ instanceId, availability }: InstanceServiceFrameProps) {
  if (availability === "starting") {
    return <div className="cm-surface flex min-h-[420px] items-center justify-center text-sm text-gray-600">Starting</div>;
  }
  if (availability === "unavailable") {
    return <div className="cm-surface flex min-h-[420px] items-center justify-center text-sm text-gray-600">Unavailable</div>;
  }
  return (
    <iframe
      title="Instance"
      src={`/api/v1/instances/${instanceId}/proxy/`}
      className="h-[min(720px,calc(100vh-220px))] min-h-[520px] w-full rounded-lg border border-gray-200 bg-white"
    />
  );
}
```

--------------------------------

### Build Multi-platform Docker Images

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/arm64-deployment_en.md

Build and push images supporting both amd64 and arm64 architectures using docker buildx.

```bash
# Build and push multi-platform images
docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/your-name/clawmanager:latest --push .
```

--------------------------------

### Troubleshoot Resources

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/single-node/README.md

Commands to debug pending PVCs, pods, or container creation issues.

```sh
kubectl get pv | grep clawmanager
kubectl -n clawmanager-system describe pvc <pvc-name>
```

```sh
kubectl get nodes -l clawmanager.io/storage-node=true
kubectl describe pod <pod-name> -n clawmanager-system
```

```sh
kubectl -n clawmanager-system get events --sort-by=.lastTimestamp | tail -n 80
```

--------------------------------

### Error Message: Missing NFS Helper

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/deployments/k3s/cluster/README.md

Example of an error message when required NFS mount helpers are missing.

```text
bad option; you might need a /sbin/mount.<type> helper program
```

--------------------------------

### Gateway State Machine

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/clawmanager-agent-v2-development-guide.md

The recommended state transition flow for gateway instances.

```text
requested -> reserved_port -> starting -> running
                              -> error
running -> stopping -> stopped
running -> unhealthy -> running/error
```

--------------------------------

### Install Skill Payload Structure

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Payload format for the install_skill command used to deploy platform-uploaded zip skill packages.

```json
{
  "skill_id": "skill-12",
  "skill_version": "skill-version-34",
  "target_name": "weather-tool",
  "content_md5": "d41d8cd98f00b204e9800998ecf8427e"
}
```

--------------------------------

### Skill Inventory JSON Payload

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Example JSON body for the skill inventory report, including metadata and MD5 checksums.

```json
{
  "agent_id": "hermes-123-main",
  "reported_at": "2026-04-27T14:30:00Z",
  "mode": "full",
  "trigger": "startup",
  "skills": [
    {
      "skill_id": "hermes-weather",
      "skill_version": "1.2.0",
      "identifier": "hermes-weather",
      "install_path": "/config/.hermes/skills/hermes-weather",
      "content_md5": "d41d8cd98f00b204e9800998ecf8427e",
      "source": "discovered_in_instance",
      "type": "hermes-skill",
      "size_bytes": 20480,
      "file_count": 12,
      "metadata": {
        "runtime": "hermes",
        "manifest": "skill.json"
      }
    }
  ]
}
```

--------------------------------

### Project directory structure

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/backend/README.md

Overview of the backend project file organization.

```text
backend/
├── cmd/server/          # Application entry point
├── internal/
│   ├── config/          # Configuration
│   ├── db/              # Database connection & migrations
│   ├── models/          # Data models
│   ├── repository/      # Data access layer
│   ├── services/        # Business logic
│   ├── handlers/        # HTTP handlers
│   ├── middleware/      # HTTP middleware
│   └── utils/           # Utilities
├── deployments/         # Docker & K8s configs
└── configs/             # Configuration files
```

--------------------------------

### Test Workspace File Service Preview

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Unit tests verifying text preview limits and error handling for the workspace file service.

```go
func TestWorkspaceFileServicePreviewTextLimit(t *testing.T) {
	root := t.TempDir()
	if err := os.WriteFile(filepath.Join(root, "small.txt"), []byte("hello"), 0640); err != nil {
		t.Fatal(err)
	}
	service := NewWorkspaceFileService(fakeAuditRepo{})
	preview, err := service.Preview(context.Background(), WorkspaceFileScope{InstanceID: 1, UserID: 2, WorkspacePath: root}, "small.txt")
	if err != nil {
		t.Fatalf("Preview returned error: %v", err)
	}
	if preview.Kind != "text" || preview.Text != "hello" {
		t.Fatalf("unexpected preview %#v", preview)
	}
}

func TestWorkspaceFileServiceRejectsLargeTextPreview(t *testing.T) {
	root := t.TempDir()
	large := bytes.Repeat([]byte("a"), 1024*1024+1)
	if err := os.WriteFile(filepath.Join(root, "large.log"), large, 0640); err != nil {
		t.Fatal(err)
	}
	service := NewWorkspaceFileService(fakeAuditRepo{})
	_, err := service.Preview(context.Background(), WorkspaceFileScope{InstanceID: 1, UserID: 2, WorkspacePath: root}, "large.log")
	if err == nil || err.Error() != "text preview exceeds 1 MiB" {
		t.Fatalf("unexpected error %v", err)
	}
}
```

--------------------------------

### System Information Reporting JSON Structure

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/hermes-runtime-agent-development.md

Example of the expected JSON structure for a command result containing system metrics.

```json
{
  "agent_id": "hermes-123-main",
  "status": "succeeded",
  "finished_at": "2026-04-27T14:31:05Z",
  "result": {
    "sampled_at": "2026-04-27T14:31:05Z",
    "system_info": {
      "cpu": {
        "cores": 2,
        "load": {
          "1m": 0.70,
          "5m": 0.55,
          "15m": 0.42
        }
      },
      "memory": {
        "mem_total_bytes": 4294967296,
        "mem_available_bytes": 2013265920
      },
      "disk": {
        "mount_path": "/config/.hermes",
        "root_total_bytes": 10737418240,
        "root_free_bytes": 8589934592
      },
      "network": {
        "interfaces": [
          {
            "name": "eth0",
            "status": "up",
            "rx_bytes": 124000000,
            "tx_bytes": 99000000
          }
        ]
      }
    }
  },
  "error_message": ""
}
```

--------------------------------

### Runtime Log Output for Inbound-Only Configuration

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/admin-user-guide.md

Example of authoritative runtime log output confirming an inbound-only clipboard configuration.

```text
clipboard_enabled: (True, True)
clipboard_in_enabled: (True, True)
clipboard_out_enabled: (False, True)
```

--------------------------------

### Define Runtime Configuration Struct

Source: https://github.com/yuan-lab-llm/clawmanager/blob/main/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md

Configuration fields and initialization logic for runtime settings.

```go
	Runtime RuntimeConfig
```

```go
type RuntimeConfig struct {
	Namespace          string
	WorkspaceRoot      string
	AgentControlToken  string
	AgentReportToken   string
	BackendReplicaID   string
	RedisURL           string
	SchedulerEnabled   bool
	HeartbeatTimeout   time.Duration
	SchedulerTick       time.Duration
	OpenClawImage      string
	HermesImage         string
	MaxGatewaysPerPod   int
	GatewayPortStart    int
	GatewayPortEnd      int
}
```

```go
Runtime: RuntimeConfig{
	Namespace:        getEnv("RUNTIME_NAMESPACE", getEnv("K8S_NAMESPACE", "clawmanager-system")),
	WorkspaceRoot:    getEnv("RUNTIME_WORKSPACE_ROOT", "/workspaces"),
	AgentControlToken: getEnv("RUNTIME_AGENT_CONTROL_TOKEN", ""),
	AgentReportToken:  getEnv("RUNTIME_AGENT_REPORT_TOKEN", ""),
	BackendReplicaID:  getEnv("HOSTNAME", "clawmanager-backend-local"),
	RedisURL:          getEnv("PLATFORM_REDIS_URL", getEnv("TEAM_REDIS_URL", "")),
	SchedulerEnabled:  getEnvBool("RUNTIME_SCHEDULER_ENABLED", true),
	HeartbeatTimeout:  getEnvDuration("RUNTIME_HEARTBEAT_TIMEOUT", 10*time.Second),
	SchedulerTick:     getEnvDuration("RUNTIME_SCHEDULER_TICK", 2*time.Second),
	OpenClawImage:     getEnv("OPENCLAW_RUNTIME_IMAGE", "ghcr.io/yuan-lab-llm/clawmanager-openclaw-image/openclaw:latest"),
	HermesImage:        getEnv("HERMES_RUNTIME_IMAGE", "ghcr.io/yuan-lab-llm/clawmanager-openclaw-image/openclaw:latest"),
	MaxGatewaysPerPod:  getEnvInt("RUNTIME_MAX_GATEWAYS_PER_POD", RuntimePodCapacity),
	GatewayPortStart:  getEnvInt("RUNTIME_GATEWAY_PORT_START", RuntimeGatewayPortStart),
	GatewayPortEnd:    getEnvInt("RUNTIME_GATEWAY_PORT_END", RuntimeGatewayPortEnd),
},
```
Tokens:
Raw