Shadow LogoShadowOwnBuddy
Launch
English

Cloud CLI

shadowob-cloud is the standalone deployment CLI for Shadow Cloud. It can create a config from a template, validate secrets and schema, deploy to Kubernetes, open the dashboard, and manage bare-server k3s clusters.

Install

npm install -g @shadowob/cloud
# or
pnpm add -g @shadowob/cloud

Verify your workstation:

shadowob-cloud --version
shadowob-cloud doctor

doctor checks local prerequisites such as kubectl, Docker, and Pulumi.

First Deploy

shadowob-cloud init --template gstack-buddy
shadowob-cloud validate --strict
shadowob-cloud up
shadowob-cloud status

Templates use ${env:VAR_NAME} for secrets:

export OPENAI_COMPATIBLE_API_KEY="sk-..."
export OPENAI_COMPATIBLE_BASE_URL="https://api.example.com/v1"
export OPENAI_COMPATIBLE_MODEL_ID="deepseek-v4-flash"
export SHADOW_SERVER_URL="https://app.example.com"
export SHADOW_USER_TOKEN="..."

Common Commands

CommandPurpose
shadowob-cloud initCreate shadowob-cloud.json, optionally from a built-in template.
shadowob-cloud init --listList available templates.
shadowob-cloud validate --strictValidate schema, template references, security, and environment variables.
shadowob-cloud upDeploy to the current Kubernetes context.
shadowob-cloud up --localStart a local Kind cluster before deploying.
shadowob-cloud statusShow deployments and pods.
shadowob-cloud logs <agent-id>Stream agent logs.
shadowob-cloud scale <agent-id> --replicas 3Scale an agent deployment.
shadowob-cloud downTear down deployed resources.
shadowob-cloud dashboardOpen the Cloud dashboard.
shadowob-cloud serveStart the API server and dashboard.
shadowob-cloud generate manifestsExport Kubernetes manifests without applying them.
shadowob-cloud sandbox statusList agent-sandbox workloads and their current state.
shadowob-cloud sandbox pause <agent>Pause an agent-sandbox workload by scaling to 0.
shadowob-cloud sandbox resume <agent>Resume a paused agent-sandbox workload.
shadowob-cloud sandbox backup <agent>Create a VolumeSnapshot backup for an agent-sandbox state PVC.
shadowob-cloud sandbox restore <agent>Resume a sandbox after PVC restore completes.

Agent-Sandbox Lifecycle

Agent-sandbox workloads support pause/resume and state backup/restore directly from the CLI:

# Pause an agent to free compute while keeping PVC state
shadowob-cloud sandbox pause strategy-buddy

# Resume later; the agent rebuilds context from its saved state
shadowob-cloud sandbox resume strategy-buddy

# Create a VolumeSnapshot backup of the state PVC
shadowob-cloud sandbox backup strategy-buddy --snapshot-class csi-hostpath-snapclass

# After restoring a PVC externally, hand off to the sandbox
shadowob-cloud sandbox restore strategy-buddy --backup-id <backup-id>

The sandbox status command shows every agent-sandbox workload with its runtime state, ready count, and state PVC name.

shadowob-cloud sandbox status -n my-namespace

Bare-Server Clusters

Cloud can bootstrap k3s on Ubuntu or Debian servers over SSH.

shadowob-cloud cluster init --config cluster.json
shadowob-cloud cluster status
shadowob-cloud up --cluster prod

A minimal cluster file:

{
  "name": "prod",
  "nodes": [
    {
      "role": "master",
      "host": "1.2.3.4",
      "user": "root",
      "sshKeyPath": "~/.ssh/id_rsa"
    }
  ]
}

Kubeconfigs are stored under ~/.shadow-cloud/clusters/<name>.yaml.

Local Debugging

shadowob-cloud generate openclaw-config
shadowob-cloud logs strategy-buddy
shadowob-cloud dashboard

Use generate openclaw-config when you need to inspect the final model provider, tools, permissions, and Shadow channel configuration that will be mounted into the agent.

ON THIS PAGE