ln-031-vps-host-runtime

Paths: File paths (shared/, ../ln-030-vps-bootstrap/references/) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Type: L3 Worker Category: 0XX Shared / Infrastructure

Installs, verifies, or updates the shared VPS layer used by all project environments on one host: packages, ${BOT_USER}, Node/nvm, Claude Code, Codex, MCP, marketplace clone/plugins, Codex trust entries, and the system-wide agent-update timer.

MANDATORY READ

MANDATORY READ: Load shared/references/worker_runtime_contract.md, shared/references/coordinator_summary_contract.md, and shared/references/vps_runtime_contract.md MANDATORY READ: Load ../ln-030-vps-bootstrap/references/scope_layers.md, ../ln-030-vps-bootstrap/references/vps_base_install.md, ../ln-030-vps-bootstrap/references/agent_runtime_install.md, and ../ln-030-vps-bootstrap/references/substitution_rules.md

Input / Output

Direction	Content
Input	`mode`, VPS connection, `${BOT_USER}`, `${PROJECT_DIR}`, `${AGENT_SKILLS_*}`, selected plugins, optional `dry_run`, optional `runId`, optional `summaryArtifactPath`
Output	`vps-host-runtime` summary with status, changes, warnings, blockers, verification, and artifact paths

If summaryArtifactPath is provided, write the same summary JSON there. If not provided, return the summary inline and write it to the standalone run-scoped path. Generate a standalone run_id when runId is absent.

Modes

Mode	Behavior
`install_or_reconcile`	Install missing shared host runtime and update idempotent surfaces
`verify_or_update`	Verify existing host, apply safe updates, add current project trust block
`verify_only`	Detection only; no mutation

Workflow

Phase 1: Preflight

Verify rendered variables, SSH access, root permissions, and dry_run gate.

Evidence:

SSH connection result
host OS
selected mode
missing variables

Phase 2: Base Host

Use vps_base_install.md.

Responsibilities:

apt packages
GitHub CLI and GitLab CLI
${BOT_USER} existence and SSH ownership
AppArmor/bubblewrap availability

verify_only reports drift and planned commands without running installers.

Phase 3: Agent Runtime

Use agent_runtime_install.md.

Responsibilities:

Node 24 under ${BOT_USER}
Claude Code and Codex CLI
optional MCP servers
Codex config creation and current ${PROJECT_DIR} trust block
skills marketplace clone and selected plugins

Do not overwrite existing auth files. Missing claude or codex login is a blocker or warning, not an automated fake success.

Phase 4: Shared Updater

Install or verify:

/usr/local/bin/agent-update
agent-update.service
agent-update.timer
/var/lib/agent-update
/var/log/agent-update.log

Smoke-run only when requested by mode and safe for the host.

Phase 5: Summary

Write a vps-host-runtime summary artifact with:

installed/updated/skipped surfaces
package and CLI versions
auth health
marketplace/plugin health
current project trust block status
blockers and warnings

Critical Rules

Safe to run repeatedly on the same VPS.
Existing shared auth is never overwritten.
Existing project environments are not restarted except through documented updater behavior.
dry_run=true and verify_only do not mutate remote state.
Optional plugins require explicit selection; default is agile-workflow.

Definition of Done

Required inputs and SSH/root access verified or reported as blockers.
Base packages and platform CLIs installed, updated, or verified.
${BOT_USER} exists with expected SSH ownership and login shell.
Node, Claude Code, and Codex versions verified under ${BOT_USER}.
Current ${PROJECT_DIR} Codex trust block exists or is reported as planned drift.
Marketplace clone and selected plugins verified.
agent-update.service and agent-update.timer installed or verified.
dry_run=true / verify_only performed no mutation.
Structured vps-host-runtime summary artifact written.

Version: 1.0.0 Last Updated: 2026-05-05