Deploying with an agent

Read this first when an autonomous coding agent needs the deploy flow for a Cloudbed capsule.

Fast path

Fresh project:

npx cloudbed new my-app --template todo
cd my-app
npx cloudbed deploy --json

Existing project:

cd existing-app
npx cloudbed init . --template todo --json
npx cloudbed deploy --json

cloudbed init [dir] [--template todo|guestbook] scaffolds into an existing directory, including a non-empty one. It never overwrites files, merges the cloudbed dependency into an existing package.json, and supports --json.

With no auth, cloudbed deploy --json creates an anonymous deploy. No account is required. The response includes a live URL.

{
  "deployId": "dep_...",
  "url": "https://example.cloudbed.app",
  "name": "todo",
  "mode": "anonymous",
  "claimed": false,
  "createdAt": "2026-07-02T00:00:00.000Z",
  "updatedAt": "2026-07-02T00:00:00.000Z",
  "expiresAt": "2026-07-09T00:00:00.000Z",
  "claimToken": "cb_claim_...",
  "claimUrl": "https://dashboard.cloudbed.dev/claim?token=...",
  "inspectToken": "cb_inspect_..."
}

Save these fields:

The CLI auto-persists deploy state to .cloudbed/deploy.json with api, deployId, claimToken, and inspectToken. Keep .cloudbed/ gitignored. If a deploy is owned or claimed, the CLI writes cloudbed.json; commit that file so future deploys from the directory update the same app.

Auth for agents

Use CLOUDBED_TOKEN for non-interactive auth. It is a bearer token, checked before ~/.cloudbed/auth.json, and works for deploy, claim, whoami, token, domains, and inspect.

export CLOUDBED_TOKEN="cb_..."
cloudbed whoami --json

To validate and persist a token for later commands:

cloudbed login --token "$CLOUDBED_TOKEN"

To mint tokens for automation:

cloudbed token create --name agent-ci --json
cloudbed token create --name agent-deploy --deploy --json

--deploy scopes the token to the current directory's deploy. The token value is shown once; store it as a secret.

State files

Error handling

Run commands with --json. On failure, JSON commands print an error envelope to stderr and exit nonzero:

{"error":{"code":"invalid_artifact","message":"artifact.format must be \"cloudbed.capsule.v1\"."}}

Branch on error.code, not the message.

Limits

Storage and handler caps apply to every deploy. Daily counters apply only to anonymous deploys and disappear on claim.

Verify it worked

deploy_json="$(cloudbed deploy --json)"
url="$(node -e 'console.log(JSON.parse(process.argv[1]).url)' "$deploy_json")"
curl -fsS "$url"
cloudbed inspect --json

For capsule({ ssr: true }) apps, curl -fsS "$url" includes the rendered app markup and the embedded __cloudbed_state__ snapshot. For CSR apps it still returns the boot shell, so use the inspect manifest and app-specific HTTP or WS checks for deeper verification.

cloudbed logs --json shows what the server code actually did (ctx.log entries; add --follow to stream while you exercise the app). If the new deploy is broken, cloudbed releases --json + cloudbed rollback restore the previous release in one command — then fix and redeploy.