Skip to content
RemoteClaw

GCP

RemoteClaw on GCP Compute Engine (Docker, Production VPS Guide)

Goal

Run a persistent RemoteClaw Gateway on a GCP Compute Engine VM using Docker, with durable state, baked-in binaries, and safe restart behavior.

If you want “RemoteClaw 24/7 for ~$5-12/mo”, this is a reliable setup on Google Cloud. Pricing varies by machine type and region; pick the smallest VM that fits your workload and scale up if you hit OOMs.

What are we doing (simple terms)?

  • Create a GCP project and enable billing
  • Create a Compute Engine VM
  • Install Docker (isolated app runtime)
  • Start the RemoteClaw Gateway in Docker
  • Persist ~/.remoteclaw + ~/.remoteclaw/workspace on the host (survives restarts/rebuilds)
  • Access the Control UI from your laptop via an SSH tunnel

The Gateway can be accessed via:

  • SSH port forwarding from your laptop
  • Direct port exposure if you manage firewalling and tokens yourself

This guide uses Debian on GCP Compute Engine. Ubuntu also works; map packages accordingly. For the generic Docker flow, see Docker.

Quick path (experienced operators)

  1. Create GCP project + enable Compute Engine API
  2. Create Compute Engine VM (e2-small, Debian 12, 20GB)
  3. SSH into the VM
  4. Install Docker
  5. Clone RemoteClaw repository
  6. Create persistent host directories
  7. Configure .env and docker-compose.yml
  8. Bake required binaries, build, and launch

What you need

  • GCP account (free tier eligible for e2-micro)
  • gcloud CLI installed (or use Cloud Console)
  • SSH access from your laptop
  • Basic comfort with SSH + copy/paste
  • ~20-30 minutes
  • Docker and Docker Compose
  • Model auth credentials
  • Optional provider credentials
    • WhatsApp QR
    • Telegram bot token
    • Gmail OAuth
**Option A: gcloud CLI** (recommended for automation) 
Install from [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)


Initialize and authenticate:


```bash
gcloud init
gcloud auth login
```


**Option B: Cloud Console**


All steps can be done via the web UI at [https://console.cloud.google.com](https://console.cloud.google.com)
 **CLI:** 
```bash
gcloud projects create my-remoteclaw-project --name="RemoteClaw Gateway"
gcloud config set project my-remoteclaw-project
```


Enable billing at [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (required for Compute Engine).


Enable the Compute Engine API:


```bash
gcloud services enable compute.googleapis.com
```


**Console:**


1. Go to IAM & Admin > Create Project
2. Name it and create
3. Enable billing for the project
4. Navigate to APIs & Services > Enable APIs > search "Compute Engine API" > Enable
 **Machine types:** 
| Type      | Specs                    | Cost               | Notes                                        |
| --------- | ------------------------ | ------------------ | -------------------------------------------- |
| e2-medium | 2 vCPU, 4GB RAM          | ~$25/mo            | Most reliable for local Docker builds        |
| e2-small  | 2 vCPU, 2GB RAM          | ~$12/mo            | Minimum recommended for Docker build         |
| e2-micro  | 2 vCPU (shared), 1GB RAM | Free tier eligible | Often fails with Docker build OOM (exit 137) |


**CLI:**


```bash
gcloud compute instances create remoteclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=20GB \
  --image-family=debian-12 \
  --image-project=debian-cloud
```


**Console:**


1. Go to Compute Engine > VM instances > Create instance
2. Name: `remoteclaw-gateway`
3. Region: `us-central1`, Zone: `us-central1-a`
4. Machine type: `e2-small`
5. Boot disk: Debian 12, 20GB
6. Create
 **CLI:** 
```bash
gcloud compute ssh remoteclaw-gateway --zone=us-central1-a
```


**Console:**


Click the "SSH" button next to your VM in the Compute Engine dashboard.


Note: SSH key propagation can take 1-2 minutes after VM creation. If connection is refused, wait and retry.
 ```bash sudo apt-get update sudo apt-get install -y git curl ca-certificates curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USER ``` 
Log out and back in for the group change to take effect:


```bash
exit
```


Then SSH back in:


```bash
gcloud compute ssh remoteclaw-gateway --zone=us-central1-a
```


Verify:


```bash
docker --version
docker compose version
```
 ```bash git clone https://github.com/remoteclaw/remoteclaw.git cd remoteclaw ``` 
This guide assumes you will build a custom image to guarantee binary persistence.
 Docker containers are ephemeral. All long-lived state must live on the host. 
```bash
mkdir -p ~/.remoteclaw
mkdir -p ~/.remoteclaw/workspace
```
 Create `.env` in the repository root. 
```bash
REMOTECLAW_IMAGE=remoteclaw:latest
REMOTECLAW_GATEWAY_TOKEN=change-me-now
REMOTECLAW_GATEWAY_BIND=lan
REMOTECLAW_GATEWAY_PORT=18789


REMOTECLAW_CONFIG_DIR=/home/$USER/.remoteclaw
REMOTECLAW_WORKSPACE_DIR=/home/$USER/.remoteclaw/workspace


GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.remoteclaw
```


Generate strong secrets:


```bash
openssl rand -hex 32
```


**Do not commit this file.**
 Create or update `docker-compose.yml`. 
```yaml
services:
  remoteclaw-gateway:
    image: ${REMOTECLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - REMOTECLAW_GATEWAY_BIND=${REMOTECLAW_GATEWAY_BIND}
      - REMOTECLAW_GATEWAY_PORT=${REMOTECLAW_GATEWAY_PORT}
      - REMOTECLAW_GATEWAY_TOKEN=${REMOTECLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${REMOTECLAW_CONFIG_DIR}:/home/node/.remoteclaw
      - ${REMOTECLAW_WORKSPACE_DIR}:/home/node/.remoteclaw/workspace
    ports:
      # Recommended: keep the Gateway loopback-only on the VM; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${REMOTECLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${REMOTECLAW_GATEWAY_BIND}",
        "--port",
        "${REMOTECLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]
```


`--allow-unconfigured` is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (`gateway.auth.token` or password) and use safe bind settings for your deployment.
 Use the shared runtime guide for the common Docker host flow: 
- [Bake required binaries into the image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build and launch](/install/docker-vm-runtime#build-and-launch)
- [What persists where](/install/docker-vm-runtime#what-persists-where)
- [Updates](/install/docker-vm-runtime#updates)
 On GCP, if build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory. Use `e2-small` minimum, or `e2-medium` for more reliable first builds. 
When binding to LAN (`REMOTECLAW_GATEWAY_BIND=lan`), configure a trusted browser origin before continuing:


```bash
docker compose run --rm remoteclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json
```


If you changed the gateway port, replace `18789` with your configured port.
 Create an SSH tunnel to forward the Gateway port: 
```bash
gcloud compute ssh remoteclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
```


Open in your browser:


`http://127.0.0.1:18789/`


Fetch a fresh tokenized dashboard link:


```bash
docker compose run --rm remoteclaw-cli dashboard --no-open
```


Paste the token from that URL.


If Control UI shows `unauthorized` or `disconnected (1008): pairing required`, approve the browser device:


```bash
docker compose run --rm remoteclaw-cli devices list
docker compose run --rm remoteclaw-cli devices approve <requestId>
```


Need the shared persistence and update reference again?
See [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where) and [Docker VM Runtime updates](/install/docker-vm-runtime#updates).

Troubleshooting

SSH connection refused

SSH key propagation can take 1-2 minutes after VM creation. Wait and retry.

OS Login issues

Check your OS Login profile:

Terminal window
gcloud compute os-login describe-profile

Ensure your account has the required IAM permissions (Compute OS Login or Compute OS Admin Login).

Out of memory (OOM)

If Docker build fails with Killed and exit code 137, the VM was OOM-killed. Upgrade to e2-small (minimum) or e2-medium (recommended for reliable local builds):

Terminal window
# Stop the VM first
gcloud compute instances stop remoteclaw-gateway --zone=us-central1-a


# Change machine type
gcloud compute instances set-machine-type remoteclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small


# Start the VM
gcloud compute instances start remoteclaw-gateway --zone=us-central1-a

Service accounts (security best practice)

For personal use, your default user account works fine.

For automation or CI/CD pipelines, create a dedicated service account with minimal permissions:

  1. Create a service account:

    Terminal window
    gcloud iam service-accounts create remoteclaw-deploy \
      --display-name="RemoteClaw Deployment"

  2. Grant Compute Instance Admin role (or narrower custom role):

    Terminal window
    gcloud projects add-iam-policy-binding my-remoteclaw-project \
      --member="serviceAccount:remoteclaw-deploy@my-remoteclaw-project.iam.gserviceaccount.com" \
      --role="roles/compute.instanceAdmin.v1"

Avoid using the Owner role for automation. Use the principle of least privilege.

See https://cloud.google.com/iam/docs/understanding-roles for IAM role details.

Next steps