Skip to content
kode-gopher

CLI

This page is the help output of the kode-gopher binary built from the current sources. A test regenerates it and fails CI if it drifts.

Flags take one dash or two (-namespace and --namespace are the same).

kode-gopher

Section titled “kode-gopher”
usage: kode-gopher <subcommand> [flags]


subcommands:
  exec <file.go>  ship a Go file into a sandbox and run it
  serve           start the MCP server (stdio, or streamable HTTP)
  auth <verb>     inspect ambient credentials (verb: status)
  version         print the build version

kode-gopher exec

Section titled “kode-gopher exec”

Runs one Go file in a sandbox and prints the outcome. Useful for checking a cluster setup without an MCP client; see Getting started.

usage: kode-gopher exec [flags] <file.go>


  -claim string
      reattach to an existing sandbox claim instead of creating a new one
  -claim-lease duration
      the sandbox claim expires this long after the last renewal, so a killed exec doesn't leave its sandbox behind; 0 = never (--keep turns it off) (default 10m0s)
  -context string
      kubeconfig context for the sandbox cluster (empty = the ambient current context)
  -credentials string
      how the snippet gets Google credentials: forwarded (copy local ADC into the sandbox), access-token (mint a short-lived token from ADC and serve it to the run only), or service (the same, for --service-account, impersonated with ADC); access-token and service need --in-cluster (default "forwarded")
  -exec-timeout duration
      per-phase sandbox /execute timeout (bounded upstream by PerAttemptTimeout, default 3min) (default 1m30s)
  -extra-imports string
      comma-separated import paths to add as blank imports (forces go mod tidy to resolve them)
  -in-cluster
      dial sandboxes by their in-cluster Service instead of port-forwarding (kode-gopher running in the cluster)
  -keep
      leave the sandbox alive on exit (Disconnect) instead of deleting it (Close)
  -namespace string
      Kubernetes namespace for the sandbox claim (must already exist) (default "default")
  -open-timeout duration
      max time spent opening the sandbox (default 5m0s)
  -read-only
      restrict Google credentials to read-only OAuth scopes; supported with --credentials=service, --credentials=access-token (service-account or WIF JSON ADC), and --auth=oauth
  -service-account string
      --credentials=service: the Google service account snippets run as; kode-gopher's ADC needs roles/iam.serviceAccountTokenCreator on it

kode-gopher serve

Section titled “kode-gopher serve”

The MCP server. Over stdio for local use (Getting started), or streamable HTTP for a shared deployment (Deploy for a team).

usage: kode-gopher serve [flags]


MCP server over stdio or streamable HTTP. Registers execute_go_code, gcp_auth_status and lookup_package_docs.


  -addr string
      http: listen address (default ":8080")
  -auth string
      http: static (one operator-issued bearer token) or oauth (kode-gopher's OAuth server fronting Google sign-in; snippets run as the signed-in user; needs --in-cluster) (default "static")
  -auth-token-file string
      http, static auth: file holding the bearer token clients must send
  -auth-user string
      http, static auth: the user the static token authenticates as (default "operator")
  -claim string
      reattach to an existing sandbox claim instead of creating a new one on first tool call
  -claim-lease duration
      sandbox claims expire this long after the last renewal, so a crashed or killed server's sandboxes go away; 0 = never (--persistent turns it off) (default 10m0s)
  -context string
      kubeconfig context for the sandbox cluster (empty = the ambient current context)
  -credentials string
      how the snippet gets Google credentials: forwarded (copy local ADC into the sandbox), access-token (mint a short-lived token from ADC and serve it to the run only), or service (the same, for --service-account, impersonated with ADC); access-token and service need --in-cluster (default "forwarded")
  -exec-timeout duration
      per-phase sandbox /execute timeout (bounded upstream by PerAttemptTimeout, default 3min) (default 1m30s)
  -in-cluster
      dial sandboxes by their in-cluster Service instead of port-forwarding (kode-gopher running in the cluster)
  -max-sandboxes-per-user int
      http: open sandboxes (MCP sessions with a sandbox) allowed per user; 0 = no cap (default 2)
  -namespace string
      Kubernetes namespace for the sandbox claim (must already exist) (default "default")
  -oauth-allow-domains string
      oauth: comma-separated Workspace domains (the ID token's hd claim) to admit
  -oauth-allow-groups string
      oauth: comma-separated Google group emails to admit (nested membership counts; the checking identity needs the Groups Reader admin role)
  -oauth-clients-file string
      oauth: JSON array of pre-registered clients ({client_id, client_secret?, client_name, redirect_uris}, or {client_id, client_secret, service_account} for the client_credentials grant)
  -oauth-custody string
      oauth: who holds users' Google grants: vault (Agent Identity credential vault) or sealed (inside kode-gopher's refresh token) (default "vault")
  -oauth-google-client-file string
      oauth: kode-gopher's Google OAuth client, as the JSON the Cloud console downloads
  -oauth-groups-service-account string
      oauth: check --oauth-allow-groups as this Google service account (impersonated; it holds Groups Reader) instead of kode-gopher's own identity, which as a Workload Identity principal has no email to assign the role to
  -oauth-issuer string
      oauth: public base URL of this server, e.g. https://kg.example.com (the MCP endpoint is <issuer>/mcp)
  -oauth-keyring-file string
      oauth: token-sealing keys, one "<id> <base64 32 bytes>" per line, sealing key first
  -oauth-open-registration
      oauth: accept dynamically registered (DCR) and Client ID Metadata Document clients, not just pre-registered ones (default true)
  -oauth-vault-auth-provider string
      oauth, vault custody: projects/<p>/locations/<l>/authProviders/<name>
  -open-timeout duration
      max time spent opening the sandbox on first tool call (default 5m0s)
  -persistent
      on shutdown, Disconnect from the sandbox (preserve for reattach) instead of Close (delete it)
  -project string
      oauth: project reported to snippets as GOOGLE_CLOUD_PROJECT
  -quota-project string
      oauth: quota project reported to snippets as GOOGLE_CLOUD_QUOTA_PROJECT
  -read-only
      restrict Google credentials to read-only OAuth scopes; supported with --credentials=service, --credentials=access-token (service-account or WIF JSON ADC), and --auth=oauth
  -service-account string
      --credentials=service: the Google service account snippets run as; kode-gopher's ADC needs roles/iam.serviceAccountTokenCreator on it
  -session-timeout duration
      http: end MCP sessions idle this long, closing their sandboxes (default 15m0s)
  -transport string
      stdio, or http (streamable HTTP at <addr>/mcp, one sandbox per MCP session) (default "stdio")

kode-gopher auth

Section titled “kode-gopher auth”
usage: kode-gopher auth <subcommand>


subcommands:
  status  print the credential identity kode-gopher will forward into sandboxes