--- name: ln-030-vps-bootstrap description: "Use when bootstrapping or managing VPS agent environments: fresh install, add project, hex-relay redeploy, diagnostics, or fleet plan/apply." license: MIT allowed-tools: Bash, Read, mcp__hex-ssh__remote-ssh, mcp__hex-ssh__ssh-read-lines --- > **Paths:** File paths (`shared/`, `references/`, `../ln-*`, `agents/hex-relay/`, `ops/`) are relative to the skills repo root. If not found at CWD, locate this `SKILL.md` directory and go up two levels for repo root. # ln-030-vps-bootstrap **Type:** L2 Domain Coordinator **Category:** 0XX Shared / Infrastructure **Tested on:** Ubuntu 24.04 (apt + systemd base: Contabo, Hetzner, DigitalOcean) Public entrypoint for VPS agent environments. This skill routes between fresh install, adding a project to an existing VPS, `hex-relay` lifecycle work, diagnostics, and fleet `plan/apply`. It does not inline detailed install work; it delegates to focused runtime workers and consumes their machine-readable summaries. ## MANDATORY READ **MANDATORY READ:** Load `shared/references/skill_contract.md`, `shared/references/worker_runtime_contract.md`, `shared/references/coordinator_summary_contract.md`, `shared/references/vps_runtime_contract.md`, and `shared/references/meta_analysis_protocol.md` **MANDATORY READ:** Load `references/scope_layers.md`, `references/shared_user_pattern.md`, `references/troubleshooting.md`, and `references/verification_recipes.md` Reference inventory owned by this coordinator family but loaded by the worker that needs it: `README.md`, `vps_base_install.md`, `agent_runtime_install.md`, `god_session_install.md`, `project_repo_bootstrap.md`, `hex_relay_deploy.md`, `operator_dispatcher_install.md`, `provider_credentials.md`, `fleet_registry.md`, `fleet_plan_apply.md`, `substitution_rules.md`, `agent-sandbox.sh`, `agent-update.sh`, `agent-update.service`, `agent-update.timer`, `claude-usage-report.sh`, `codex-config.toml.template`, `codex-notify.sh`, `dispatch.md`, `dispatch.service`, `dispatch.timer`, `dispatcher.md.template`, `god-session.service`, `god-session.sh`, `hex-relay.service`, `mint-gh-token.sh`, `operator.CLAUDE.md`, `register-telegram-commands.sh`, `secrets.env.template`, `settings.agent-config.fragment.json`, `settings.hooks.fragment.json`, `settings.statusline.fragment.json`, `statusline.sh`. --- ## Inputs | Parameter | Required | Default | Description | |---|---:|---|---| | `mode` | No | `auto` | `auto`, `fresh_install`, `add_project`, `relay_redeploy`, `diagnose`, `fleet_plan`, or `fleet_apply` | | `dry_run` | No | `false` | Produce planned actions without mutation where supported | | `registry_path` | No | `/etc/agent-fleet/environments` | VPS-local fleet registry directory for `fleet_plan` / `fleet_apply`; repo `ops/environments` is templates/docs only | | `environment_id` | No | unset | Limit fleet operations to one registry environment | | `plan_artifact_path` | No | generated | Existing plan for `fleet_apply`, or output path for `fleet_plan` | | `repair_scope` | No | `safe` | `none`, `safe`, or explicit bounded repair action for diagnostics | Single-project modes also require the project/VPS variables documented in `references/scope_layers.md` and worker inputs: `PROJECT_NAME`, `SERVICE_PREFIX`, `PROJECT_DIR`, `REPO_URL`, `REPO_REF`, `BOT_USER`, `VPS_HOST`, `VPS_SSH_KEY`, `TARGET_REPO_PATH`, `GIT_PROVIDER`, `REPO_SLUG`, plus optional Telegram/provider variables. --- ## Phase Map ### Phase 1: Resolve Intent Classify the requested operation: | Condition | Operation | |---|---| | `mode=fleet_plan` | Validate registry and compute drift plan for selected environments | | `mode=fleet_apply` | Revalidate registry, re-check live state, and apply approved plan targets | | `mode=relay_redeploy` | Redeploy `agents/hex-relay/` for one existing project environment | | `mode=diagnose` | Inspect one environment and run only bounded safe repairs | | `mode=fresh_install` | Force host reconcile, project runtime, optional relay, verification | | `mode=add_project` | Reuse host through verify/update, then project runtime and optional relay | | `mode=auto` | Discover host state before selecting fresh vs add-project path | Evidence: - selected mode - target environment ids - missing required variables - `dry_run` / apply gate status ### Phase 2: Host Discovery Always perform a lightweight host discovery before project mutation unless the operation is registry validation only. Discovery checks: - SSH connectivity to `${VPS_HOST}` - `id ${BOT_USER}` - required package binaries - Node/nvm, `claude`, `codex` - `~${BOT_USER}/.claude/`, `~${BOT_USER}/.codex/` - `${AGENT_SKILLS_DIR}` and marketplace manifests - `agent-update.timer` - existing `${SERVICE_PREFIX}` units and port collisions Decision: - new or unhealthy shared host -> call `ln-031-vps-host-runtime` with `mode=install_or_reconcile` - existing host -> call `ln-031-vps-host-runtime` with `mode=verify_or_update` - diagnostics-only -> call `ln-034-vps-environment-diagnostics` ### Phase 3: Project Runtime Call `ln-032-vps-project-runtime` for one selected project unless the operation is only `relay_redeploy`, `diagnose`, or registry `plan`. The worker owns project clone, project config/state dirs, god-session, scheduler, provider credentials, and local dispatcher setup. It must not rebuild shared host runtime or deploy `hex-relay`. ### Phase 4: `hex-relay` Lifecycle Call `ln-033-hex-relay-lifecycle` when: - Telegram is enabled for a fresh/add-project install - `mode=relay_redeploy` - fleet drift plan includes `hex-relay` source/service/user drift Skip with explicit `N/A:` reason when `TELEGRAM_BOT_TOKEN` is empty and no relay redeploy was requested. ### Phase 5: Diagnostics And Fleet Call `ln-034-vps-environment-diagnostics` after install/redeploy when final health evidence is needed, or directly for `mode=diagnose`. Fleet rules: - `fleet_plan` loads and validates the live VPS registry from `/etc/agent-fleet/environments/*.yaml` by default, checks live state, and writes a plan artifact under `.hex-skills/runtime-artifacts/runs/{run_id}/vps-fleet-plan/`. - `fleet_apply` must re-check the live VPS registry and live state before mutation. A stale, missing, or registry-mismatched plan is a blocker. - The repo `ops/environments/` directory is template-only. Do not treat it as the source of truth for real fleet membership. - v1 is push-over-SSH only; no continuous daemon/reconciler. - registry secrets are references only, never values. ### Phase 6: Final Summary Aggregate child summaries into one coordinator summary: - operation - environments selected - workers activated - changes planned/applied - skipped/N/A gates - warnings and blockers - verification evidence - artifact paths --- ## Worker Invocation (MANDATORY) | Phase | Worker | Use | |---|---|---| | 2 | `ln-031-vps-host-runtime` | Shared VPS host/runtime install, verify, update | | 3 | `ln-032-vps-project-runtime` | Per-project VPS runtime and local operator setup | | 4 | `ln-033-hex-relay-lifecycle` | `hex-relay` deploy, redeploy, migration, Telegram users | | 5 | `ln-034-vps-environment-diagnostics` | Health, drift, logs, bounded safe repair | Managed worker pattern: ```text childRunId="run-ln-030-${operation}-${worker}-${environment_id}" childSummaryArtifactPath=".hex-skills/runtime-artifacts/runs/${run_id}/vps-runtime-worker/${worker}--${environment_id}.json" Skill(skill: "ln-031-vps-host-runtime", args: "mode={install_or_reconcile|verify_or_update|verify_only} environment_id={environment_id} runId=${childRunId} summaryArtifactPath=${childSummaryArtifactPath}") Skill(skill: "ln-032-vps-project-runtime", args: "mode={bootstrap|verify_only} environment_id={environment_id} runId=${childRunId} summaryArtifactPath=${childSummaryArtifactPath}") Skill(skill: "ln-033-hex-relay-lifecycle", args: "mode={initial_deploy|redeploy|verify_only|sync_users} environment_id={environment_id} runId=${childRunId} summaryArtifactPath=${childSummaryArtifactPath}") Skill(skill: "ln-034-vps-environment-diagnostics", args: "mode={inspect|verify|repair_safe} environment_id={environment_id} repair_scope={repair_scope} runId=${childRunId} summaryArtifactPath=${childSummaryArtifactPath}") Read ${childSummaryArtifactPath} ``` Risk Checklist: - checkpoint child metadata before each delegation - never continue from child chat prose when the summary artifact is missing - do not run workers whose phase is gated `N/A:` - do not apply a fleet plan if live state has changed since plan creation ## TodoWrite format (mandatory) ```text - Phase 1: Resolve operation and required variables (pending) - Phase 2: Discover host state and call host runtime worker when needed (pending) - Phase 3: Call project runtime worker when project bootstrap is in scope (pending) - Phase 4: Call hex-relay lifecycle worker when Telegram/relay is in scope (pending) - Phase 5: Call diagnostics worker and/or write fleet plan/apply evidence (pending) - Phase 6: Aggregate child summaries and run self-check (pending) ``` --- ## Critical Rules - `ln-030` owns routing decisions and ordering. - Workers remain standalone; do not encode upward ownership in worker instructions. - Host bootstrap is never blindly skipped. Existing VPS hosts go through `verify_or_update`. - `fleet_apply` is not a continuous reconciler. It applies an approved plan after a fresh live-state check. - Real fleet membership is stored on the VPS under `/etc/agent-fleet/environments`; repo `ops/environments` is a template contract only. - Registry files may contain secret references only. - Project-specific units, ports, state dirs, and Telegram bot tokens must be unique per environment. - `hex-relay` source is owned by `agents/hex-relay/`; deployment logic lives in `ln-033`. --- ## Definition of Done - [ ] Operation mode resolved with required variables or registry targets. - [ ] Initial TodoWrite plan contains every phase above and all gated `N/A:` items. - [ ] Host discovery completed or registry-only mode explicitly skipped it. - [ ] Selected worker invocations used `runId` and `summaryArtifactPath`. - [ ] Every activated worker produced a structured summary artifact. - [ ] Fresh/add-project flow called host runtime before project runtime. - [ ] Existing-host flow used `verify_or_update`, not a blind skip. - [ ] `hex-relay` work was delegated only when Telegram/relay scope required it. - [ ] Fleet plan/apply used the live VPS registry path and wrote or consumed a run-scoped artifact with registry evidence. - [ ] Final coordinator summary lists applied changes, skipped gates, blockers, warnings, and verification evidence. - [ ] Meta-analysis completed using `shared/references/meta_analysis_protocol.md`. ## Meta-Analysis **MANDATORY READ:** Load `shared/references/meta_analysis_protocol.md` Skill type: `domain-coordinator`. Run after Phase 6 and include whether the split reduced inline execution, preserved worker independence, and kept fleet apply guarded by a plan artifact. --- **Version:** 1.0.0 **Last Updated:** 2026-05-05