Repository navigation
Proxy service-model redesign: automatic flake services, retire proxy-supervisor ownership, restore consumer Wants #2104
Description
Proxy service-model redesign: automatic flake services, supervisor retirement
Design decision (Drew, 2026-10-28 23:05 CDT): make the fleet proxies proper automatic flake-declared user services, retire the proxy-supervisor's process-ownership role, and restore consumers' Wants against the real units.
Current state
- Seven proxies serve canonical ports: clef :18742, antigravity-agy :18743, codex :18744, antigravity-ls :18745, design-code :18746, commandcode :18748, claude-code :18749. (muse :18747 is supervised the same way and must not be stranded by a supervisor retirement.)
- They currently run as supervisor-owned transient
fps-*units (bin/proxy-supervise.mjs, run by theproxy-supervisoruser timer every ~2 min; endpoint state under~/.local/state/<proxy>/endpoint.json). - The supervisor had a symlink-guard bug (proxy-supervise: main() never runs when invoked via a symlinked path (~/code -> ~/git/code) — supervisor timer silently no-ops since 2026-10-27 #2083) making it a silent no-op from 2026-10-27 until manual cold-starts on 2026-10-28. PR fix(proxy-supervise): entry-point guard compares realpaths so symlinked invocations run main() (#2083) #2085 (guard fix) is open.
- The flake also declares manual one-off units for the proxies in
home/common/default.nix(noInstall.WantedBy), currently stopped.claude-code-proxyandmuse-proxyhave no declarative unit at all — supervisor config only. - Consumers on
mainstillWantsthe manual units:openclaw-gateway(home/openclaw/default.nix: commandcode/design-code/agy + mcpx) andopenchamber.service(home/common/default.nix: clef/codex/antigravity-ls/design-code).
Redesign
- One automatic user service per proxy: flake-declared (home-manager
systemd.user.services), canonical port,ExecStartrunning the same checkout entry points the supervisor runs today (~/code/bin/*.mjs,commandcode-proxy-start.sh,muse-proxy-start.sh),Restartper flake patterns,Install.WantedBy = [ "default.target" ]. - Retire the supervisor's ownership in the same change: remove/disable the
proxy-supervisortimer + oneshot service and its config so it cannot respawnfps-*units. No second owner may remain; the cutover must end in exactly one ownership model. - Consumers'
Wantsstay/restored against the (now real, automatic) units withWants+Aftersemantics — soft pull-in, ordering when co-started, never blocks the consumer if a proxy is not live. mcpxWantsare legitimate and stay. - The manual one-off declarations are replaced by the automatic units (same unit names), so nothing startable remains that can fight the services for a canonical port.
Supersedes / related
- PR fix(home): drop openclaw-gateway wants on manual proxy units #2092 (gateway wants removal) and PR fix(home): drop openchamber wants on manual proxy units #2094 (openchamber wants removal) are superseded by this redesign: the wants are no longer wrong once the units they name are real automatic services. Both PRs stay open, unmerged.
- proxy-supervise: main() never runs when invoked via a symlinked path (~/code -> ~/git/code) — supervisor timer silently no-ops since 2026-10-27 #2083 / PR fix(proxy-supervise): entry-point guard compares realpaths so symlinked invocations run main() (#2083) #2085: the guard fix becomes moot if the supervisor's process-management role retires here.
- Home-layer eval uses a stale bin/ tree: commandcode-proxy unit 203/EXEC, managed opencode stuck on old rev #883: related — the declarative commandcode unit's store-path
ExecStartwas the stale-bin casualty; the redesign runs the checkout entry points like the supervisor does.
Acceptance criteria
- After a switch: all proxy services active on canonical ports,
proxy-supervisortimer gone/disabled, nofps-*units. -
/v1/modelsspot-checks on :18745, :18746, :18748 return live lists. -
openclaw-gatewayandopenchamber.servicerestart cleanly (Wants+After soft semantics). - One end-to-end route smoke through the background OpenCode serve (:13420).
-
systemctl --user --failedclean for proxy units. - Cutover safety: never leave supervisor + services fighting over ports; if the cutover cannot complete, the supervisor-owned status quo stays fully intact.
Activity
developing-today commentedon Oct 29, 2026
CODE-1012
dezren39 commentedon Oct 29, 2026
Implementation PR: #2107 (branch feat/proxy-automatic-services-2104, commit 659343a) — home/common/default.nix only.
Local verification in the worktree before pushing: nix eval of the built home config renders clef-proxy's ExecStart, claude-code-proxy Install.WantedBy = ["default.target"], and the proxy-supervisor service attribute is absent (removal confirmed).
Status 2026-10-28 night CDT: PR open, mergeable, checks pending (Nix flake evaluation / run / treefmt check queued on the backlogged self-hosted runners). Per merge-on-green-only, it has NOT been merged and no switch/cutover has been attempted. The supervisor-owned status quo remains fully live: proxy-supervisor.timer active, all fps-* units serving canonical ports 18742-18749. Cutover (timer stop -> switch -> fps stop -> service start -> port/model/consumer/smoke verification) is deferred until #2107 merges on green.
Also done under this issue: superseded comments on #2092 and #2094 (both left open, unmerged) and a comment on #2083 noting PR #2085's guard fix becomes moot if the supervisor retires here.
dezren39 commentedon Oct 29, 2026
Intake review
Fleet monitor intake pass (protocol §5), 2026-10-28 ~23:35 CDT.
Wantsrestoration must land with, not before, the real units.Merge pull request #2107 from developing-today/feat/proxy-automatic-s…
developing-today commentedon Nov 3, 2026
agent-note:v1
state: reviewed (coverage loop-back)
Coverage pass 2026-11-03, loop-back review: this issue was re-reviewed (drift / overlap / already-handled / stale / blockers / ordering) so every open issue in the four repos is reviewed and in the system. Verdict: still live; in the system as task 7290 (triage, queued, priority 50) in repo-health-code-pilot. Labels audited and synced. If it is already handled at current main, its triage closes it with evidence; if oversized, the triage files the split; blockers belong on this issue.
Found via: coverage loop-back 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done (triage — closing with evidence)
Triage verdict — #2104 is implemented and live; closing with evidence
Verified fresh 2026-11-03 ~23:25Z against GitHub current main and the laptop's live systemd user state.
The redesign landed. PR #2107 — feat(home): make fleet proxies automatic services, retire proxy-supervisor (#2104) — MERGED 2026-10-30T05:16Z (merge commit 72749ff),
home/common/default.nixonly, exactly per this issue's design: one automatic flake-declared user service per proxy on its canonical port running the checkout entry points, new declarative units for claude-code-proxy (:18749) and muse-proxy (:18747), and theproxy-supervisorservice + 2-minute timer + supervisor config removed in the same change so nothing can respawnfps-*units.Acceptance criteria, checked against the fleet's current shape:
fps-*units — live on the laptop: clef-proxy, codex-proxy, commandcode-proxy, claude-code-proxy, muse-proxy and opencode-route-proxy areloaded active runninguser services (unit files enabled);systemctl --user list-timersshows no proxy/supervisor timer; nofps-*units exist. Current main still carries the retirement (home/common/default.nix: "Proxy supervisor retired (Proxy service-model redesign: automatic flake services, retire proxy-supervisor ownership, restore consumer Wants #2104, 2026-10-28)")./v1/modelsspot-checks — :18748 and :18744 return live model lists today. :18745/:18746 return nothing on localhost by later design, not by failure: subsequent changes replaced agy-proxy (:18743) and antigravity-ls-proxy (:18745) and left the design-code door (:18746) off with no consumers (see the comments athome/common/default.nix:588-589 and :656-670) — the fleet evolved past the original seven-proxy set after this redesign landed.Wants+Aftersoft semantics — openclaw-gatewayWantsopencode-route-proxy + mcpx (+ openclaw-embedding) and ordersAfterthe proxy units; the openchamber side is recorded athome/common/default.nix:546. Note on ordering history: PRs fix(home): drop openclaw-gateway wants on manual proxy units #2092/fix(home): drop openchamber wants on manual proxy units #2094 (wants removal) did merge on 2026-10-30 (03:34Z / 05:14Z) despite this issue's "stay open" note — but PR feat(home): make fleet proxies automatic services, retire proxy-supervisor (#2104) #2107 merged after them (05:16Z) and is the final word: the units the consumers name are real automatic services.systemctl --user --failedclean for proxy units — no proxy unit is failed. (Two unrelated failures exist: openai-cred-watchdog, tracked by Fleet workhorse legs failing fleet-wide: provider.auth 401 'Missing scopes: api.responses.write' (15:40 wave 9/9 roots failed) #3216, and pm-git-sync.)Residual papercut (not a blocker; routed, not filed as a duplicate):
home/openclaw/default.nixstill carries the pre-redesign comment claiming the proxies "are owned by the proxy-supervisor (transient fps-* units)" and keeps the retiredagy-proxy.servicein openclaw-gateway'sAfterlist (it shows as a not-found unit). The specific lines are recorded on #2775 (the open survey of laptop services & proxies declarative coverage) as its tracking home.Disposition: the queue task 7290 triage is complete with outcome
already_done; this issue closes on its merits — the work it tracked is implemented, merged, and verified live.