Remote Access GUI Toggle

Goal

A Remote access card on the dashboard's Settings > Advanced tab: a master toggle (Allow remote access) plus a scope picker (Tailscale only, recommended/default, vs All interfaces). Flipping it persists to the settings DB and immediately restarts the service with the new bind. The settings DB becomes the single source of truth for the bind host; CLI --host becomes a one-shot explicit override that is never persisted. Autostart artifacts stop baking --host, so reboots and upgrades honor whatever the GUI last said.

Decisions Already Made (do not re-litigate)

Pre-existing Bugs This Fixes (verified first-hand)

• Upgrade reverts the bind: jacked install has no --host flag and unconditionally regenerates autostart with DEFAULT_HOST (_setup_tray_autostart → _ensure_autostart_and_running(DEFAULT_HOST, DEFAULT_PORT), cli.py:2692-2708). Both upgrade paths (system.py:_do_upgrade runs jacked install --force; tray updater at updater.py:300-322 likewise) therefore silently revert a user's 0.0.0.0 plist to loopback on every upgrade.
• service restart --host X is a silent no-op on macOS when a plist is loaded: native_restart() runs launchctl kickstart -k (platform.py:21-60), which reuses launchd's in-memory plist definition and ignores the new host; cli.py:3364-3377 returns early on native-path success.
• install_autostart never unloads before launchctl load (platform.py:245-261): rewriting the plist over an already-loaded label silently keeps the old in-memory definition until reboot. Fix: bootout-then-bootstrap (or unload/load) so plist changes take effect.

Architecture

flowchart TD
    GUI[Settings > Advanced card] -- PUT /api/settings/remote-access --> DB[(settings table\nremote_access_enabled\nremote_access_scope)]
    GUI -- POST /api/settings/remote-access/restart --> RS[restart: execv POSIX /\ndetached respawn Windows]
    RS --> BOOT[service boot]
    CLI[explicit --host flag\none-shot override] --> RES
    BOOT --> RES[resolve_bind in jacked/service/bind.py\nflag > DB > loopback]
    DB --> RES
    RES --> DET[Tailscale IP detection\nUDP route trick + CLI fallback]
    RES --> SOCK[pre-bound socket set\nSO_REUSEADDR]
    SOCK --> UV[uvicorn Server.run sockets=...]
    RES --> ENV[JACKED_HOST env\nCORS/CSRF/lifespan]
  

flowchart TD
    GUI[Settings > Advanced card] -- PUT /api/settings/remote-access --> DB[(settings table)]
    GUI -- POST /api/settings/remote-access/restart --> RS[restart]
    RS --> BOOT[service boot]
    CLI[explicit --host flag] --> RES
    BOOT --> RES[resolve_bind: flag > DB > loopback]
    DB --> RES
    RES --> DET[Tailscale IP detection]
    RES --> SOCK[pre-bound socket set]
    SOCK --> UV[uvicorn Server.run sockets=...]
    RES --> ENV[JACKED_HOST env]
  

Bind Resolution — new module jacked/service/bind.py

resolve_bind(cli_host: str | None, port: int) -> BindPlan
# precedence: explicit CLI --host (one-shot, never persisted)
#             > DB setting (remote_access_enabled/scope) > loopback default
# BindPlan: mode ('loopback'|'tailscale'|'all'), sockets spec,
#           primary_host (feeds JACKED_HOST), tailscale_ip | None,
#           fallback_reason: str | None (tailscale requested but not detected)

• Socket sets are mutually exclusive (avoid EADDRINUSE overlap): loopback → [127.0.0.1]; tailscale → [127.0.0.1, 100.x]; all → [0.0.0.0] alone (never 0.0.0.0 plus another socket on the same port).
• Sockets pre-bound with SO_REUSEADDR, created fresh per (re)start, handed to uvicorn. Verified: uvicorn 0.46.0 Server.run(sockets=[...]) and Server.serve(sockets=[...]) both accept socket lists.
• Both launch sites move to the socket path: tray ServiceRunner._start_uvicorn (tray.py:310-326, currently uvicorn.Config(host=...) + server.run() in a daemon thread → becomes server.run(sockets=...), minimal change to the threading model) and webux (cli.py:240-277, currently uvicorn.run(host=...) → same Config/Server.run(sockets=...) shape). webux --reload stays single-host CLI-only (uvicorn's reloader subprocess can't inherit pre-bound sockets); document in help text.
• Readiness/port checks must follow the socket set: ServiceRunner._wait_for_ready (tray.py:336), _wait_for_port_free (tray.py:359), and is_port_available(self.host, ...) (tray.py:1011) currently target self.host; they must target the resolved sockets (and never hard-fail the boot on a vanished pinned IP; see detection fallback). _service_http_ok (cli.py:280-309) already always probes loopback and stays as-is.
• JACKED_HOST env channel (read by lifespan main.py:214-218, CSRF guard security.py:266-270, import-time CORS main.py:355): set to the primary non-loopback host when remote is on (the 100.x IP, or 0.0.0.0), loopback otherwise. The lifespan refreshes _cors_origins in place (main.py:226), so a restart picks everything up.
• Argv stops lying: _spawn_service_detached (cli.py:334) currently bakes --host into the service argv unconditionally (svc_args = ["service","start","--host",host,...]); it must pass --host ONLY when the user explicitly typed one (thread explicit-ness through jacked start, whose click default is already None, cli.py:385). This is what makes os.execv(sys.argv[0], sys.argv) (system.py:805) re-resolve from the DB on upgrade restarts. The webux click decorator's hardcoded default "127.0.0.1" (cli.py:241) becomes None so "no flag" is distinguishable from "explicit loopback".

Tailscale IP Detection (stdlib-only)

• Primary: connected UDP socket to 100.100.100.100:80 (Tailscale's service IP; UDP connect sends no packets), getsockname() yields the local address; accept only if inside 100.64.0.0/10 (use ipaddress).
• Fallback: shell out to tailscale ip -4 (use winproc.NO_WINDOW on Windows; short timeout; tolerate missing binary).
• Both fail → bind loopback only, log loudly, record fallback_reason so the GUI status line shows "Remote access is on, but Tailscale wasn't detected at startup; currently loopback only." Never silently widen to 0.0.0.0; never crash the boot. Re-detect on every restart. No live interface-watcher: Tailscale node IPs are stable by design; the status line plus re-apply-on-restart covers it.

Storage and API

• Settings keys: remote_access_enabled, remote_access_scope ("tailscale" | "all") in the existing settings table (jacked/web/database.py:239-243; get_setting/set_setting at 1444-1533 are sync, usable at boot outside any request: Database().get_setting(...), DB path ~/.claude/jacked.db).
• Add both keys to _PROTECTED_SETTING_KEYS (system.py:902-916) so the generic PUT /api/settings/{key} can't clobber them.
• New router jacked/api/routes/settings_remote.py copying the settings_swap.py pattern (Pydantic model + validation). Register before system.router in main.py (like swap_settings_router at main.py:465) or system's catch-all PUT steals the routes.
• GET /api/settings/remote-access → {enabled, scope, effective: {addresses: [...], tailscale_ip, fallback_reason}}. effective reflects what the server ACTUALLY bound at startup (BindPlan stored on app.state) so the UI never lies about live state.
• PUT /api/settings/remote-access → validates + persists, returns the same shape.
• POST /api/settings/remote-access/restart → broadcasts restart_started WS event, sleeps ~1.5s to flush, restarts (below). Separate from PUT so save and apply stay distinct (mirrors upgrade).

Restart Mechanics

• Service/tray (all platforms): in-process restart via the registered _on_restart handler, as above. No execv, no PID churn, no detached respawn needed.
• webux foreground (no handler registered): os.execv(sys.argv[0], sys.argv), the upgrade flow's proven pattern (system.py:779-805); argv no longer carries --host, so the fresh process re-resolves from the DB. Windows execv is spawn-and-exit emulation, acceptable here because there is no tray to orphan.
• Frontend reuses the upgrade modal + _startHealthPolling (header.js:128-140: "Restarting…", poll GET /api/health every 1.5s, location.reload() on ok, 30s deadline). WS handler map (websocket.js:473-489) gains restart_started wired to the same modal functions.
• Lockout case: when window.location.hostname is not loopback (127.0.0.1/localhost/::1) and the action disables remote access (or a scope change drops the current origin), the confirm dialog warns the user is cutting themselves off, and after confirming, the modal shows a terminal "reopen from the machine itself" message instead of health-polling forever.

Frontend (Settings > Advanced)

• Vanilla JS, no bundler: jacked/data/web/js/components/settings.js (tab bar at 40-46, renderAdvancedTab at 1227). Copy the auto-swap settings pattern (auto-swap.js:131-133, 753-799: checkbox → debounced save → api.put → toast), NOT the features toggle (that PUTs /api/features/...).
• Card contents: master toggle, scope radio pair (Tailscale only = default with "recommended" badge; All interfaces = danger styling), live status line from effective ("Listening on 127.0.0.1 + 100.64.12.7 (Tailscale)" / fallback warning state), and the URL hint (MagicDNS name / IP) when remote is active.
• Confirm dialog copy carries the real exposure story; "All interfaces" variant is explicitly loud (unauthenticated dashboard incl. account switching + upgrade endpoint reachable by anyone on the LAN; Tailscale ACL example pointer). No em-dashes in any user-facing copy (use commas/colons/parens; plain hyphen if a dash is unavoidable).
• Follow existing dashboard styling; press/hover feedback, real loading/error states on the card (it fetches GET /api/settings/remote-access on tab render).

Autostart Artifacts and Migration

• Drop the --host pair (keep --port) from _generate_launchd_plist (platform.py:149-194, bake at 171-174) and _generate_windows_vbs (platform.py:197-219, bakes at BOTH 213-214 and 217-218). install_autostart (platform.py:231) loses its host param; update ALL bake sites: tray.py:592 (_on_toggle_autostart passes self.host), cli.py:3449 (service_install), _ensure_autostart_and_running, and ensure_native_lifecycle's in-process install_autostart() call (platform.py:117).
• Fix the launchctl caching bug: install_autostart becomes bootout-then-bootstrap (tolerate "not loaded" on bootout) so a rewritten plist actually takes effect.
• Data-preserving migration: when jacked install --force (which every upgrade runs) or service boot finds an existing plist/VBS with a baked --host: parse the host out FIRST and copy it into the DB (0.0.0.0 → enabled+all; a 100.64.0.0/10 IP → enabled+tailscale; loopback → leave settings untouched/disabled), THEN regenerate host-free and reload. Existing service install --host 0.0.0.0 users keep their bind instead of losing it.
• CLI parity: jacked service install --host X and jacked service restart --host X now write the DB setting (X=0.0.0.0 → enabled+all; X in 100.64/10 or X omitted-but-remote-was-on → respect scope; X=127.0.0.1 → disabled), then restart. This makes them finally work reliably on macOS (native_restart's kickstart now picks up the DB on boot). Update the flag help text: the GUI toggle is the primary interface.
• Linux: no artifact is generated today (platform.py:222-228, 270-274); the DB read at service start makes the toggle work there automatically. Docs: systemd-unit authors must not bake --host in their own unit's ExecStart.

Security Posture

• No security.py trust-model changes needed (verified): host_header_allowed already accepts IP literals + *.ts.net + single-label MagicDNS names (security.py:135-162); origin_allowed's same-origin fallthrough (security.py:165-197) means pages served from http://100.x:8321 or MagicDNS FQDNs pass WS origin (main.py:397-414) and CSRF (security.py:260-280) checks unchanged. build_allowed_origins never wildcards (security.py:75-90).
• Lifespan's existing non-loopback warning log (main.py:259-266) stays; add the tailscale-fallback-to-loopback log line.
• Dialog copy = the real exposure story. Tailscale ACL example stays in README.
• After implementation: security review pass (auth-adjacent surface: a GUI control that widens network exposure + a restart endpoint) before merge. /cso must report no high/critical findings.

File Structure

Testing Plan

• resolve_bind precedence matrix: flag > DB > default; explicit flag never persists.
• Socket-set construction per mode incl. 0.0.0.0 exclusivity (never 0.0.0.0 + another socket same port).
• Tailscale detection: mocked UDP route trick, mocked CLI fallback, both-fail → loopback + fallback_reason logged (never wider, never crash).
• Migration parser: plist/VBS with baked 0.0.0.0 / 100.x / 127.0.0.1 / no host → correct DB writes, host-free regeneration.
• Settings router: validation, protected-key guard on generic PUT, effective-state shape.
• Restart path selection: POSIX execv vs Windows detached respawn (mock sys.platform).
• Multi-socket integration: Server.serve(sockets=[two pre-bound loopback sockets on different ports]) against the real app; both answer /api/health (proves the serving model without a tailnet in CI).
• test_network_security.py extensions: Host/Origin cases for a concrete 100.x:8321 (some exist at :94/:152); effective-state endpoint.
• Frontend JS via node-harness pattern (tests/unit/test_web_js_swap_ui.py): render, save flow, confirm-dialog branches, lockout branch.
• Full CI replication locally (uv run python -m pytest) before push.

Milestones (build order)

1. bind.py: resolve_bind + BindPlan + socket sets + tailscale detection, fully unit-tested.
2. Serving paths: tray + webux on Server.run(sockets=...); JACKED_HOST fed from BindPlan; readiness checks fixed; multi-socket integration test green.
3. API: settings_remote router (GET/PUT/restart) + protected keys + restart mechanics (POSIX/Windows) + restart_started WS event.
4. Frontend: Advanced-tab card, dialogs, status line, lockout guard, restart overlay; JS tests.
5. Autostart: generators drop --host, bootout/bootstrap fix, data-preserving migration, CLI parity (service install/restart write DB).
6. Docs: README Remote Access rewritten GUI-first; CLI help text updated.
7. Gates: full local CI, browser QA of the flow, security review, code review; PR.

Generated with the jacked HTML artifact template. Edit freely.