Tier-2 (Linux) support: there is no way to bring an agent VM to the same baseline as a laptop

[kurtseifried]

Implements the tier-2 half of DEC-013 — macOS and Windows are first class; Linux is supported and headless, because it is the machine AI works on.

Current state

# scripts/macos-ai-tools.sh:262
[[ "$(uname -s)" == "Darwin" ]] || abort "This script supports macOS only."

There is no Linux script. scripts/ contains only macos-* and windows-*. The only Linux awareness anywhere is the root-check exemption for containers (/.dockerenv, /run/.containerenv), which exists for CI.

Why it matters — this already cost us

The weekly CSA-source sweep (#49, docs/periodic-sweep.md) was designed, built, and moved to a Claude cloud routine — then parked disabled, because the cloud sandbox ships no gh binary and wiring one needs a CSA-Internal PAT in cloud config. That is a fully built automation sitting shelved for want of a tier-2 baseline.

What tier 2 is, and is not

Is: CLI tools and authentication on VMs, containers, CI runners, cloud sandboxes. Non-interactive as the primary path, not a fallback.

Is not: a human desktop. No 1Password GUI, Slack, Zoom, Chrome, Claude Desktop, or ChatGPT Desktop. No assumption of a person at the keyboard.

The hard part is auth, not packages

Packages are mostly solved already, and by the vendors:

tool	Linux story
Claude Code	signed apt / dnf / apk repositories, published by Anthropic
Codex	Linux musl + gnu binaries, plus curl https://chatgpt.com/codex/install.sh | sh
Gemini CLI	npm, same as everywhere
uv	one static binary, all platforms (DEC-012)
git / gh	distro packages

The real work is the browser-dependent flows. gh auth login, claude login, and MCP OAuth (/mcp) all assume a browser and a human. "It works once you log in" is not a tier-2 answer. This needs device-code flows or injected credentials, and it is a credential-policy decision as much as a technical one — the same one that parked the sweep routine.

Suggested scope for a first pass

1. Decide whether tier 2 is a linux-ai-tools.sh or a portable path inside the existing script. The base layer (git, gh, node, python, the three CLIs, plugins, MCP registration) is largely shared; the package manager and the GUI-app block are what differ.
2. Prefer the OS-agnostic vendor install methods above over per-distro packaging, so this does not become a third codebase to keep in sync — the repo already carries the cost of two.
3. Treat the auth story as its own decision, not a detail of the script.

Note the existing duplication discipline (tools/check-duplication.py) will apply to any shared functions a third script introduces, which is an argument for portability over a separate file.

[kurtseifried]

Scoped: tier 2 means Ubuntu LTS

Recorded as an amendment to DEC-013. Arch and others are out of scope until something forces otherwise — naming one distro is what makes this buildable instead of a matrix.

Verified traps — the distro packages mostly can't be used

tool	apt result	so use
nodejs	18.19.1 on 24.04 — below our floor of 22	NodeSource repo (vendor)
awscli	not in the noble archive (present focal/jammy/oracular/plucky, removed for 24.04)	AWS's official v2 installer
claude-code	n/a	Anthropic's signed apt repo ✅ already vendor-published
terraform	lags	HashiCorp apt repo
docker	docker.io lags	Docker's official apt repo
gh	lags	GitHub apt repo
uv	n/a	Astral install script
python3	3.12 on 24.04 — clears the 3.10 floor	still prefer uv, for one pinned version across tiers

The pattern: on Ubuntu almost everything sits at rank 2 of the install-method ranking (vendor repo/script), not rank 3 (distro package). That's good news for scope — rank 2 methods are distro-independent, so this is largely the same install logic tier 1 already wants, not a third codebase.

What else is needed — beyond packages

The packages are the easy half. These are the actual open items:

1. Auth, and it's still the blocker. gh auth login, claude login and MCP /mcp OAuth all want a browser. Needs device-code flows or injected credentials. This is what parked the sweep routine.
2. AWS credentials on a headless VM. If we use AWS SSO, that's another browser flow. But DEC-006 says IAM-first, no stored credentials — so a tier-2 VM running inside AWS gets credentials from its instance role and the problem disappears. That's likely the answer, and it's worth confirming, because it decides whether tier-2 VMs must live in AWS.
3. 1Password on a headless box. The CLI's normal flow is desktop-app-integrated. Service accounts (OP_SERVICE_ACCOUNT_TOKEN) are the headless path — relevant given DEC-011 pairs 1Password with AWS Secrets Manager.
4. Ansible collections. Installing ansible doesn't install amazon.aws; that's ansible-galaxy, and it's a separate step nobody has specified.
5. Terraform state access — S3 + locking, which depends entirely on (2).
6. Git identity and commit signing on an ephemeral VM.
7. A tier-2 update path. macos-update.sh has no Linux counterpart, and an ephemeral VM arguably wants provisioning-from-cold rather than updating — worth deciding rather than porting by reflex.

Items 1–3 are credential-policy decisions more than engineering ones. Suggest settling (2) first: if tier-2 VMs run in AWS with instance roles, a large part of the auth problem is solved by construction rather than by code.