openclaw/crabbox
openclaw/crabbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
main
crabbox/docs/commands/artifacts.md
Peter Steinberger b568298019
feat: improve desktop reliability artifacts
2026-05-08 04:52:51 +01:00

7.6 KiB
Raw Permalink Blame History

artifacts

crabbox artifacts collects desktop QA evidence into a durable bundle, creates trimmed review media, and publishes inline-ready assets for pull requests.

Use it when a desktop/WebVNC issue or UI fix needs more than a one-off screenshot: MP4 recording, trimmed GIF, logs, doctor output, WebVNC status, and metadata in one directory.

Collect

crabbox artifacts collect --id blue-lobster --output artifacts/blue-lobster
crabbox artifacts collect --id blue-lobster --all --duration 20s --output artifacts/blue-lobster
crabbox artifacts collect --id blue-lobster --run run_123 --output artifacts/blue-lobster

By default collect writes:

  • metadata.json
  • screenshot.png
  • doctor.txt
  • webvnc-status.json when a coordinator login is configured
  • logs.txt and run.json when --run <run-id> is provided

--all also records screen.mp4, creates screen.trimmed.gif, and writes screen.trimmed.mp4 using the same motion window. Video/GIF capture currently requires a Linux desktop lease with ffmpeg and X11 capture support.

Useful flags:

--id <lease-id-or-slug>
--output <dir>
--run <run-id>
--all
--screenshot
--video
--gif
--doctor
--webvnc-status
--metadata
--duration <duration> default 10s
--fps <n>             default 15
--gif-width <px>      default 640
--provider <name>
--network auto|public|tailscale
--json

When collection hits an unhealthy desktop, WebVNC, VNC, or input layer, it prints the same inline problem:, detail:, and rescue: commands used by the desktop and WebVNC commands. With --json, stdout remains valid JSON and those same repair hints are returned in the warnings array instead of being printed as text before the JSON document. If a capture step fails after the bundle has started, the command still exits nonzero and includes an error object with a stable code and message.

Video

crabbox artifacts video --id blue-lobster --duration 15s --output screen.mp4

video records only an MP4 from a Linux desktop lease. It is useful when you want to keep capture separate from bundle collection.

GIF

crabbox artifacts gif \
  --input screen.mp4 \
  --output screen.trimmed.gif \
  --trimmed-video-output screen.trimmed.mp4

gif is an alias for the same local motion-trimmed preview logic as crabbox media preview.

Templates

crabbox artifacts template openclaw \
  --before before.png \
  --after after.gif \
  --summary "Login modal no longer overlaps the toolbar." \
  --output summary.md

crabbox artifacts template mantis --summary-file qa-notes.md

Templates write Markdown with Summary, Before / After, and Evidence sections sized for Mantis/OpenClaw QA comments.

Publish

crabbox artifacts publish \
  --dir artifacts/blue-lobster \
  --pr 123

crabbox artifacts publish \
  --dir artifacts/blue-lobster \
  --pr 123 \
  --storage s3 \
  --bucket qa-artifacts \
  --prefix pr-123/blue-lobster \
  --base-url https://qa-artifacts.example.com

crabbox artifacts publish \
  --dir artifacts/blue-lobster \
  --pr 123 \
  --storage cloudflare \
  --bucket qa-artifacts \
  --prefix pr-123/blue-lobster \
  --base-url https://artifacts.example.com

publish uploads bundle files, writes published-artifacts.md, and comments on the PR with inline images/GIFs plus links to videos, logs, and metadata. Use --dry-run to generate markdown and print intended actions without upload or comment side effects.

Storage backends:

  • --storage auto is the default. When a coordinator is configured, Crabbox asks the broker for upload URLs and the broker-owned artifact backend handles storage credentials. Without a coordinator, auto falls back to local markdown.
  • --storage broker requires a configured coordinator and uploads through broker-minted URLs.
  • --storage s3 uses the AWS CLI and uploads to s3://<bucket>/<prefix>/....
  • --storage cloudflare uses wrangler r2 object put --remote.
  • --storage r2 uses the AWS CLI against an S3-compatible R2 endpoint.
  • --storage local writes markdown only. For --pr, local publishing needs a --base-url that already serves the files, otherwise the PR would contain unusable local paths.

S3 flags:

--bucket <name>
--prefix <path>
--base-url <url>
--region <region>
--profile <profile>
--endpoint-url <url>
--acl <acl>
--presign
--expires <duration> default 168h

When --base-url is supplied, published links use that public URL. Otherwise --presign generates temporary AWS/R2 S3 URLs after upload.

Cloudflare R2 flags:

--bucket <name>
--prefix <path>
--base-url <url>     required for --pr inline-ready links

For native Cloudflare publishing, publish runs wrangler with CRABBOX_ARTIFACTS_CLOUDFLARE_* when present, then the generic CLOUDFLARE_* environment. Prefer brokered publishing for shared teams so Cloudflare and object-store secrets stay on the coordinator.

For S3-compatible R2 publishing, pass --storage r2 --endpoint-url <r2-endpoint> --profile <r2-profile>. When present, Crabbox uses CRABBOX_ARTIFACTS_R2_ENDPOINT_URL and CRABBOX_ARTIFACTS_R2_AWS_PROFILE before falling back to generic AWS defaults.

Coordinator artifact backend configuration:

CRABBOX_ARTIFACTS_BACKEND=s3|r2
CRABBOX_ARTIFACTS_BUCKET
CRABBOX_ARTIFACTS_PREFIX
CRABBOX_ARTIFACTS_BASE_URL
CRABBOX_ARTIFACTS_REGION
CRABBOX_ARTIFACTS_ENDPOINT_URL
CRABBOX_ARTIFACTS_ACCESS_KEY_ID
CRABBOX_ARTIFACTS_SECRET_ACCESS_KEY
CRABBOX_ARTIFACTS_SESSION_TOKEN
CRABBOX_ARTIFACTS_UPLOAD_EXPIRES_SECONDS
CRABBOX_ARTIFACTS_URL_EXPIRES_SECONDS

For brokered publishing, the CLI never receives object-store credentials. It sends artifact names, sizes, content types, and hashes to POST /v1/artifacts/uploads; the coordinator returns one short-lived upload URL per file plus the final URL to place in Markdown. Upload grants are signed with the declared content-length, so the object store rejects oversized PUTs during the grant window; the broker also caps each upload request at 5 GiB total before signing grants. When --prefix is omitted for hosted publishing, the CLI derives a unique prefix from the PR number, bundle directory, and current time so later QA comments do not overwrite earlier evidence.

Coordinator artifact values split into two groups:

  • Worker vars: CRABBOX_ARTIFACTS_BACKEND, CRABBOX_ARTIFACTS_BUCKET, CRABBOX_ARTIFACTS_PREFIX, CRABBOX_ARTIFACTS_BASE_URL, CRABBOX_ARTIFACTS_REGION, CRABBOX_ARTIFACTS_ENDPOINT_URL, CRABBOX_ARTIFACTS_UPLOAD_EXPIRES_SECONDS, and CRABBOX_ARTIFACTS_URL_EXPIRES_SECONDS. These describe where artifacts go and how long URLs should live.
  • Worker secrets: CRABBOX_ARTIFACTS_ACCESS_KEY_ID, CRABBOX_ARTIFACTS_SECRET_ACCESS_KEY, and optional CRABBOX_ARTIFACTS_SESSION_TOKEN. These are S3-compatible object-store keys used only by the coordinator to sign artifact upload/read URLs.

Our deployed coordinator currently uses R2-compatible storage with public final URLs on https://artifacts.openclaw.ai, bucket openclaw-crabbox-artifacts, and object prefix crabbox-artifacts. The actual R2 access key id and secret access key are Worker secrets; they are not required on developer machines for normal crabbox artifacts publish.

Environment defaults:

CRABBOX_ARTIFACTS_STORAGE
CRABBOX_ARTIFACTS_BUCKET
CRABBOX_ARTIFACTS_PREFIX
CRABBOX_ARTIFACTS_BASE_URL
CRABBOX_ARTIFACTS_AWS_REGION
CRABBOX_ARTIFACTS_AWS_PROFILE
CRABBOX_ARTIFACTS_ENDPOINT_URL
CRABBOX_ARTIFACTS_S3_ACL
CRABBOX_ARTIFACTS_PRESIGN
CRABBOX_ARTIFACTS_EXPIRES

publish --pr uses gh issue comment <pr> --body-file ..., so the current checkout must be authenticated with GitHub. Pass --repo owner/name when the working directory is not inside the target repository.