# 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

- Author: fengning-starsend
- Repository: stars-end/agent-skills
- Version: 20260121145356
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/stars-end/agent-skills
- Web: https://mule.run/skillshub/@@stars-end/agent-skills~vm-bootstrap:20260121145356

---

---
name: vm-bootstrap
description: |
  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
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)

1. **Never print tokens** to logs or stdout
2. **Never store secrets** in YAML, `.env` files, or repo
3. **Railway vars** are for app runtime only (not runner/gh/tailscale credentials)
4. **gh auth** and **railway login** use interactive prompts or GitHub secrets

## Dirty Repo Safety

Before running in `install` or `strict` mode:

1. Check `git status --porcelain`
2. If dirty:
   - In `check` mode: warn and continue
   - In `install`/`strict` mode: refuse and suggest:
     - Commit/stash changes first, OR
     - Use `/dirty-repo-bootstrap` skill to snapshot to WIP branch

## Agent Identity (DX_AGENT_ID)

**Recommended**: Set `DX_AGENT_ID` for consistent agent identification across repos and sessions.

```bash
# 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**:
```bash
~/.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:

1. Detect OS is Linux (refuse on macOS/Windows with clear message)
2. Run verification for each required tool
3. In `check` mode: report status (✓/✗) for each tool
4. In `install` mode: prompt before each install
5. In `strict` mode: exit 1 on first missing required tool

## Command Usage

```bash
# 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:

```bash
# In scripts/bd-context or make dx-doctor
~/agent-skills/vm-bootstrap/verify.sh check
```

## Related Skills

- `toolchain-health`: Python-specific mise/Poetry alignment
- `mcp-doctor`: MCP server health check
- `skills-doctor`: Skills discovery and loading verification