> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-magi-remove-two-ai-catalog-items.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @hyperframes/gcp-cloud-run

> Google Cloud Run and Workflows adapter for distributed HyperFrames rendering.

The GCP Cloud Run package runs HyperFrames' distributed render primitives on Google Cloud. It ships a Cloud Run HTTP service, a Node client SDK, and a Terraform module for provisioning the bucket, service, workflow, and service accounts.

```bash theme={null}
npm install @hyperframes/gcp-cloud-run
```

## When to Use

**Use `@hyperframes/gcp-cloud-run` when you need to:**

* Render large compositions on Google Cloud infrastructure
* Orchestrate `plan`, `renderChunk`, and `assemble` through Cloud Workflows
* Store project archives, chunk outputs, and final videos in GCS
* Deploy the renderer as a Cloud Run service with a pinned Chrome runtime
* Drive renders from CI, a backend service, or custom internal tooling

**Use a different package if you want to:**

* Render locally or inside a single Node process - use the [CLI](/packages/cli) or [producer](/packages/producer)
* Run the same distributed model on AWS - use [aws-lambda](/packages/aws-lambda)
* Build or edit composition HTML - use [studio](/packages/studio), [sdk](/packages/sdk), or [core](/packages/core)

<Tip>
  Cloud Run uses a container image, so it avoids Lambda ZIP-size pressure and can install the same pinned `chrome-headless-shell` runtime used by the standard renderer.
</Tip>

## Package Exports

| Import                              | Description                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `@hyperframes/gcp-cloud-run`        | Server handler, event types, GCS transport, and client SDK exports                                |
| `@hyperframes/gcp-cloud-run/server` | Cloud Run HTTP service entry point                                                                |
| `@hyperframes/gcp-cloud-run/sdk`    | Lightweight Node SDK for deploying sites, starting renders, polling progress, and estimating cost |

The published package also includes `terraform/` and a `Dockerfile` for deployment.

## Architecture

Cloud Workflows invokes one Cloud Run service with different `Action` values:

<Steps>
  <Step title="Plan">
    Downloads the project archive from GCS, runs the producer planner, and uploads the plan directory.
  </Step>

  <Step title="Render chunks">
    Cloud Workflows runs parallel `renderChunk` calls against the Cloud Run service. Each request renders one chunk and uploads it to GCS.
  </Step>

  <Step title="Assemble">
    Downloads all chunks and audio assets, assembles the deliverable, and uploads the final file.
  </Step>
</Steps>

The service is intentionally close to the AWS Lambda adapter: thin cloud transport around the same `@hyperframes/producer/distributed` primitives.

## Deploying

Build and push the container, then apply the Terraform module:

```bash theme={null}
gcloud builds submit . \
  --tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG

terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
  -var project_id=PROJECT \
  -var region=us-central1 \
  -var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
```

Terraform outputs the bucket name, service URL, workflow name, and region needed by the SDK.

## Using the SDK

```typescript theme={null}
import { getRenderProgress, renderToCloudRun } from "@hyperframes/gcp-cloud-run/sdk";

const handle = await renderToCloudRun({
  projectDir: "./my-composition",
  config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
  bucketName: "hyperframes-render-my-project",
  projectId: "my-project",
  location: "us-central1",
  workflowId: "hyperframes-render",
  serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
});

let progress = await getRenderProgress({ executionName: handle.executionName });
while (progress.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  progress = await getRenderProgress({ executionName: handle.executionName });
}

console.log(progress.status, progress.outputFile, progress.costs.displayCost);
```

Plan v2 is the default because workers fetch manifest-selected
content-addressed artifacts. The SDK sends explicit v2 when `planProtocol` is
omitted. Deprecated v1 compatibility remains available by passing
`planProtocol: "v1"`.

<Warning>
  For an existing installation, pause new renders and drain active workflow
  executions. Redeploy the Cloud Run image and Cloud Workflows definition from
  the same package version before upgrading the application SDK. Older
  workflows may default omission to v1 or lack v2 support.
</Warning>

Pass `projectDir` for one-shot uploads, or call `deploySite()` separately and reuse the returned site handle across many renders.

## Related topics

<CardGroup cols={2}>
  <Card title="GCP Cloud Run Deployment" icon="cloud" href="/deploy/gcp-cloud-run">
    End-to-end deployment details and smoke-test notes.
  </Card>

  <Card title="@hyperframes/producer" icon="video" href="/packages/producer">
    The distributed primitives that the Cloud Run service executes.
  </Card>
</CardGroup>