> ## 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.

# GCP BYOC

> Configure RemoteMux to provision into your own GCP project.

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env new
rmux workspace new main
rmux workspace attach
```

## Editor Access

Open workspaces in VS Code or Cursor:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/guides/editors) 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.