Skip to main content

Workspace Service

The workspace service is a lightweight HTTP REST sidecar provided by MosBot OS — it is not part of the standard OpenClaw distribution. It runs alongside OpenClaw, shares the same workspace directory or volume, and exposes the workspace filesystem over HTTP so MosBot API can read and write workspace files, manage configuration, and list agents.

Deployment

You need to run the workspace service container (ghcr.io/bymosbot/mosbot-workspace-service) next to your OpenClaw instance. See Setting Up OpenClaw for Docker and Kubernetes deployment examples. :::

What the workspace service provides​

  • File access: read, create, update, and delete files in agent workspaces
  • Directory listing: list files and directories recursively
  • Configuration access: read and write openclaw.json
  • Agent discovery: list agents defined in openclaw.json

Architecture​

MosBot API
    │
    │ HTTP (Bearer token auth)
    ▼
OpenClaw Workspace Service (port 8080)
    │
    │ Filesystem access
    ▼
Workspace PVC / directory
(workspace-coo/, workspace-cto/, skills/, shared/, etc.)

In Kubernetes, the workspace service runs as a sidecar container in the OpenClaw pod and shares the same PVC (Persistent Volume Claim). This means it has direct filesystem access to all workspace directories.

Authentication​

The workspace service uses bearer token authentication. The token is shared between the workspace service configuration and MosBot API's OPENCLAW_WORKSPACE_TOKEN environment variable.

Generating a token​

WORKSPACE_TOKEN="$(openssl rand -base64 32)"
echo "Save this token: ${WORKSPACE_TOKEN}"

Configure the same token in:

  1. OpenClaw's workspace service (as WORKSPACE_SERVICE_TOKEN in its environment)
  2. MosBot API's .env (as OPENCLAW_WORKSPACE_TOKEN)

Security model​

The workspace service is designed to be an internal service — not exposed to the public internet:

  • Network isolation: in Kubernetes, deploy as a ClusterIP service (no public ingress)
  • Bearer token auth: all requests require a valid token
  • Path validation: the service normalizes paths and rejects directory traversal attempts (e.g. ..)
  • RBAC: MosBot API enforces its own role-based access control before proxying requests to the workspace service

Workspace directory structure​

A typical OpenClaw workspace layout:

/                           ← workspace root
├── workspace-coo/          ← agent workspace (COO agent)
│   ├── memory/             ← agent memory files
│   ├── skills/             ← agent-specific skills
│   └── HEARTBEAT.md        ← heartbeat context file
├── workspace-cto/          ← agent workspace (CTO agent)
│   ├── memory/
│   └── skills/
├── skills/                 ← shared skills (available to all agents)
├── docs/                   ← shared documentation
├── projects/               ← shared project files
└── openclaw.json           ← OpenClaw configuration

API endpoints (via MosBot API)​

MosBot API proxies workspace requests through its own authenticated endpoints:

EndpointDescription
GET /api/v1/openclaw/workspace/statusCheck workspace service connectivity
GET /api/v1/openclaw/workspace/filesList files (params: path, recursive)
GET /api/v1/openclaw/workspace/fileRead a file (param: path)
POST /api/v1/openclaw/workspace/fileCreate a new file
PUT /api/v1/openclaw/workspace/fileUpdate an existing file
DELETE /api/v1/openclaw/workspace/fileDelete a file
GET /api/v1/openclaw/configRead openclaw.json
PUT /api/v1/openclaw/configUpdate openclaw.json
GET /api/v1/openclaw/agentsList agents from openclaw.json

Verifying the workspace service​

# Direct check (bypassing MosBot API)
curl -H "Authorization: Bearer <workspace-token>" \
  http://localhost:8080/status

# Via MosBot API (requires MosBot JWT)
curl -H "Authorization: Bearer <mosbot-jwt>" \
  http://localhost:3000/api/v1/openclaw/workspace/status

Troubleshooting​

503 on workspace endpoints The workspace service is unreachable. Check:

  • OPENCLAW_WORKSPACE_URL is correct
  • The workspace service is running
  • Network connectivity between MosBot API and the workspace service

401 Unauthorized The token doesn't match. Verify OPENCLAW_WORKSPACE_TOKEN in MosBot API's .env matches the token configured in the workspace service.

Path traversal errors The path contains .. or other traversal sequences. Use absolute paths from the workspace root (e.g. /workspace-coo/memory/2026-03-01.md).