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

Goal

Run a persistent Pllan Gateway on a GCP Compute Engine VM using Docker, with durable state, baked-in binaries, and safe restart behavior. If you want “Pllan 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 Pllan Gateway in Docker
Persist ~/.pllan + ~/.pllan/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)

Create GCP project + enable Compute Engine API
Create Compute Engine VM (e2-small, Debian 12, 20GB)
SSH into the VM
Install Docker
Clone Pllan repository
Create persistent host directories
Configure .env and docker-compose.yml
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

Install gcloud CLI (or use Console)

Option A: gcloud CLI (recommended for automation)Install from https://cloud.google.com/sdk/docs/installInitialize and authenticate:

gcloud init
gcloud auth login

Option B: Cloud ConsoleAll steps can be done via the web UI at https://console.cloud.google.com

Create a GCP project

CLI:

gcloud projects create my-pllan-project --name="Pllan Gateway"
gcloud config set project my-pllan-project

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

gcloud services enable compute.googleapis.com

Console:

Go to IAM & Admin > Create Project
Name it and create
Enable billing for the project
Navigate to APIs & Services > Enable APIs > search “Compute Engine API” > Enable

Create the VM

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:

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

Console:

Go to Compute Engine > VM instances > Create instance
Name: pllan-gateway
Region: us-central1, Zone: us-central1-a
Machine type: e2-small
Boot disk: Debian 12, 20GB
Create

SSH into the VM

CLI:

gcloud compute ssh pllan-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.

Install Docker (on the VM)

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:

exit

Then SSH back in:

gcloud compute ssh pllan-gateway --zone=us-central1-a

Verify:

docker --version
docker compose version

Clone the Pllan repository

git clone https://github.com/pllan/pllan.git
cd pllan

This guide assumes you will build a custom image to guarantee binary persistence.

Create persistent host directories

Docker containers are ephemeral. All long-lived state must live on the host.

mkdir -p ~/.pllan
mkdir -p ~/.pllan/workspace

Configure environment variables

Create .env in the repository root.

PLLAN_IMAGE=pllan:latest
PLLAN_GATEWAY_TOKEN=change-me-now
PLLAN_GATEWAY_BIND=lan
PLLAN_GATEWAY_PORT=18789

PLLAN_CONFIG_DIR=/home/$USER/.pllan
PLLAN_WORKSPACE_DIR=/home/$USER/.pllan/workspace

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.pllan

Generate strong secrets:

openssl rand -hex 32

Do not commit this file.

Docker Compose configuration

Create or update docker-compose.yml.

services:
  pllan-gateway:
    image: ${PLLAN_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - PLLAN_GATEWAY_BIND=${PLLAN_GATEWAY_BIND}
      - PLLAN_GATEWAY_PORT=${PLLAN_GATEWAY_PORT}
      - PLLAN_GATEWAY_TOKEN=${PLLAN_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:
      - ${PLLAN_CONFIG_DIR}:/home/node/.pllan
      - ${PLLAN_WORKSPACE_DIR}:/home/node/.pllan/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:${PLLAN_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${PLLAN_GATEWAY_BIND}",
        "--port",
        "${PLLAN_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.

Shared Docker VM runtime steps

Use the shared runtime guide for the common Docker host flow:

GCP-specific launch notes

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 (PLLAN_GATEWAY_BIND=lan), configure a trusted browser origin before continuing:

docker compose run --rm pllan-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.

Access from your laptop

Create an SSH tunnel to forward the Gateway port:

gcloud compute ssh pllan-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:

docker compose run --rm pllan-cli dashboard --no-open

Paste the token from that URL.If Control UI shows unauthorized or disconnected (1008): pairing required, approve the browser device:

docker compose run --rm pllan-cli devices list
docker compose run --rm pllan-cli devices approve <requestId>

Need the shared persistence and update reference again? See Docker VM Runtime and 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:

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):

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

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

# Start the VM
gcloud compute instances start pllan-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:

Create a service account:

gcloud iam service-accounts create pllan-deploy \
  --display-name="Pllan Deployment"

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

gcloud projects add-iam-policy-binding my-pllan-project \
  --member="serviceAccount:pllan-deploy@my-pllan-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

Set up messaging channels: Channels
Pair local devices as nodes: Nodes
Configure the Gateway: Gateway configuration

Install overview

Containers

Hosting

Maintenance

GCP

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

Goal

What are we doing (simple terms)?

Quick path (experienced operators)

What you need

Troubleshooting

Service accounts (security best practice)

Next steps

Install overview

Containers

Hosting

Maintenance

​Pllan on GCP Compute Engine (Docker, Production VPS Guide)

​Goal

​What are we doing (simple terms)?

​Quick path (experienced operators)

​What you need

​Troubleshooting

​Service accounts (security best practice)

​Next steps

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

Goal

What are we doing (simple terms)?

Quick path (experienced operators)

What you need

Troubleshooting

Service accounts (security best practice)

Next steps