#Cloud SaaS Deployment Runtime

Cloud SaaS deployments expose runtime lifecycle operations through the deployment API namespace: pause idle agents, resume them on demand, create and list state backups, and restore from a backup.

All endpoints live under /api/cloud-saas/deployments/:id.

#Template manifest

GET /manifest returns the deployment's linked template, manifest revision, config hash, and drift state (up-to-date, template-updated, missing-template, unlinked, or unknown). The normal deployment list remains redacted; use this endpoint when a dashboard or CLI needs to explain where a running deployment came from.

POST /template saves the deployed config snapshot as an editable template. Owned draft/rejected community templates are updated in place; official, approved, or pending templates are forked.

POST /redeploy still accepts an empty body for the existing snapshot redeploy behavior. It also accepts:

const manifest = await client.getCloudDeploymentManifest('deployment-id')
await client.syncCloudDeploymentTemplate('deployment-id')
await client.redeployCloudDeployment('deployment-id', { mode: 'template' })

manifest = client.get_cloud_deployment_manifest("deployment-id")
client.sync_cloud_deployment_template("deployment-id")
client.redeploy_cloud_deployment("deployment-id", mode="template")

#Pause deployment

Pauses a running agent-sandbox workload by scaling its Sandbox to 0. The PVC is retained for later resume or restore. Only the current deployment in a namespace can be paused.

Response (200):

{
  "ok": true,
  "status": "paused",
  "deployment": {}
}

const result = await client.pauseCloudDeployment('deployment-id', { agentId: 'strategy-buddy' })
console.log(result.status) // 'paused'

result = client.pause_cloud_deployment("deployment-id", agent_id="strategy-buddy")
print(result["status"])  # 'paused'

Possible errors: 404 deployment not found, 409 cannot pause a historical deployment, 422 unsupported status.

#Resume deployment

Resumes a paused agent-sandbox workload by scaling its Sandbox back to 1. The agent will pick up from its saved state on the PVC.

Response (200):

{
  "ok": true,
  "status": "deployed",
  "deployment": {}
}

const result = await client.resumeCloudDeployment('deployment-id', { agentId: 'strategy-buddy' })
console.log(result.status) // 'deployed'

result = client.resume_cloud_deployment("deployment-id", agent_id="strategy-buddy")
print(result["status"])  # 'deployed'

Possible errors: 404 deployment not found, 409 cannot resume a historical deployment, 422 unsupported status, 502 resume failed.

#List backups

Returns all backup records for the deployment, including status and phase fields that track progress through snapshot creation, object archive upload, PVC restore, and sandbox resume.

Response:

{
  "deploymentId": "uuid",
  "backups": [
    {
      "id": "backup-id",
      "deploymentId": "uuid",
      "namespace": "gstack-buddy",
      "agentId": "strategy-buddy",
      "sandboxName": "strategy-buddy",
      "pvcName": "openclaw-data-strategy-buddy",
      "driver": "volumeSnapshot",
      "snapshotName": "gstack-buddy-strategy-buddy-2025-01-01T00-00-00Z",
      "objectKey": null,
      "status": "succeeded",
      "phase": "completed",
      "error": null,
      "expiresAt": null,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:01:00.000Z"
    }
  ]
}

const { backups } = await client.listCloudDeploymentBackups('deployment-id')
const { backups } = await client.listCloudDeploymentBackups('deployment-id', { agentId: 'strategy-buddy' })

result = client.list_cloud_deployment_backups("deployment-id")
result = client.list_cloud_deployment_backups("deployment-id", agent_id="strategy-buddy")
backups = result["backups"]

#Create backup

Creates a state backup for the deployment. When the cluster supports CSI VolumeSnapshot and the target PVC is backed by a CSI StorageClass with a matching VolumeSnapshotClass, the API creates a VolumeSnapshot. Otherwise it falls back to an object archive (pod-based tar.gz, optionally encrypted).

The backup runs asynchronously. The response returns 202 with the backup record. Check the backup phase field to track progress: queued → snapshot-creating or object-archiving → completed.

Response (202):

{
  "ok": true,
  "backup": {
    "id": "backup-id",
    "status": "running",
    "phase": "queued"
  }
}

// VolumeSnapshot backup
const { backup } = await client.createCloudDeploymentBackup('deployment-id', {
  agentId: 'strategy-buddy',
  driver: 'volumeSnapshot',
  retentionDays: 30,
})

// Object archive backup with encryption
const objectBackup = await client.createCloudDeploymentBackup('deployment-id', {
  agentId: 'strategy-buddy',
  driver: 'restic',
})

# VolumeSnapshot 备份
result = client.create_cloud_deployment_backup("deployment-id",
    agent_id="strategy-buddy",
    driver="volumeSnapshot",
    retention_days=30,
)
backup = result["backup"]

# 对象归档备份（可加密）
object_result = client.create_cloud_deployment_backup("deployment-id",
    agent_id="strategy-buddy",
    driver="restic",
)

Possible errors: 404 deployment not found, 409 another operation is already running in this namespace, 422 unsupported status or VolumeSnapshot not available.

#Restore from backup

Restores deployment state from a backup. The restore process:

1. Pauses the agent-sandbox (if running).
2. Restores the state PVC from the VolumeSnapshot or object archive.
3. Resumes the agent-sandbox workload.

The operation runs asynchronously and returns 202. Check the backup phase field to track progress: restoring-pausing → restoring-pvc → restoring-resuming → completed.

Response (202):

{
  "ok": true,
  "backup": {},
  "status": "resuming",
  "deployment": {}
}

const result = await client.restoreCloudDeploymentBackup('deployment-id', {
  agentId: 'strategy-buddy',
  backupId: 'backup-id',
})
console.log(result.status) // 'resuming'

result = client.restore_cloud_deployment_backup("deployment-id",
    agent_id="strategy-buddy",
    backup_id="backup-id",
)
print(result["status"])  # 'resuming'

Possible errors: 404 deployment or backup not found, 409 another operation is running in this namespace, 422 unsupported status or backup driver.

#Auto-resume triggers

Cloud deployments that are paused will automatically resume when the platform detects activity:

App proxy auto-resume is synchronous (waits up to 25s). Message mention and agent heartbeat auto-resumes are fire-and-forget.

#Deployment status lifecycle

Deployments progress through these statuses:

The resuming status is transient between paused and deployed. The failed status with reasons like cancelled by user or superseded-by-newer-deployment is not shown to users.

#Next Steps

• Cloud overview for the full deployment model.
• Cloud CLI for the sandbox command group.
• SDKs for the client methods.