Google Cloud

Connect

portal connect gcp --from-cli --project my-project

--from-cli uses your gcloud login. It prints every step and asks before it makes anything: a service account for Portal with the roles it needs, and either a keyless binding to Portal's own identity (when Portal offers one) or a service account key, which is sealed on Portal's side and never shown again. --keys asks for the key even when keyless binding is offered, and --federated asks for keyless binding and fails when it is not offered. The default region is us-central1; set another with --region.

To use a key you already have, pass the service account JSON file:

portal connect gcp --file key.json

or paste it on the console's Connect page.

The project needs the Compute Engine API. --from-cli turns it on; a pasted key turns it on too when its service account may enable services (Owner, Editor or Service Usage Admin), and the save waits for Google to finish. A key that may not is refused with the project named and the page that enables the API; enable it there, then connect again.

Networks

By default Portal uses a network of its own in your project that admits no inbound traffic; its nodes only dial out. To use an existing network instead:

External IPs

Each VM gets an ephemeral external IP by default. It is how the VM reaches Portal, installs packages and saves checkpoints: Portal's VMs only dial out. Many organizations deny VMs external IPs with the organization policy constraints/compute.vmExternalIpAccess, or its managed form constraints/compute.managed.vmExternalIpAccess, and new organizations often deny them all from the start. Google Cloud then refuses every VM with "Constraint constraints/compute.vmExternalIpAccess violated".

When you connect without --private-network or --no-private-network, Portal reads the project's effective policy:

Reading the policy needs the permission orgpolicy.policy.get and the Organization Policy API (orgpolicy.googleapis.com). --from-cli reads it with your gcloud login; when that API or Compute Engine is off, the plan turns them on first and reads the policy before it makes anything else. Portal reads it again with the connection's own role, which has orgpolicy.policy.get and compute.routers.list. A connection made before October 31, 2026 gets both by connecting again with portal connect gcp --from-cli, which updates the role.

To give the VMs a way out without external IPs, create a Cloud Router and Cloud NAT in the connection's region, then connect with --private-network:

gcloud compute routers create portal-nat-router --project=PROJECT --region=REGION --network=soma-net
gcloud compute routers nats create portal-nat --project=PROJECT --region=REGION --router=portal-nat-router --auto-allocate-nat-external-ips --nat-custom-subnet-ip-ranges=soma-net
portal connect gcp --from-cli --private-network --project PROJECT --region REGION

When Portal's network soma-net does not exist yet, create it first, the way Portal makes it:

gcloud compute networks create soma-net --project=PROJECT --subnet-mode=auto --description=soma:managed=true

With your own network (--network), put its name in place of soma-net, and its subnetwork's name in --nat-custom-subnet-ip-ranges. Google Cloud bills Cloud NAT; quotes leave it out.

The other way out: an organization policy administrator allows external IPs on the project. Portal never changes an organization policy.

If a launch still meets the policy, for a connection made before Portal checked it or a policy set later, the job's events carry the same commands (portal explain JOB), and Portal tries the job's next offer when it has one.

Machines

Notices and lifetime

Portal asks for Compute Engine's 120 s preemption notice on spot VMs, and Portal's node on the VM watches the metadata server for it. On a notice Portal checkpoints and suspends the job. GPU VMs that are not spot also watch for host maintenance that would stop them.

Every VM is created with a termination time, 24 hours after it starts by default, so a VM cannot outlive it. An Owner can change it in the console's Settings (gcp_max_run_h). See Settings.