Skip to main content

​
GCP BYOC Guide

Use backend=gcp when you want rmux to talk directly to your own GCP project.

​
What This Backend Does

With the GCP backend, rmux:
  1. validates your active gcloud identity and resolved project settings
  2. creates one Compute Engine devbox VM per environment
  3. syncs your project into /workspace
  4. uses gcloud compute ssh for attach and remote command flows
  5. uses gcloud compute scp for directory sync
There is no RMUX control plane requirement for this mode.

​
Prerequisites

You should have:
  1. a GCP project you control
  2. the gcloud CLI installed and authenticated
  3. Compute Engine API enabled in the target project
  4. a project ID and zone for the devbox VM
  5. a VPC network, and optionally a subnetwork, if you are not using the default network

​
Configure The Backend

The shortest setup path is: 
cd /path/to/project
rmux configure \
  --backend gcp \
  --gcp-project-id rmux-dev \
  --gcp-zone us-central1-a
You can also set the full network and machine configuration explicitly: 
rmux configure \
  --backend gcp \
  --gcp-project-id rmux-dev \
  --gcp-region us-central1 \
  --gcp-zone us-central1-a \
  --gcp-network default \
  --gcp-subnetwork default-us-central1 \
  --gcp-machine-type e2-standard-4 \
  --gcp-preview-domain preview.example.com
gcp.projectId is required. gcp.zone is also required in practice, though rmux can derive the region from it if you omit gcp.region.

​
Validate GCP Setup

Run: 
rmux gcp-check
This check is read-only. It validates:
  1. the active gcloud account
  2. project access and project number resolution
  3. Compute Engine API enablement
  4. zone reachability
  5. network existence
  6. optional subnetwork existence
  7. default Compute Engine service-account resolution
It does not create temporary resources to prove create or delete permissions.

​
Create And Use The Environment

rmux new
rmux session ls
rmux session new -s agent-a
rmux session attach -t agent-a
Run commands remotely without attaching: 
rmux session run -t agent-a bun install
rmux session run -t agent-a bun test

​
Attach And Sync Model

The current GCP path is SSH-based:
  1. attach and remote commands use gcloud compute ssh
  2. rmux env sync copies the current directory with gcloud compute scp
  3. the runtime does not use a gcp.workspaceBucket
That makes the GCP runtime different from AWS and managed, which stage sync archives through S3-backed flows.

​
Useful Commands

rmux gcp-check
rmux env status
rmux env sync
rmux env down
rmux env destroy
rmux usage
Last modified on March 19, 2026