Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.remotemux.com/llms.txt

Use this file to discover all available pages before exploring further.

Use backend=gcp when you want the RemoteMux control plane to provision into your own GCP project.

​
What This Backend Does

  1. Authenticates to the RemoteMux control plane with rmux login
  2. Validates your GCP credentials, project settings, and required APIs/permissions
  3. Creates one Compute Engine VM per environment
  4. Uses gcloud compute ssh --tunnel-through-iap for attach and remote commands
The control plane owns orchestration and state for the environment lifecycle.

​
Prerequisites

  • gcloud CLI installed
  • Either an authenticated gcloud session or a credential file when gcp.authMode=credentials-file
  • Compute Engine API and IAP API enabled in the target project
  • A project ID and zone for the VM
  • A VPC network (optionally with a subnetwork)

​
Configure

cd /path/to/project
rmux login
rmux configure \
  --backend gcp \
  --gcp-project-id YOUR_PROJECT \
  --gcp-zone us-central1-a
In gcloud-cli mode, interactive rmux configure --backend gcp validates the current gcloud auth state first and can seed the project, region, and zone from your local gcloud config. Full configuration: 
rmux configure \
  --backend gcp \
  --gcp-project-id rmux-dev \
  --gcp-zone us-central1-a \
  --gcp-network default \
  --gcp-subnetwork default-us-central1 \
  --gcp-machine-type e2-standard-4
Credential-file setup for CI or non-interactive environments: 
rmux configure \
  --backend gcp \
  --gcp-auth-mode credentials-file \
  --gcp-project-id rmux-dev \
  --gcp-zone us-central1-a \
  --gcp-credentials-file /path/to/service-account.json \
  --gcp-impersonate-service-account deployer@rmux-dev.iam.gserviceaccount.com
gcp.projectId is required. gcp.zone is required in practice, and RemoteMux derives gcp.region from it when you do not set one explicitly. gcp.authMode defaults to gcloud-cli; use credentials-file when you want gcloud commands to initialize from a service-account JSON key or another gcloud auth login --cred-file credential file. gcp.impersonateServiceAccount is optional and applies to all gcloud operations RemoteMux runs.

​
Validate

rmux gcp-check
This read-only check validates:
  1. Usable GCP credentials and the active gcloud account when applicable
  2. Project access and project number
  3. Compute Engine and IAP API enablement
  4. Zone reachability and machine-type availability
  5. Network and subnetwork existence
  6. Base image availability
  7. Default Compute Engine service-account resolution
  8. Required project and service-account permissions when IAM permission probing is reachable

​
Create and Use

rmux env new
rmux workspace new main
rmux workspace attach

​
Editor Access

Open workspaces in VS Code or Cursor: 
rmux workspace code main
rmux workspace cursor server
RemoteMux uses gcloud compute config-ssh to seed the local SSH key and then writes an IAP-backed host alias under ~/.ssh/rmux/config. See Editor Access for details.

​
Port Exposure

GCP BYOC exposed ports currently return direct public-IP URLs such as http://PUBLIC_IP:3000. Private previews and preview share links are currently available only on Managed and E2B environments. RemoteMux does not currently provision preview-domain ingress for backend=gcp, so gcp.previewDomain is reserved for future work and is not used for live port URLs today.
Last modified on April 9, 2026