Bootstrap Google Tools

Install & authenticate CLIs in the sandbox

The sandbox ships lean — Node, gws, gcloud, agents-cli, and mcp-cli are not prebaked. This skill is the verified install + auth recipe for each. The tools are independent: install only the one the task needs. This is a menu, not a sequence — there's no 1-2-3 to run in order.

Persistence model — binaries in ~/.local, credentials in /workspace

Two different durability rules, because the sandbox has two boundaries:

• Across normal sessions the sandbox reattaches, so everything ($HOME included) persists. Install once, reuse next session.
• Across a runtime-image upgrade the sandbox is re-provisioned and only /workspace is migrated — and that migration is a zip that drops symlinks and strips executable bits (and is best-effort). So it can't carry installed CLIs at all; it's only safe for plain data files.

That dictates the split:

So: install binaries the normal way, but point each tool's config dir at /workspace/lha/config (via its own env var, shown per tool) so the expensive part — the OAuth client + tokens — survives upgrades. Don't put binaries on /workspace: they can't migrate anyway, and bloating the migration zip risks the credentials that can. ~/.local/bin is already on PATH (runtime image), and the bash shell is non-login (no ~/.profile), so that image PATH is what makes installs resolve.

Pick what you need

Each tool's usage lives in its own skill (google-workspace, mcp-cli's shipped skill, the google-agents-cli-* set). This skill only gets a tool installed and authed, then hands off.

Before installing: check first

Within a session (and across sessions without an upgrade) a tool may already be present — check before installing, and install only what's missing:

bash(command="command -v gws")   # or gcloud / agents-cli / mcp-cli / node

Node + npm (prerequisite for gws)

The sandbox is Debian x86_64 with curl and tar but no xz. So you must download the .tar.gz build, not the .tar.xz. Pick a current LTS version:

bash(command='mkdir -p ~/.local/bin && cd ~ && V=v22.x.x && \
  curl -fsSLo node.tgz "https://nodejs.org/dist/$V/node-$V-linux-x64.tar.gz" && \
  tar -xzf node.tgz -C ~/.local && rm node.tgz && \
  ln -sf ~/.local/node-$V-linux-x64/bin/node ~/.local/node-$V-linux-x64/bin/npm ~/.local/node-$V-linux-x64/bin/npx ~/.local/bin/')

Replace v22.x.x with the real current LTS. The ln -sf … ~/.local/bin/ step puts node/npm/npx on PATH. Then verify:

bash(command="node --version && npm --version")

• Use .tar.gz — .tar.xz will fail to extract (xz is absent).

gws — Google Workspace CLI

Install the npm global into ~/.local (needs Node on PATH — see above) with --prefix, so the binary lands at ~/.local/bin/gws:

bash(command='npm install -g --prefix ~/.local @googleworkspace/cli && gws --version')

Expect 0.22.x. gws self-identifies as "not an officially supported Google product."

Keep gws credentials on /workspace. By default gws reads/writes ~/.config/gws — which is not migrated on a runtime upgrade. Point it at /workspace and use the file keyring (no OS keyring headless) on every gws command so the OAuth client, token, and encryption key survive:

export GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/workspace/lha/config/gws
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

First, always: probe the pre-injected token. When the user has used "Connect Workspace" in the web UI, the GOOGLE_WORKSPACE_CLI_TOKEN secret is auto-injected into every bash command — gws's highest-priority auth source. Don't inspect the environment or ask; just run a cheap read against the surface you need and see if it works:

bash(command="export GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/workspace/lha/config/gws GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file && gws gmail messages list --params '{\"maxResults\": 1}'")

If it returns data, you're done — no OAuth client, no gws auth login, no loopback bridge. It's a ~1h token (no refresh); the user re-clicks Connect when it lapses. The token only carries the surfaces + access level (read-only by default) the user picked — a gws call outside those scopes fails (403/scope error), which means "reconnect with more surfaces or read-write," not that the token is missing. Don't trust gws auth status — with the env token it reports auth_method: none / credential_source: token_env_var even while reads succeed, so a real read is the only reliable check. Only if the probe 401s (truly no token) do you fall through to the OAuth-client options below.

Otherwise, point gws at an OAuth client — gws ships none of its own. Pick one:

1. Drop a client_secret.json into /workspace/lha/config/gws/ (must be a Desktop app OAuth client — see the google-workspace skill).
2. Set GOOGLE_WORKSPACE_CLI_CLIENT_ID + GOOGLE_WORKSPACE_CLI_CLIENT_SECRET.
3. Service account: GOOGLE_APPLICATION_CREDENTIALS=/workspace/lha/config/gws/key.json — for fully unattended automation (no interactive login).
4. gws auth setup — provisions a project + OAuth client, but is a full-screen TUI that can't be driven headless; prefer option 1 in the sandbox.

gws auth login is loopback-browser only, but does complete headless — you bridge the OAuth redirect by hand (start it backgrounded, relay the auth URL to the user, then curl their pasted localhost:<port>/?code=... redirect back to the waiting listener). The google-workspace skill has the full auth recipe (Desktop-app client type, Internal audience, the loopback bridge) plus command shapes (Drive, Docs, Sheets, Gmail, Calendar, Chat). For fully unattended jobs with no user present to paste the redirect, use the service-account option.

Under a routine, the Google/gcloud token is present only if you declared its secret name (GOOGLE_WORKSPACE_CLI_TOKEN / CLOUDSDK_AUTH_ACCESS_TOKEN) in the routine's secrets:.

Once gws is set up, strongly suggest installing Google's official gws skills. They live in the googleworkspace/cli repo and go deeper than the builtin google-workspace skill — one per surface. Install the ones the user needs (gws-shared is the common base the others build on):

bash(command="npx --yes skills add googleworkspace/cli@gws-shared -y")
bash(command="npx --yes skills add googleworkspace/cli@gws-gmail -y")
# also: gws-drive, gws-docs, gws-docs-write, gws-sheets, gws-calendar,
#       gws-events, gws-chat-send

The Skills CLI stages each under .agents/skills/<skill>/, which Horizon auto-discovers — just load_skill(action="reload"), no move needed (see the find-skills skill for details). (npx --yes skills find gws lists the current set with install counts.)

gcloud

Install under ~/.local (slim — don't add extra components) and symlink the entrypoints onto PATH:

bash(command='mkdir -p ~/.local/bin && cd ~/.local && \
  curl -fsSLo gcloud.tgz "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz" && \
  tar -xzf gcloud.tgz && rm gcloud.tgz && \
  ./google-cloud-sdk/install.sh --quiet --usage-reporting=false --path-update=false && \
  ln -sf ~/.local/google-cloud-sdk/bin/gcloud ~/.local/google-cloud-sdk/bin/gsutil ~/.local/google-cloud-sdk/bin/bq ~/.local/bin/')

No durable gcloud credentials are kept in the sandbox. GCP access is via the short-lived token-as-secret path below, which persists nothing — no refresh token, no ADC file, no key. (You may set CLOUDSDK_CONFIG=/workspace/lha/config/gcloud as a scratch config dir, but there is no login state to persist across upgrades.)

Verify:

bash(command="gcloud --version")

Security: GCP creds is a high-trust combination

Logging in deposits credentials the agent can use, in a sandbox with open outbound internet egress. An injected agent could read the user's GCP data, bq extract / gsutil cp it to a foreign bucket, mint a service-account key, or grant external IAM — all over *.googleapis.com. Layer A (exfil_guard) still gates credential/secret exfil and uploads to non-allowlisted hosts, and still blocks the GCP metadata server; it has no GCP-action awareness (it can't see what a gcloud call does). The real control is credential minimization:

• Use the short-lived token-as-secret path only (below). We keep no durable credential (refresh token / ADC file / SA key) in the sandbox, so a single injection can't become standing access that outlives the ~1 h token.
• Mint the token with the narrowest scopes the task needs; cloud-platform (everything the user's IAM allows) is a broad, high-trust default — not a free one.
• Confirm the user actually wants the agent acting as them on GCP before adding the token.

Authenticate — short-lived access token as a secret (the only GCP path)

The lowest-trust, least-friction path, and the only one we use (works for corp / org-restricted accounts too): the user mints a short-lived access token on their own machine (already gcloud-authed there, so the org's device/CAA policy is satisfied) and hands it to the agent as a secret. Nothing durable lands in the sandbox, and the token self-expires in ~1 hour.

1. The user runs locally, in their own terminal (authed as the right account):

   gcloud auth print-access-token

2. The user saves it as a secret named CLOUDSDK_AUTH_ACCESS_TOKEN in the /lha/secrets UI — never pasted into chat (it's a live credential).
3. Secrets are auto-injected as env vars into every bash command, and gcloud reads CLOUDSDK_AUTH_ACCESS_TOKEN from the environment — so the agent just runs commands, no login / ADC / OAuth client at all:

   bash(command="export CLOUDSDK_CONFIG=/workspace/lha/config/gcloud && gcloud projects list")

   gsutil and bq read the same env token. Don't name the token in a curl/wget (-H "Authorization: Bearer $CLOUDSDK_AUTH_ACCESS_TOKEN"): the exfil guard hard-blocks a network command that references a secret env var (by design — it stops the agent exfiltrating the token). Use the gcloud-family CLIs, which pick it up from the environment without naming it; a raw REST call that must carry the token needs a /grant.

Why this is the default:

• Short-lived (~1 h): a single injection can't become standing access; on expiry the user re-mints and updates the secret.
• Nothing durable in the sandbox — no refresh token on /workspace to reuse.
• Corp-clean: consent already happened through the user's org-approved local gcloud — no Account restricted, no custom OAuth client, no remote-bootstrap.
• It still acts as the user for that window (short lifetime bounds misuse, doesn't eliminate it) and carries the user's login scopes. For a long unattended job the token expires (~1 h) and must be re-minted and the secret updated — by design we keep no durable credential in the sandbox to fall back on.