Skip to content
SHC Docs

Local dev servers

The console, marketplace, zkpoker, storybook and the daemon they talk to, run on a workstation and reachable from other machines on the private network. Audience: whoever is trying to test the UI and finding nothing listening.

Short version: they are launchd jobs now. Start them with

Terminal window
scripts/devservers.sh install # first time, or after changing the script
scripts/devservers.sh status # is it up, on what bind, answering what

Three separate faults, diagnosed 2026-08-13. Only the first one matches the “it was serving twenty minutes ago and now there is no listener at all” symptom; the other two were found while fixing it.

1. Every dev server was a child of an editor session

Section titled “1. Every dev server was a child of an editor session”

Nobody started these from a terminal they owned. They were started from AI agent tool calls, which gives every one of them this parent chain:

one dev --port 4600
└─ pnpm --filter @app/console exec one dev --port 4600
└─ /bin/zsh -c ... (the agent harness shell)
└─ Cursor Helper (Plugin): extension-host
└─ Cursor.app

When the agent turn ends, the harness reaps that zsh and the whole process group goes with it. This is why the failure had no fingerprints:

  • no crash report: ~/Library/DiagnosticReports had nothing for them;
  • no error in the app log: /tmp/zkpoker-web.log ends mid-SSR-render on an ordinary line and simply stops;
  • no OOM: the kernel log had zero jetsam events and the box was at 97% free memory;
  • not a crash loop: a crash loop keeps a listener most of the time. This left no listener at all.

It reproduced while being investigated: the console listening on 4600 as pid 54851 at 17:23 was gone by 17:27, replaced by pid 7535 from a different agent’s shell. Restarting by hand loses this race every time, which is why “restart it and confirm it works” was never a fix.

A second-order version of the same problem: several agent lanes each started their own copy of the same app on the same port, so they took turns evicting each other.

2. A hand-rolled supervisor was actively killing the daemon

Section titled “2. A hand-rolled supervisor was actively killing the daemon”

An earlier lane left this running:

Terminal window
while :; do SHC_MODULES=... make dev/run >> /tmp/shc-daemon-supervised.log 2>&1
sleep 3; done

make dev/run begins with make stop, and make stop does:

kill $(readlink .shc/run/shc.pid)
rm -f .shc/run/shc.pid .shc/run/shc.sock

So every three seconds that loop deleted the running daemon’s unix socket and then failed to start its own replacement with bind: address already in use. The daemon reported the damage honestly and nobody was reading it: X503048USKVNS unix_socket filesystem entry vanished, rebinding, every 30 seconds for hours. Downstream, every /api call through the dev proxy returned 502 because the socket path had no filesystem entry to connect to.

The supervised daemon now keeps its pid and socket in ~/.local/state/shc-dev/, outside the worktree, so make stop from any lane, test harness or editor task is a no-op against it rather than a kill.

3. Port 8000 was not the daemon: that is the 502

Section titled “3. Port 8000 was not the daemon: that is the 502”

shcd was healthy the whole time. It was not what answered.

A frappe bench belonging to a different checkout (frappe/multiplatform.one, started 07:33, orphaned to pid 1) held IPv4 *:8000. shcd came up later, and its bare :8000 listen produced a dual-stack IPv6 socket that coexists with the IPv4 one, but on BSD the more specific IPv4 socket wins every IPv4 connection. The result:

RequestReached
the host’s LAN address on :8000 (IPv4)the frappe bench
http://127.0.0.1:8000/ (IPv4)the frappe bench
http://[::1]:8000/ (IPv6)shcd, answering 401 X401900NOAUTH correctly

That bench reverse-proxies to a One dev server on :3456, which was itself an agent-session orphan and had died. A proxy with a dead upstream returns 502, so curling the host’s LAN address on :8000 returned 502 while shcd was perfectly fine one address family away.

The bench was stopped (it had no clients and no supervisor), and shcd now binds an explicit SHC_SERVER_TCP_BIND=0.0.0.0:8000 rather than a bare :8000, so a future squatter collides loudly at startup instead of silently shadowing the daemon on one address family.

A 401 from :8000 is the healthy answer. The public TCP listener requires a Keycloak bearer. Use :8003 for an authorized API in dev (below).

Newly visible: the console runs out of heap

Section titled “Newly visible: the console runs out of heap”

With real log files in place, a fourth failure showed up immediately: the console dev server died of FATAL ERROR: Ineffective mark-compacts near heap limit after about seven minutes of SSR churn. V8 caps old-space at ~4 GB regardless of machine size; this workstation has 512 GB. The node services now run with --max-old-space-size=8192. Unlike the faults above, this one was always a genuine crash; it was just invisible, because nothing was capturing stderr.


Each service is a per-user LaunchAgent, com.clayrisser.shcdev.<service>, written by scripts/devservers.sh into ~/Library/LaunchAgents/.

launchd is the point. It is the only parent on macOS that outlives every editor, terminal and session, and with KeepAlive it restarts a job within seconds whether it crashed, was kill -9’d, or lost a race with another lane. RunAtLoad brings everything back at login after a reboot. nohup/setsid would have survived the session but not a reboot, and would not restart on exit, and macOS ships no setsid anyway.

ServicePortBindWhat it is
shcd80000.0.0.0the daemon; 401 unauthenticated is correct
uds-proxy8003127.0.0.1unix socket bridged to TCP as local admin
console46000.0.0.0apps/console, proxies /api → :8003
marketplace47000.0.0.0apps/marketplace
zkpoker44560.0.0.0crypto-outlaws/zkpoker-ui/apps/zkpoker
storybook60060.0.0.0frappe/multiplatform.one/apps/storybook
Terminal window
scripts/devservers.sh install # write agents, reap strays, start all
scripts/devservers.sh install console # one service
scripts/devservers.sh status # listener + HTTP table, checked on the host's real IP
scripts/devservers.sh restart console
scripts/devservers.sh stop console
scripts/devservers.sh start console
scripts/devservers.sh logs console # tail -f
scripts/devservers.sh uninstall # remove all agents

status deliberately probes this host’s LAN address, not localhost. A loopback bind passes a localhost check and still fails the person testing from another machine, which is exactly how the :8003 bind bug survived.

stop is a launchctl bootout, not launchctl stop; with KeepAlive a plain stop is undone immediately.

~/Library/Logs/shc-dev/<service>.log

stdout and stderr both land there. Before this, the dev servers wrote to scattered /tmp/*.log files or to a terminal buffer that vanished with the session, and the console’s OOM crash had never once been seen by anyone.

Bind addresses, and what is not safe to widen

Section titled “Bind addresses, and what is not safe to widen”

Every HTTP service here except uds-proxy binds 0.0.0.0. This box sits on a private /20 and is driven from other machines on it, so a loopback-only bind on those services means they are not testable at all. That is a deliberate and appropriate choice for a dev workstation on a trusted private network.

uds-proxy is the exception. The generator defaults it to 127.0.0.1 (SHC_DEV_UDS_PROXY_BIND) and ignores $BIND_HOST, because the unix socket behind it authenticates every caller as the synthetic local admin.

uds-proxy on 8003 has no authentication. It bridges the daemon’s unix socket. A wide bind hands platform-admin to anything that can reach the port, with no token and no login. Loopback is the default so a host on the /20 cannot get there. Do not copy this service onto a shared, routed, or internet-facing listener.

The console and marketplace dev servers proxy /api to the daemon from the server side (apps/console/vite.config.ts), so a browser on another machine reaches the API through :4600 without ever touching :8003. That is the supported remote path. To widen the proxy anyway (you almost never want this):

Terminal window
SHC_DEV_UDS_PROXY_BIND=0.0.0.0 scripts/devservers.sh install uds-proxy

SHC_DEV_BIND_HOST still narrows every other service at once. It does not move uds-proxy.

zkpoker talks to backends that are still started by hand, and it will render but misbehave if they are down:

PortWhatWhere
8001frappe bench, site zkpoker.localhostzkpoker-ui/apps/frappe
9001socket.io realtimescreen -r zkpoker-socketio
8280keycloak (realm zkpoker)docker
8545hardhat localnetscreen -r zkpoker-hardhat
  • make dev/run and make stop still exist and still fight you. They target .shc/run/shc.pid, which the supervised daemon no longer writes, so they can no longer kill it, but make dev/run will fail with bind: address already in use while the supervised daemon holds 8000. Use scripts/devservers.sh restart shcd instead, or stop shcd first if you genuinely want a foreground daemon.

  • The shc CLI looks for the socket in the default location. The supervised daemon’s socket is out of the worktree, so point the CLI at it:

    Terminal window
    SHC_SOCKET_PATH=~/.local/state/shc-dev/shc.sock bin/shc ls

    Without it the CLI reports X503931DMNDWN the shc daemon is not reachable on this node, with a hint about systemctl that does not apply on macOS.

  • A broad pkill -f shcd from another lane still reaches this daemon, and there are several other shcd binaries running on this box from other worktrees, so that pattern gets used. It is no longer fatal: launchd brings the daemon back within seconds and runs = N in launchctl print gui/$UID/com.clayrisser.shcdev.shcd tells you it happened.

  • Do not start these from an agent shell or an editor terminal again. That is the whole bug. If a service needs different flags, change scripts/devservers.sh and re-run install, so the change is versioned and the process still belongs to launchd.