Bare-machine first use: isolated docker environment + setup ordering fix - #104
Merged
Conversation
Ubuntu container that installs @pacphi/agentic-kit@next at start, runs full setup (--codex --opencode), and serves the loopback-only dashboard to the host via a socat bridge published on host-loopback only. No host paths mounted except ./artifacts; persistent state in named volumes, so a host agentic-kit install can never conflict. Verified end-to-end with zero credentials: setup completes and ak sync converges with no failing subsystems.
On a genuinely bare machine, machine setup registered the user-scope MCP
server and synced the CLAUDE.md guidance blocks before the hosts branch had
installed the claude/codex/opencode CLIs — so first runs warned ('claude mcp
add failed') and reported immediate block drift (command:codex and
flag:dualMode detectors flip only after the hosts step). Both steps now run
as a final pass in the setup orchestrator, after the hosts branch and the
project phase's codex bridge (which creates ~/.codex). The guidance
reconcile loop is extracted to blocks.mjs reconcileGuidance and shared with
ak sync, so the two commands converge guidance identically.
…laims AK_INSTALL_SPEC lets maintainers install an unpublished npm-pack tarball from ./artifacts — used to prove local fixes in the first-use container before publishing. User guide now states the zero-credential convergence as verified fact.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two deliverables that belong together — a repeatable bare-machine first-use environment, and the setup bug it immediately caught:
docker/— isolated cross-platform first-use environment. Onedocker compose up akon macOS/Windows/Linux builds Ubuntu 26.04 + Node (NodeSource, build-arg matrix), installs@pacphi/agentic-kit@nextat container start (the true first-install path — no image rebuild per release), runsak setup --codex --opencode --yesas a non-root user, and serves the dashboard to the host browser. The dashboard binds container-loopback by design (ADR-0014), so a socat bridge re-publishes it and compose maps it back host-loopback-only — the printed#tokenURL works verbatim on the host. Isolation is absolute both ways: no host paths mounted except./docker/artifacts; all persistent state in named volumes; a host agentic-kit install of any version cannot conflict. Persona-split docs live in the directory itself (USER-GUIDE.md/MAINTAINER-GUIDE.md).fix(setup): guidance blocks + user-scope MCP registration moved to a final pass. On a genuinely bare machine, both ran before setup's hosts branch had installed theclaude/codexCLIs — first runs warnedclaude mcp add failedand reported immediate block drift. The reconcile loop is extracted toblocks.mjs reconcileGuidance()and shared withak sync, so setup and sync converge guidance identically.Proof (zero-credential container runs)
⚠ claude mcp add failed, post-setup status warnsmcp: ruflo MCP not registered+ 3 drifted blocks.AK_INSTALL_SPECtarball install): zero warnings; final pass upserts all 9 registry blocks in one shot (including~/.codex/AGENTS.mddual-mode, which previously needed a second sync); post-setup status:mcp: claude-flow registered (user scope),blocks: CLAUDE.md managed blocks in sync (9 in registry). Remaining warns are only the honestcodex/opencode auth: noneadvisories.ruflo init/memory/swarm/daemon with a verified memory write,aqe init --with-codex) needs no AI login or API key;ak syncafterwards reports converged with no failing subsystems.Test plan
pnpm run checkgreen (typecheck, lint, markdown, build, full test suites).🤖 Generated with Claude Code