StarPilot/openpilot/starpilot/galaxy/README.md

Galaxy companion

Galaxy is StarPilot's Vue browser interface for device status, saved preferences, and local tools. The managed service listens on port 8082. On the device's local network, open the address and QR code shown by the native Galaxy page. Direct local connections establish a browser session automatically. Remote or proxied connections use the existing password-backed session; account pairing and a managed remote tunnel are not available.

Run and test

./dev galaxy starts a desktop server on loopback. The Python entry point is python -m openpilot.starpilot.galaxy.server; its default host is 127.0.0.1. Use --host 0.0.0.0 only when a LAN bind is intended. The managed service is selected by the manager and can be disabled with STARPILOT_GALAXY_DISABLE=1 in the manager environment. A manual server cannot share its port with the managed service. Static browser files are under web/, with no JavaScript package installation required.

For frontend or backend work, ./dev galaxy --live [--port N] builds the shared host cache, releases its lock so ./c3, ./c4 and ./onroad can run alongside, then follows edits under this package. An open page reloads itself after each edit; other changes here restart the server first. Refresh a page opened before the session once. Edits outside the package need ./dev sync and a restart. The reload script exists only in the host cache, never in this directory. Unsaved drafts and pending saves defer automatic reload until they are resolved. Add --no-autoreload to keep following edits but refresh by hand. Only one live Galaxy session can own a shared host cache at a time, regardless of port. Run the package tests with ./dev pytest openpilot/starpilot/galaxy/tests. Browser JavaScript tests use Node 24; set STARPILOT_NODE to an existing Node 24 executable when needed. A static preview can serve web/ over loopback; it labels its sample System Monitor data and cannot edit a device.

Pages and owners

Page	Current source and operations
Home and Tools	Local status cards, navigation, theme, drawer, pinned tiles, and hash routes.
System Monitor and Plots	Bounded local process/device and driving-message samples. Unavailable data stays unknown; leaving a page stops its polling.
Logs and Routes	Crash-report previews and a shared route workspace for camera footage, driving UI replay, segment details, and scoped footage/replay/log downloads.
Software & Updates	Read-only installed and updater status. Refresh rereads reported Params; it does not check, download, switch branches, install, roll back, or reboot.
Driving and Device Preferences	Saved settings through typed owners shared with native controls, including SLC, lateral and longitudinal tuning, conditional modes, display, cameras, and sounds.
Vehicle Controls	One saved manual vehicle choice for the next start, or Auto for normal detection.
Models and Model Laboratory	Verified model catalog management and parked Laboratory configuration. Paired inference is unavailable in the production model runner.
Bluetooth	Local BlueZ adapter and device operations, including pairing confirmation. Bluetooth audio routing is unavailable.
Maps	Local map status and a parked catalog-region download, progress, or cancellation. A completed selection takes effect at the next map service start.
Cameras and Sentry	Saved PiP and V-ASM settings and bounded Sentry event metadata. The crop editor uses a browser-local still image; it does not upload that image.
Sound packs	Catalog status, verified download and cancellation through the local sound owner.
Galaxy Access & Install	Remote link pairing, Galaxy installation, and an opt-in Wi-Fi hotspot. Local addresses are on Home.

The Vue router in web/js/app.js and the route handlers in server.py are the current route map. API groups include /api/auth, /api/system/monitor, /api/software/status, /api/settings, /api/models, /api/maps, /api/sounds, /api/bluetooth, /api/vehicle-selection, /api/recordings, /api/replay, /api/sentry/events, and /api/flm. An unknown API route returns an error; there is no arbitrary Params or shell-command endpoint. The retired POST /api/companion cross-origin bridge is no longer supported. Local hotspot access uses the same authenticated, same-origin HTTP API as local Wi-Fi.

Access and operation rules

The hotspot is off by default. While parked, open Galaxy Access & Install → Galaxy Wi-Fi Hotspot, enable automatic broadcast, and save a password (12–63 printable ASCII characters without spaces). Join TheGalaxy-<last four characters of dongle ID> and bookmark http://172.31.254.1:8082/; stay connected if your phone warns of no Internet. Saved settings survive restarts. It runs without Android Auto or another Wi-Fi connection, requires an available Wi-Fi radio, and follows connected Wi-Fi/Android Auto's channel. Network changes may interrupt access; changing the password or disabling it disconnects clients. It provides no Internet gateway; the public Galaxy link still needs Internet and its tunnel. Sustained projection and standalone reconnects still need hardware validation.

The server requires the actual peer and socket destination to be local for passwordless access. Proxy headers select the password-backed path. The Host must match the destination address, and JSON writes require that same origin. Sessions use opaque HttpOnly, SameSite=Strict cookies; a local session cannot authorize a remote request. A session is checked again after slower reads and before sensitive results are returned. The server bounds connections, request bodies, file reads, and operation concurrency.

Saved-setting writes use an authenticated preview/confirm transaction. Their owners recheck current saved-source identity, vehicle eligibility, and fresh offroad evidence before committing. A saved choice is not proof that a driving feature is active. Map, model, Bluetooth, sound, and other operations each have their own authority checks; browser text is never a command to execute. A lost save response has an unknown outcome: refresh before repeating an action.

Status endpoints distinguish missing, invalid, stale, or changed inputs from valid zero values. Crash and recording readers recheck file identity and skip active or symlinked sources. Camera footage is remuxed from closed segments in a bounded temporary cache. Combined footage and log archives are limited to 512 MB; larger routes use individual segment downloads. Plots and System Monitor stop or retire requests when hidden, signed out, expired, or superseded. Sample rates and message ages describe observed data, not driving-control timing.

Routes keep one selected segment across Footage and Replay with UI. Raw camera and log downloads use a complete selected-route inventory, bounded at 512 segments; the route list uses a smaller summary. Replay uses the existing parked-only owner, so native replay, browser preview, and export cannot run competing renderers.

Replay exports render camera and UI together at normal speed, then stream-copy into a validated MP4. Segment exports end at the engine's recorded segment boundary; route exports concatenate replayable recorded ranges and omit gaps. An export freezes the last preview's display settings for the same browser and route, or snapshots the current display settings when no preview exists. Closing or hiding Galaxy stops its preview but leaves its export running; explicit Cancel stops it. The browser receipt survives a page refresh within the same authenticated session while Galaxy remains running. Authority loss, source changes, time limits, or insufficient storage stop the job.

Only one completed export is cached, for 30 minutes or until replaced/deleted. An active download holds the file against eviction. The owner reserves the larger of 5 GiB and 10% of storage, budgets for spool plus final MP4, and caps exports at 32 GiB. Completed exports are private, authenticated, range-capable downloads; owner restart clears the cache. Device replay binaries must be rebuilt with the matching source. GPU rendering and the hardware encoder require device validation.

Galaxy does not provide cloud drive history, remote account setup, or updater actions. See model contracts for Laboratory runtime eligibility and map operations for offline-region ownership.

Source and notices

The UI adapts StarPilot's earlier Vue Galaxy design; the adapted StarPilot source remains under the repository LICENSE. The bundled Vue and Bootstrap Icons assets retain their respective MIT notices in web/vendor/notices/. Other asset notices remain beside their files.