ln-030-vps-bootstrap

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.

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:

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)

- 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