Google Cloud Run

Deploy distributed HyperFrames rendering to Cloud Run, Cloud Workflows, and Google Cloud Storage.

Use this path when renders must run in your Google Cloud account. A Cloud Workflow plans the render, sends chunks to Cloud Run in parallel, and assembles the result in Google Cloud Storage.

Cloud Workflow: Plan → Render chunks in parallel → Assemble
                         ↓
                  Cloud Run service
                         ↓
                         GCS

For a hosted render without infrastructure ownership, use HyperFrames Cloud. For a small preview application and render endpoint, use a hosted template.

Prerequisites

• A Google Cloud project with billing enabled
• gcloud authenticated for that project
• Terraform 1.5 or newer
• Cloud Build access, or an existing compatible container image
• @hyperframes/gcp-cloud-run installed alongside the CLI

The CLI can build the renderer automatically when it runs from a HyperFrames repository checkout. Outside the repository, pass an image built from packages/gcp-cloud-run/Dockerfile with --image.

Deploy

hyperframes cloudrun deploy --project my-gcp-project

The command enables the required Google Cloud APIs, builds and pushes the renderer when needed, applies the bundled Terraform module, and stores the resulting bucket, service URL, and workflow name in ~/.hyperframes/.

The default region is us-central1. Machine and scaling controls include --region, --cpu, --memory, --max-instances, and --timeout.

Render

Width and height describe the authored canvas. Use --output-resolution when the encoded result should be supersampled without changing the layout.

hyperframes cloudrun render ./my-project \
  --width 1920 \
  --height 1080 \
  --wait

The command accepts the same template variables used by local and AWS renders:

hyperframes cloudrun render ./card-template \
  --width 1920 \
  --height 1080 \
  --variables '{"name":"Ada"}' \
  --wait

Supported distributed outputs are MP4, MOV, WebM, and PNG sequences. MP4 can use H.264 or H.265. Distributed rendering is currently SDR-only.

Reuse an upload

Projects are content-addressed. Upload an unchanged project once, then reuse its site ID for later renders:

hyperframes cloudrun sites create ./my-project

Use render-batch with a JSONL file when one template needs many sets of variables:

hyperframes cloudrun render-batch ./card-template \
  --batch ./recipients.jsonl \
  --width 1920 \
  --height 1080 \
  --max-concurrent 10

Each JSONL row contains an output key and optional variables:

{"outputKey":"renders/ada.mp4","variables":{"name":"Ada"}}

Progress and teardown

Without --wait, a render returns its workflow execution name immediately.

hyperframes cloudrun progress <execution-name>
hyperframes cloudrun destroy --project my-gcp-project

destroy removes the Terraform-managed stack and its render bucket. Download anything that must be retained before running it.

Programmatic use

@hyperframes/gcp-cloud-run/sdk exposes deploySite, renderToCloudRun, and getRenderProgress for Node backends. The package also exports the Terraform module and HTTP handler used by the deployed service.

See the GCP package reference for the SDK contract and the complete infrastructure shape.