vm-bootstrap
Linux VM bootstrap verification skill. MUST BE USED when setting up new VMs or verifying environment.Supports modes: check (warn-only), install (operator-confirmed), strict (CI-ready).Enforces Linux-only + mise as canonical; honors preference brew→npm (with apt fallback).Verifies required tools: mise, node, pnpm, python, poetry, gh, railway, bd, tmux, jq, rg.Handles optional tools as warnings: tailscale, playwright, docker, bv.Never prints/seeds secrets; never stores tokens in repo/YAML; Railway vars only for app runtime env.Safe on dirty repos (refuses and points to dirty-repo-bootstrap skill, or snapshots WIP branch).Keywords: vm, bootstrap, setup, mise, toolchain, linux, environment, provision, verify, new vm
When & Why to Use This Skill
The Linux VM Bootstrap Verification skill is a specialized utility designed to automate the setup and validation of standardized Linux development environments. It ensures environment parity by verifying essential toolchains like mise, Node.js, Python, and Poetry, while offering flexible execution modes ranging from passive health checks to strict CI enforcement. Built with security and safety in mind, it prevents secret leakage and protects 'dirty' repositories from accidental misconfiguration.
Use Cases
- Automated Environment Setup: Streamline the provisioning of new Linux VMs by automatically installing and verifying a consistent set of development tools.
- CI/CD Toolchain Validation: Integrate into CI pipelines using 'strict' mode to fail fast if the build environment lacks required dependencies or correct versions.
- Agent Workspace Auditing: Enable AI agents to self-diagnose their environment health, ensuring they have the necessary CLI tools (gh, railway, jq) to perform tasks.
- Secure Toolchain Management: Standardize tool versions across teams using mise while ensuring no sensitive tokens or secrets are stored in the local environment or repository.
| name | vm-bootstrap |
|---|---|
| description | | |
| Supports modes | check (warn-only), install (operator-confirmed), strict (CI-ready). |
| Verifies required tools | mise, node, pnpm, python, poetry, gh, railway, bd, tmux, jq, rg. |
| Handles optional tools as warnings | tailscale, playwright, docker, bv. |
| Keywords | vm, bootstrap, setup, mise, toolchain, linux, environment, provision, verify, new vm |
| tags | [dx, tooling, setup, linux] |
Linux VM Bootstrap Verification
Verify and optionally install required tools for a standardized Linux development VM.
Modes
| Mode | Behavior | Use Case |
|---|---|---|
check |
Warn-only, never modifies | Local DX entrypoint, agents |
install |
Prompt before each install | Interactive bootstrap |
strict |
Exit non-zero on first missing required tool | CI jobs |
Required Tools
| Tool | Why | Source | Verify |
|---|---|---|---|
git |
repo sync, PRs | apt | git --version |
curl |
installers, API calls | apt | curl --version |
jq |
parse JSON (Railway/GH) | brew (apt fallback) | jq --version |
rg (ripgrep) |
fast search | apt or brew | rg --version |
tmux |
multi-agent sessions | apt or brew | tmux -V |
mise |
toolchain versions | mise installer | mise --version |
python |
backend + scripts | mise (per repo) | mise exec -- python --version |
poetry |
python deps | pipx or mise | poetry --version |
node |
frontend + tooling | mise (per repo) | mise exec -- node --version |
pnpm |
monorepo installs | mise / corepack | mise exec -- pnpm --version |
gh |
PRs + auth | brew | gh --version && gh auth status |
railway |
env/shell/deploy | mise (@railway/cli) |
mise exec -- railway --version |
bd |
Beads tasks | Beads installer | bd --version |
Optional Tools (warn-only)
| Tool | Why | Verify |
|---|---|---|
bv |
Beads graph insights | bv --version |
playwright |
UI/E2E | mise exec -- playwright --version |
tailscale |
cross-VM networking | tailscale status |
docker |
Railway railway dev / local deps |
docker --version |
Security Rules (MUST FOLLOW)
- Never print tokens to logs or stdout
- Never store secrets in YAML,
.envfiles, or repo - Railway vars are for app runtime only (not runner/gh/tailscale credentials)
- gh auth and railway login use interactive prompts or GitHub secrets
Dirty Repo Safety
Before running in install or strict mode:
- Check
git status --porcelain - If dirty:
- In
checkmode: warn and continue - In
install/strictmode: refuse and suggest:- Commit/stash changes first, OR
- Use
/dirty-repo-bootstrapskill to snapshot to WIP branch
- In
Agent Identity (DX_AGENT_ID)
Recommended: Set DX_AGENT_ID for consistent agent identification across repos and sessions.
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export DX_AGENT_ID="$(hostname -s)-claude-code"
Format: <magicdns-host>-<platform>
Examples: v2202509262171386004-claude-code, macmini-codex-cli
Why: Provides stable identity for git trailers, Agent Mail coordination, and multi-repo workflows.
Helper script:
~/.agent/skills/scripts/get_agent_identity.sh
Status: P2, warn-only. Missing DX_AGENT_ID triggers warnings but doesn't block operations.
See DX_AGENT_ID.md for full specification and migration path.
Agent Guidance
When this skill is relevant:
- Detect OS is Linux (refuse on macOS/Windows with clear message)
- Run verification for each required tool
- In
checkmode: report status (✓/✗) for each tool - In
installmode: prompt before each install - In
strictmode: exit 1 on first missing required tool
Command Usage
# Check mode (default, safe for agents)
./vm-bootstrap/check.sh
# or
./vm-bootstrap/verify.sh check
# Install mode (interactive, operator-confirmed)
./vm-bootstrap/install.sh
# Strict mode (CI)
./vm-bootstrap/verify.sh strict
Note: check.sh is a wrapper for verify.sh check. install.sh provides interactive tool installation following the LINUX_VM_BOOTSTRAP_SPEC phases.
Integration
DX entrypoints should call vm-bootstrap check as first step:
# In scripts/bd-context or make dx-doctor
~/agent-skills/vm-bootstrap/verify.sh check
Related Skills
toolchain-health: Python-specific mise/Poetry alignmentmcp-doctor: MCP server health checkskills-doctor: Skills discovery and loading verification