@computesdk/cloud-run

Google Cloud Run Sandboxes provider for ComputeSDK.

Cloud Run Sandboxes are currently in beta and require your GCP project to be allow-listed by the Cloud Run team.

This package supports two modes:

• Remote mode: deploy a gateway Cloud Run service with npx @computesdk/cloud-run, then connect using CLOUD_RUN_SANDBOX_URL and CLOUD_RUN_SANDBOX_SECRET.
• Direct mode: run your app inside a Cloud Run service deployed with --sandbox-launcher, then call the in-container sandbox CLI at /usr/local/gcp/bin/sandbox.

Install

npm install @computesdk/cloud-run

Setup Remote Gateway

Set your GCP project and region, then run the setup command:

export CLOUD_RUN_PROJECT_ID="your-gcp-project"
export CLOUD_RUN_REGION="us-central1"

npx @computesdk/cloud-run

The setup command uses gcloud to:

• Build a small ComputeSDK gateway container.
• Deploy it to Cloud Run with --sandbox-launcher and --no-cpu-throttling.
• Configure the gateway for low-latency sandbox execution with 1 CPU, 2Gi memory, concurrency 1, session affinity, CPU boost, and 100 min/max instances.
• Allow unauthenticated Cloud Run invocation with --allow-unauthenticated.
• Generate a bearer token for gateway authentication.
• Print the runtime environment variables.

By default, the gateway executes each ComputeSDK command with sandbox do. The ComputeSDK sandbox object is a logical handle used to carry configuration such as environment variables and working directory between calls. Set executionMode: 'stateful' to use sandbox run, sandbox exec, and sandbox delete for persistent sandbox sessions.

Execution mode controls how SDK methods map to the Cloud Run sandbox CLI:

| SDK method | Ephemeral mode (default) | Stateful mode | |---|---|---| | create() | Creates a local logical handle only | Calls sandbox run <id> --detach | | runCommand() | Calls sandbox do -- /bin/sh -c <command> | Calls sandbox exec <id> -- /bin/sh -c <command> | | destroy() | Removes local bookkeeping only | Calls sandbox delete <id> | | filesystem | Runs each operation with sandbox do | Runs each operation with sandbox exec <id> |

Add the printed values to your app environment:

CLOUD_RUN_SANDBOX_URL=https://computesdk-sandbox-...run.app
CLOUD_RUN_SANDBOX_SECRET=...

Prerequisites:

• Your GCP project is allow-listed for Cloud Run Sandboxes.
• gcloud is installed, up to date, and authenticated.
• Cloud Build and Cloud Run APIs are enabled for the project.
• Your organization policy allows public Cloud Run invokers, or callers must provide CLOUD_RUN_AUTH_TOKEN.

Public Gateway Access

The remote gateway is designed to be public at the Cloud Run layer and protected by CLOUD_RUN_SANDBOX_SECRET for sandbox operations. Public Cloud Run access avoids requiring each SDK caller to mint a Google identity token.

The setup command passes --allow-unauthenticated. If your organization blocks public IAM members with constraints/iam.allowedPolicyMemberDomains, the deploy can succeed with an IAM warning but the service will still require Cloud Run IAM auth. In that case, either allow allUsers as roles/run.invoker for this gateway service or set CLOUD_RUN_AUTH_TOKEN to a Google-signed identity token for the gateway URL.

Manual Direct Deploy

Deploy your service with the sandbox launcher enabled:

gcloud beta run deploy my-sandbox-service \
  --image=gcr.io/$PROJECT_ID/my-sandbox-service:latest \
  --region=$REGION \
  --project=$PROJECT_ID \
  --sandbox-launcher \
  --no-cpu-throttling

The sandbox binary is only available in Cloud Run containers with --sandbox-launcher enabled.

Remote Usage

import { cloudRun } from '@computesdk/cloud-run'

const compute = cloudRun({
  sandboxUrl: process.env.CLOUD_RUN_SANDBOX_URL,
  sandboxSecret: process.env.CLOUD_RUN_SANDBOX_SECRET,
})

const sandbox = await compute.sandbox.create()

const result = await sandbox.runCommand('echo hello')
console.log(result.stdout)

await sandbox.destroy()

Stateful Execution

import { cloudRun } from '@computesdk/cloud-run'

const compute = cloudRun({
  sandboxUrl: process.env.CLOUD_RUN_SANDBOX_URL,
  sandboxSecret: process.env.CLOUD_RUN_SANDBOX_SECRET,
  executionMode: 'stateful',
  write: true,
})

const sandbox = await compute.sandbox.create()
await sandbox.runCommand('echo hello > /tmp/hello.txt')
const result = await sandbox.runCommand('cat /tmp/hello.txt')
console.log(result.stdout)
await sandbox.destroy()

Direct Usage

import { cloudRun } from '@computesdk/cloud-run'

const compute = cloudRun({
  persistDir: '/tmp/cloud-run-sandbox',
  write: true,
})

const sandbox = await compute.sandbox.create({
  envs: { NODE_ENV: 'production' },
})

const result = await sandbox.runCommand('echo hello')
console.log(result.stdout)

await sandbox.destroy()

Configuration

| Option | Env var | Default | Description | |---|---|---|---| | sandboxUrl | CLOUD_RUN_SANDBOX_URL | | URL of deployed gateway service for remote mode | | sandboxSecret | CLOUD_RUN_SANDBOX_SECRET | | Bearer token for deployed gateway service | | gatewayAuthToken | CLOUD_RUN_AUTH_TOKEN | | Optional Google identity token when Cloud Run IAM auth is enabled | | executionMode | | ephemeral | Use ephemeral for sandbox do or stateful for sandbox run/exec/delete | | sandboxBinary | CLOUD_RUN_SANDBOX_BINARY | /usr/local/gcp/bin/sandbox | Path to the Cloud Run sandbox CLI | | mode | | CLI default | Sandbox CLI mode, local or container | | allowEgress | | false | Allow sandbox network egress | | rootfs | | / | Root filesystem exposed to sandboxes | | workdir | | CLI default | Default working directory | | template | | | Cloud Run container template name | | persistDir | | | Host path used for persistent filesystem state | | overlayDir | | | Writable overlay directory | | write | | false | Allow mounted filesystems to be writable | | mounts | | [] | Bind mounts passed to --mount | | env | | {} | Environment variables for new sandbox sessions | | globalArgs | | [] | Extra CLI global args | | runArgs | | [] | Extra args for sandbox do and sandbox run | | execArgs | | [] | Extra args for sandbox exec in stateful mode |

Notes

Commands use ephemeral sandbox do execution by default. Filesystem writes are only preserved when your Cloud Run sandbox CLI configuration supports host-backed persistence such as --persist-dir. Use executionMode: 'stateful' when you need a detached sandbox session created with sandbox run and reused with sandbox exec.

getUrl() is not supported because the current Cloud Run sandbox CLI does not expose per-sandbox ports.

CI with Workload Identity Federation

When Cloud Run IAM auth is enabled, CI needs a Google-signed ID token for the gateway URL. Some federated credentials cannot use gcloud auth print-identity-token directly; use IAM Credentials generateIdToken with a federated access token instead:

ACCESS_TOKEN="$(gcloud auth print-access-token)"
SERVICE_URL="$(gcloud run services describe computesdk-sandbox --region=$CLOUD_RUN_REGION --project=$CLOUD_RUN_PROJECT_ID --format='value(status.url)')"

CLOUD_RUN_AUTH_TOKEN="$(node -e '
const [accessToken, audience, serviceAccount] = process.argv.slice(1)
fetch(`https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${serviceAccount}:generateIdToken`, {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ audience, includeEmail: true }),
}).then(r => r.json()).then(j => process.stdout.write(j.token))
' "$ACCESS_TOKEN" "$SERVICE_URL" "$CLOUD_RUN_SERVICE_ACCOUNT")"

The federated principal must be allowed to impersonate CLOUD_RUN_SERVICE_ACCOUNT and mint OpenID tokens for it.