Operations

Your own domain and multiple deployments

Set KG_HOST=kode-gopher.example.com, and create a DNS A record pointing it at the ADDRESS_NAME (default kode-gopher-ip) address.

Do this before the first deploy, because the certificate (CERT_NAME, default kode-gopher-cert) is issued for whatever hostname the script sees first. To change the hostname on an existing deployment, delete its certificate (gcloud compute ssl-certificates delete kode-gopher-cert --global), then redeploy with KG_HOST. Under Google sign-in the issuer URL and vault continue URI change with the hostname, so update the OAuth client’s redirect URI and the vault auth provider’s --three-legged-oauth-default-continue-uri as well.

To run more than one kode-gopher deployment in the same GCP project (for example a staging cluster and a production cluster), pass distinct ADDRESS_NAME, CERT_NAME and (under Google sign-in) VAULT_AUTH_PROVIDER values for each deployment.

Test a deployment

scripts/smoketest-http.sh reads the auth mode from the Deployment, and checks everything that doesn’t need a browser:

• Both modes: a 401 without a valid token.
• Static token: a full MCP session, in which a snippet gets its token from the metadata emulator with no ADC file in the sandbox.
• Google sign-in: discovery metadata, client registration, and every refusal path of /authorize and /token.
• With --client-credentials <file>: a full session as that client’s service account.

Use --port-forward before the certificate is ACTIVE.

Upgrade

Rerun the deploy script, with a new IMAGE if you pin one. It keeps the Secrets, the IP and the certificate. The sandbox image is pinned in manifests/overlays/gke, so pulling a newer checkout updates it too.

The warm pool doesn’t pick up a new sandbox image on its own: agent-sandbox keeps the existing unclaimed sandboxes. So when they run an older image than the template, the deploy script replaces them (scripts/refresh-warm-pool.sh) and waits for one on the new image. Sessions already holding a sandbox keep theirs until they end. To refresh by hand, run scripts/refresh-warm-pool.sh.

Limits and behavior

• Sessions: one MCP session holds one sandbox. Idle sessions end after 15 minutes, and each user may hold 2 sandboxes at once.
• Crash cleanup: sandbox claims carry a 10-minute lease that kode-gopher renews, so if the server dies, its sandboxes are cleaned up.
• One replica: sessions and the token replay cache live in memory. A restart ends open MCP sessions, which clients reopen, and forgets the replay cache.
• Tokens:
  • kode-gopher access tokens last up to 15 minutes;
  • refresh tokens last 30 days, renewed by each use;
  • authorization codes last 1 minute.
• Network:
  • sandboxes may reach DNS and, on port 443, only the egress allowlist (see Sandbox isolation); add hosts with EGRESS_ALLOW;
  • kode-gopher’s own egress is limited to DNS, the sandboxes, the API server, the GKE metadata server and public HTTPS (it fetches clients’ metadata documents from anywhere);
  • its ingress is limited to Google’s load balancer ranges;
  • the sandbox router accepts no in-cluster traffic at all.
• Front-end timeout: keep any proxy or load balancer in front of kode-gopher at a request timeout of at least 2 minutes. Under vault custody, a token refresh or sign-in can wait out a nearly spent Google token for up to about 93 seconds before answering, and a client that gets a 504 instead may start a new browser sign-in. The GKE Gateway the deploy script creates allows 900 seconds; a load balancer’s default is often 30 or 60.
• Secret changes: kode-gopher reads its Secret at startup. The deploy script restarts it whenever the Secret changes: a new token, CLIENTS_FILE or Google client file.

Logs

kubectl -n codemode logs deployment/kode-gopher

kode-gopher never logs tokens or secrets.

Remove it

kubectl -n codemode delete gateway kode-gopher   # first, so the load balancer releases the IP and certificate
kubectl delete -k manifests/overlays/gke-server
kubectl -n codemode delete secret kode-gopher-token kode-gopher-oauth --ignore-not-found
gcloud compute addresses delete kode-gopher-ip --global
gcloud compute ssl-certificates delete kode-gopher-cert --global

Also remove the IAM grants you made to kode-gopher’s principal. Those grants belong to the project’s Workload Identity pool, not the cluster: a future codemode/kode-gopher service account in any cluster of the project would inherit them. If you’re done with them, also remove the OAuth client’s redirect URI and the vault auth provider.