Native AppKit menu-bar app for the controlled Mac. It renders the host-derived
menu-bar model and forwards operator actions to the host's loopback,
token-authenticated local-control surface — the shell never re-implements
enable/disable, tone, or label rules, so the TypeScript contract
(src/macos-host-support.ts → deriveMacOSMenuBarModel) stays the single
source of truth.
Architecture#
Sources/BellonaRemoteHostShell/main.swift— entrypoint; one binary, two invocations: a normal login-session launch and--run-as-agentunder launchd (the LaunchAgent plan'sProgramArgumentsrun this same executable).ShellController.swift— NSStatusItem + NSMenu rendered every 2 s fromGET /v1/local-control/menu-bar-model; controls post topause/resume/stop-session/unpair/diagnostics; unpair is guarded by a destructive confirmation alert; diagnostics reveals the written snapshot in Finder.LocalControlClient.swift— loopback HTTP client; reads the owner-only token file the host mints next to its identity file, and self-heals by poking the (401) state endpoint when the token file does not exist yet.HostProcessSupervisor.swift— spawns and supervises the Node remote-host child whenBELLONA_SHELL_HOST_COMMANDis set: unexpected exits restart with a 5 s backoff; a graceful shell shutdown (Quit control or SIGTERM fromlaunchctl kill TERM) forwards SIGTERM so the host cancels running commands, disconnects from the gateway, and flushes before exit. Without a command the shell runs attach-only against an externally managed host.
Build and bundle#
cd apps/bellona/remote-host/macos
scripts/bundle-app.sh # swift build -c release + assemble
open "dist/Bellona Remote Host.app"
The bundle sets LSUIElement=true (menu-bar only) and bundle id
com.oshun.bellona.remote-host. Signing/notarization is the separate, gated
180.C.26.06 step; this script produces an unsigned bundle for development and
hardware-evidence runs.
Configuration (environment)#
| Variable | Meaning | Default |
|---|---|---|
BELLONA_SHELL_HOST_PORT |
Host health/local-control port | 4071 |
BELLONA_SHELL_TOKEN_PATH |
Local-control token file | ~/.oshun/bellona/local-control.token |
BELLONA_SHELL_HOST_COMMAND |
argv (JSON array or space-split) to spawn the host | empty → attach-only |
BELLONA_SHELL_HOST_CWD |
Working directory for the host command | inherited |
BELLONA_SHELL_CONTROL_ROOM_URL |
URL for the "Open Control Room" control | unset → control explains how to configure |
Live evidence run#
apps/bellona/remote-host/scripts/macos-menu-bar-shell-evidence.ts boots the
REAL gateway and REAL host in one process with a gateway-issued development
identity so the shell can be exercised against live host state:
cd apps/bellona/remote-host
npx tsx scripts/macos-menu-bar-shell-evidence.ts /tmp/bellona-shell-evidence
# parse the printed {"ready":true,...} line for ports/paths, then:
BELLONA_SHELL_HOST_PORT=<hostPort> \
BELLONA_SHELL_TOKEN_PATH=<tokenPath> \
"./macos/dist/Bellona Remote Host.app/Contents/MacOS/Bellona Remote Host"
The 2026-07-07 MAC-HOST-03 closure runs for 180.C.26.01 and 180.C.26.02
(including the full launchd lifecycle) are documented in
docs/domains/bellona/extras/remote-control/evidence/180.C.26.01/ and
.../180.C.26.02/.