Feature: Pre-install AI CLI tools (Gemini, Codex, Claude Code) for end users

[MagnaCapax]

Summary

Pre-install three AI CLI tools system-wide on PMSS servers so end users have them available immediately on login without running any installers themselves. Each user authenticates independently (BYO API key or OAuth) — no shared credentials, no pre-existing keys, no data leakage between users.

Tools:

Tool	Binary	Source	License
Google Gemini CLI	gemini	npm @google/gemini-cli	Apache 2.0
OpenAI Codex CLI	codex	Standalone Rust binary from GitHub releases	Apache 2.0
Anthropic Claude Code	claude	npm @anthropic-ai/claude-code	Proprietary

Privacy & Security Alignment

Cardinal Value #1 — Liberty and privacy are sacred:

• NO pre-existing API keys anywhere in skel or system config
• Each user's config is isolated: ~/.gemini/, ~/.codex/, ~/.claude/ (mode 700, created by tools on first run)
• No shared credentials between users
• Users bring their own API keys or use their own OAuth logins
• Tools communicate with their respective cloud APIs — no local model data, no inter-user leakage

Security considerations:

• All three tools can execute shell commands — but users already have shell access, so this doesn't change the threat model
• Codex CLI has Landlock sandboxing on kernel 5.13+ (Debian 12). On Debian 10/11 (kernel <5.13), sandbox is unavailable
• System-wide /etc/codex/config.toml can set sandbox = "danger-full-access" on older kernels (user already has full shell, sandbox is protection from Codex, not from the user)

Prerequisites

Node.js 20+ (required for Gemini CLI and Claude Code)

Stock Debian Node.js is too old for all versions:

Debian	Stock Node.js	Required
10 (Buster)	10.x	20+
11 (Bullseye)	12.x	20+
12 (Bookworm)	18.x	20+

Install via NodeSource:

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs

Kernel compatibility (Codex CLI sandbox)

Debian	Kernel	Codex Landlock sandbox
10	4.19	NO — needs system config workaround
11	5.10	NO — needs system config workaround
12	6.1	YES — works natively

Installation Methods (per tool)

1. Gemini CLI

# System-wide via npm (requires Node.js 20+)
npm install -g @google/gemini-cli
# Binary: /usr/local/bin/gemini (or wherever npm prefix points)

Per-user config: ~/.gemini/ (settings.json, oauth_creds.json, .env)
System config: /etc/gemini-cli/settings.json (optional, lowest precedence)
Auth options:

• Google OAuth (free tier: 60 req/min, 1000 req/day) — opens browser
• GEMINI_API_KEY env var — headless, BYO key from Google AI Studio
• Vertex AI credentials — for GCP users

2. Codex CLI

# Download static musl binary (no Node.js required, no dependencies)
wget https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
chmod +x /usr/local/bin/codex

Per-user config: ~/.codex/ (config.toml, auth.json)
System config: /etc/codex/config.toml (lowest precedence)
Auth options:

• ChatGPT account OAuth — opens browser (requires Plus/Pro/Business/Enterprise)
• OPENAI_API_KEY via codex login --with-api-key — headless, BYO key
• Device code auth (codex login --device-code) — headless, beta

Debian 10/11 workaround (sandbox unavailable):

mkdir -p /etc/codex
cat > /etc/codex/config.toml << 'EOF'
# Landlock unavailable on kernel < 5.13
# Users already have full shell access; sandbox protects from Codex, not from user
sandbox = "danger-full-access"
EOF

3. Claude Code

# System-wide via npm (requires Node.js 18+, but we have 20+ from Gemini)
npm install -g @anthropic-ai/claude-code
# Binary: /usr/local/bin/claude

Note: Anthropic's recommended install (curl | bash) is per-user to ~/.local/bin/claude. For system-wide deployment, npm global install is the practical option despite being marked deprecated.

Per-user config: ~/.claude/ (settings.json, .credentials.json)
Auth options:

• OAuth login — opens browser (requires Claude Pro/Max/Teams/Enterprise)
• ANTHROPIC_API_KEY env var — headless, BYO key, pay-as-you-go API rates

Implementation Plan

Phase 1: System-wide binary installation (server-side script)

Create a PMSS script (e.g., /scripts/util/installAiTools.php or a bash script invoked during update) that:

1. Checks if Node.js 20+ is installed; if not, installs via NodeSource
2. Installs Gemini CLI via npm install -g @google/gemini-cli
3. Downloads and installs Codex CLI static binary to /usr/local/bin/codex
4. Installs Claude Code via npm install -g @anthropic-ai/claude-code
5. Creates /etc/codex/config.toml with sandbox workaround on kernels < 5.13
6. Verifies all three binaries are executable and in PATH

Phase 2: User-facing documentation / helper

Add an ai-help function to skel .bashrc (or .bashrc.custom) that displays:

• Available tools and their commands
• How to authenticate each tool (BYO API key instructions)
• Links to documentation
• Note about free tier availability (Gemini)

This could also be a standalone /usr/local/bin/ai-help script to avoid .bashrc bloat.

Phase 3: Skeleton integration

• If adding files to skel (e.g., a helper script in ~/bin/): add to skeleton.php file list for propagation to existing users
• System-wide binaries in /usr/local/bin/ don't need skel — they're available to all users immediately via PATH (the pmss_normalize_path function in .bashrc includes /usr/local/bin/)

Phase 4: Testing

• Test on ONE server first (safety doctrine)
• Verify on Debian 10, 11, and 12 if possible
• Confirm each tool starts, shows auth prompt, and doesn't leak to other users
• Confirm disk usage is acceptable on root partition
• Confirm user quota is not affected (system-wide install, not per-user)

Estimated disk usage (system partition, not user quota)

• Node.js 20: ~100 MB
• Gemini CLI + deps: ~50-100 MB
• Codex CLI binary: ~30 MB
• Claude Code + deps: ~50-100 MB
• Total: ~250-400 MB on root filesystem

Rollback

• npm uninstall -g @google/gemini-cli @anthropic-ai/claude-code
• rm /usr/local/bin/codex
• Optionally remove NodeSource repo and Node.js (but other tools may use it)

User authentication summary

Tool	Free tier?	BYO key env var	OAuth	Headless
Gemini	YES (Google account)	GEMINI_API_KEY	Google OAuth	API key only
Codex	NO (needs ChatGPT sub or API key)	OPENAI_API_KEY	ChatGPT OAuth	API key or device code
Claude	NO (needs subscription or API key)	ANTHROPIC_API_KEY	Claude OAuth	API key only

Related

• bashrc: add .bashrc.custom sourcing to prevent install-media-stack conflicts #183 — .bashrc.custom sourcing (extension mechanism for user shell customizations)
• Security: User PATH includes ~/bin before system paths - potential self-hijack vector #153 — PATH ordering fix (system paths already lead, /usr/local/bin/ included)

Väinämöinen noreply@pulsedmedia.com

[MagnaCapax]

Revised approach: All per-user namespace

Per operator direction, the architecture is changed from system-wide to fully per-user:

Design: follows install-media-stack.sh pattern

• ~/install-ai-tools.sh in skel — user runs it to install, re-runs to update
• Self-updates from GitHub raw URL on every interactive run (same as install-media-stack.sh)
• Everything installs to user space: ~/bin/, ~/.local/
• Zero system-level dependencies (portable Node.js for Gemini, static binary for Codex, native installer for Claude)
• User controls versions — re-run to update, delete ~/bin/<tool> to remove
• Counted against user's disk quota (their choice to install)

Per-tool install locations

~/bin/gemini         wrapper script → ~/.local/share/gemini-cli/bin/gemini
~/bin/codex          static musl binary (self-contained)
~/bin/claude         symlink → ~/.local/bin/claude
~/bin/ai-help        help/orientation script

~/.local/share/node/          portable Node.js 20 LTS (for Gemini only)
~/.local/share/gemini-cli/    Gemini CLI npm packages
~/.local/bin/claude           Claude Code native binary (from Anthropic's installer)
~/.local/share/claude/        Claude Code version data

Per-tool config (created by tools on first use, NOT pre-populated)

~/.gemini/           Gemini CLI settings + credentials
~/.codex/            Codex CLI settings + credentials
~/.claude/           Claude Code settings + credentials

Disk usage per user (approximate, only if user runs installer)

Component	Size
Portable Node.js 20	~80-100 MB
Gemini CLI + npm deps	~50-80 MB
Codex CLI binary (musl)	~30 MB
Claude Code (native)	~80-100 MB
Total	~250-310 MB

Installer shows this estimate and asks for confirmation before proceeding.

Skeleton propagation

• install-ai-tools.sh goes in /etc/skel/ and into skeleton.php file list
• Existing users get the script on next PMSS update
• Users are NOT forced to install — they run the script only if they want the tools
• Self-update mechanism means even stale skel copies fetch latest on run

Why per-user is better

1. No system-level Node.js dependency
2. Users control their own versions and updates
3. No root intervention needed for updates
4. Follows established pattern (install-media-stack.sh)
5. Disk cost is opt-in (only users who run the installer pay quota)
6. Clean removal: user deletes ~/bin/ and ~/.local/share//

Privacy unchanged

• No pre-existing keys
• No shared credentials
• Per-user config dirs (700 perms, created by tools)
• Users authenticate independently

Codex sandbox note

On kernels < 5.13 (Debian 10/11), Codex CLI's Landlock sandbox is unavailable. The installer creates ~/.codex/config.toml with sandbox = "danger-full-access" on those kernels. User already has shell access — sandbox protects from Codex making unintended changes, not from the user.

Väinämöinen noreply@pulsedmedia.com

[MagnaCapax]

Design principle noted

Operator direction: always userspace over global when possible. This is now the guiding principle for this implementation.

The revised architecture (previous comment) already follows this:

• Portable Node.js in ~/.local/share/node/ (not system-wide)
• Codex static binary in ~/bin/ (not /usr/local/bin)
• Claude Code via native per-user installer → ~/.local/bin/claude + symlink to ~/bin/
• Gemini CLI npm packages in ~/.local/share/gemini-cli/ (not global npm)
• Zero root/system dependencies
• User runs bash ~/install-ai-tools.sh to opt in
• User re-runs to update (self-update from GitHub like install-media-stack.sh)

Implementation prompt ready at prompts/install-ai-cli-tools.md in the sysadmin repo.

Väinämöinen noreply@pulsedmedia.com

[MagnaCapax]

Test Results

Server: le6-1-100emperor.pulsedmedia.com

• Debian: 12.13, Kernel: 6.1.0-42-amd64, PMSS: git/main@2026-01-31 10:55
• CPU: AMD Opteron 6168 (no AVX2 — exercises npm fallback for Claude Code)

Results

• install-ai-tools.sh runs without errors (exit 0)
• Self-update mechanism present (skipped in test with --skip-update, GitHub URL not live yet)
• Portable Node.js 20.20.0 installs to ~/.local/share/node/
• Gemini CLI 0.26.0 installs and shows version
• Codex CLI 0.93.0 (rust-v0.93.0) binary downloads and shows version
• Claude Code native installer fails gracefully on old CPU (Illegal Instruction)
• Claude Code 2.1.29 installs via npm fallback, symlink wrapper in ~/bin
• ai-help command works
• No pre-existing credentials — ~/.gemini/ does not exist, ~/.codex/ has only tmp/, ~/.claude/ has only downloads/
• User A cannot access User B config (homedir 770 blocks traversal)
• Total disk usage: ~1.1 GB (NOT 250-310 MB — Gemini npm deps are 504 MB)
• Re-run updates correctly (idempotent) — Node.js skipped, tools updated

Disk breakdown

168M    ~/.local/share/node/          (portable Node.js 20.20.0)
504M    ~/.local/share/gemini-cli/    (Gemini CLI + npm deps)
66M     ~/bin/codex                   (static musl binary)
84M     ~/.local/share/claude-code/   (Claude Code npm packages)
---
349M    ~/bin/
756M    ~/.local/
~1.1 GB total

Issues found and resolved

1. Claude Code native binary requires AVX2 — AMD Opteron 6168 (and similar old CPUs) get "Illegal Instruction". Added npm fallback: tries native first, if binary crashes, installs via npm install -g @anthropic-ai/claude-code using the already-installed portable Node.js. Works transparently.

2. Disk estimate was wrong — Original estimate 250-310 MB, actual ~1.1 GB. Gemini CLI npm packages are 504 MB (not 50-80 MB). Updated the banner message to say "~1 GB".

3. Codex release tag is rust-v0.93.0 (not v0.93.0) — the download URL construction handles this correctly since we extract the full tag from the GitHub redirect/API.

Notes

• Script is opt-in: users must run bash ~/install-ai-tools.sh themselves
• skeleton.php updated to propagate installer to existing users on PMSS update
• No system dependencies — everything is user-space
• Tested as non-root user akayajir with real quota constraints

— Sampsa Pellervoinen 🌱

[MagnaCapax]

install-media-stack.sh Security Hardening (2026-02-01)

While implementing the AI tools installer (#185), discovered the same AVX CPU compatibility issue affects Jellyfin on old servers (AMD Opteron 6168, emperor class). Extended the fix pattern to install-media-stack.sh along with a comprehensive security audit.

Commits

• fd3a18d — Main security hardening (65 insertions, 12 deletions)
• 82f4396 — BindAddress race condition fix + AutoDiscovery disable

Changes

CPU Compatibility:

• AVX/SSE4.2 detection at install start with user warnings
• Jellyfin smoke test: starts DLL briefly, detects SIGILL crashes
• Enhanced post-startup verification: checks app logs for Illegal Instruction

Security Fixes:

• SABnzbd: explicit host = 127.0.0.1 binding (was defaulting to 0.0.0.0)
• Jellyfin: network.xml created BEFORE first start (was 0.0.0.0 race)
• Radarr/Sonarr/Prowlarr: <BindAddress>127.0.0.1</BindAddress> directly in templates (was * → sed race)
• Jellyfin AutoDiscovery disabled (inappropriate on shared servers)
• Config dirs: chmod 700
• Log file + lighttpd proxy config: chmod 600

Tested On

le6-1-100emperor.pulsedmedia.com (AMD Opteron 6168, no AVX):

• Dry-run passes, CPU warnings fire correctly
• Permission changes verified
• SABnzbd host insertion works for both old and new configs
• Syntax verified (bash -n)