Skip to main content
Nuphos never stores a service account key. To connect, you create a connector service account in your project and let Nuphos impersonate it, minting short-lived access tokens that expire after about an hour. The agent can then inspect and operate your Google Cloud resources: GKE, Compute Engine, Cloud Run, VPCs, firewalls, IAM, and more.
Connecting a project requires the Administrator role on your team. See the IAM trust model for the security design behind this flow.

​
Connect

In your GCP project you:
  1. Enable the Cloud Resource Manager and IAM APIs.
  2. Create a connector service account (nuphos-connector).
  3. Grant it permission to manage your project.
  4. Grant the Nuphos platform service account permission to impersonate it.
Then you enter the connector’s email and your project ID into Nuphos. There are two ways to do this. In Connectors → Connect → GCP, choose the guided path. Nuphos opens an agent session that runs gcloud on your machine and performs the steps below, pausing for your approval, then prints the project ID and connector email for you to paste in.

​
Option B — Manual setup with gcloud

Run these commands yourself, replacing PROJECT_ID with your project:
1

Enable the required APIs

2

Create the connector service account

3

Let the connector manage your project

roles/iam.infrastructureAdmin lets the connector discover and manage infrastructure (and enable additional APIs on demand). Scope it down later if your team requires tighter permissions.
4

Let Nuphos impersonate the connector

Grant the Nuphos platform service account the Service Account Token Creator role on the connector — this is what allows impersonation:
zeabur-byos-connector@zeabur-system.iam.gserviceaccount.com is the Nuphos platform identity. It is not a secret — it appears in every customer’s policy. Use it exactly as shown.
5

Enter the details into Nuphos

In the GCP binding dialog, enter:
  • Service account email: nuphos-connector@PROJECT_ID.iam.gserviceaccount.com
  • Project ID: PROJECT_ID
Unlike AWS, GCP connections are not verified at bind time. If the impersonation grant or project ID is wrong, the connection saves but fails the first time the agent uses it. Double-check the grant in step 4.

​
In the Nuphos app

Once the project is connected, Nuphos discovers what’s in it and turns it into browsable surfaces:
  • Kubernetes clusters — your GKE clusters appear with workloads, networking, config, storage, and RBAC. Open a pod terminal, stream logs, and act on resources in bulk — no kubeconfig wrangling.
  • Compute & access — Compute Engine instances with status and metrics, Cloud Run services and revisions, an SSH terminal to any VM, and port forwarding into private networks.
  • Cloud resources — VPCs, firewall rules, and the networking picture around your compute.

​
What the agent can do for you

The agent uses the same access to investigate and operate on your behalf. Ask it things like:
  • “Why is the checkout deployment on GKE crash-looping?” — it reads events, logs, and config across the cluster and walks you to the cause.
  • “Which firewall rule is blocking traffic to api-internal?” — it traces services, firewall rules, and routes together.
  • “Scale the staging node pool down over the weekend” — it proposes a plan with steps and risk for you to approve, then executes it.
When the connector’s role hits a permission wall, the agent can propose a narrow permission grant for an Administrator to approve instead of just stopping.

​
Permissions & authorization

Two boundaries govern what happens through this connector:
  • Hard boundary — who can use it. Only team Administrators can bind or remove the project, and they can restrict it to specific members with a member allow-list. Within a session the agent only holds credentials for projects you explicitly selected, and the allow-list is re-checked on every credential request.
  • Soft boundary — what the agent may do with it. Reads run freely, but changes go through plan approvals, and at the command level Auto-authorization decides which gcloud/kubectl commands run unattended: read-only ones auto-run, irreversible ones always pause for a human, and your standing rules cover the middle.
The outer limit is the connector service account’s IAM role — the agent can never exceed what you granted it in step 3.

​
How credentials work

​
Good to know

Keep the connector least-privilege and let an administrator widen roles later through admin-approved permission grants, applied by a dedicated permission-admin service account rather than the connector itself.
You can connect multiple GCP projects and give each its own allow-list — keep production tight while the whole team works with staging.