docs/NETWORK-ACCESS.md
Run on your Mac mini, view from your laptop
Keep Palantir running on one computer and open its dashboard from another through an SSH tunnel. The same computer can be both server and viewer, or an always-on Mac mini can serve your laptop. No second observer installation is needed just to view it.
What runs where?
| Mac mini — the host | Laptop — the viewer |
|---|---|
| Bun service, public feed connection, local history and saved server data | Browser UI and WebGL 3D rendering |
| Connected RS-SDK folder and friendly-name discovery | Its own camera layout and browser preferences |
| Installed agent CLIs, credentials and local gameplay harness | A private SSH connection to the host |
The browser, API and viewer WebSocket use the same forwarded address. Multiple browsers reach the same service and saved server data. Focus details still moves one shared observation area: focusing a camera from one device can change detailed coverage for another. Browser layouts and camera preferences do not automatically synchronize between devices.
The host must remain running and awake. Closing a laptop browser does not stop the Mac mini service. Closing the SSH tunnel disconnects that viewer; it does not stop the host or its bots.
1. Prepare the host
Install and build Palantir on the Mac mini using the README, then start it from its installation folder:
| 1 | pnpm run start |
Verify http://127.0.0.1:5197 on the Mac mini. In Settings → Project & fleet, choose the RS-SDK folder on the Mac mini. When you later open Settings from the laptop, folder browsing still refers to the host filesystem, not the laptop.
Use an SSH account you already control on the host. On macOS, SSH access is managed through Remote Login. The host can be reached over your LAN or an already configured private network such as Tailscale. This guide does not enable Remote Login, join a network or change access permissions automatically.
2. Open the tunnel on your laptop
Replace USER with your SSH account and MAC_MINI_HOST with the host’s configured LAN hostname/address or private-network name. Run this in a terminal on the laptop:
| 1 | ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \ |
| 2 | -L 127.0.0.1:5197:127.0.0.1:5197 USER@MAC_MINI_HOST |
Complete your normal SSH authentication and leave the command running. Open http://127.0.0.1:5197 in the laptop browser. Requests travel through SSH to Palantir on the mini; the laptop is not running a second observer. Press Ctrl+C in the tunnel terminal when finished.
Repeat the tunnel setup on each additional desktop/laptop that should access this same host. The local listener is explicitly restricted to 127.0.0.1 on each viewing device. Anyone granted this tunnel can reach the host’s local app; it is not a separate read-only guest account. Gameplay and agent execution still require their existing in-app approvals.
Match the ports. Palantir checks its Host and Origin, including the port. If 5197 is occupied on the laptop, do not forward laptop port 5198 to host port 5197. Choose the same unused port on both ends. For a host deliberately started with PORT=5198 pnpm run start, use:
| 1 | ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \ |
| 2 | -L 127.0.0.1:5198:127.0.0.1:5198 USER@MAC_MINI_HOST |
Then open http://127.0.0.1:5198. Keep the host’s chosen port consistent across viewers.
What is shared, and what stays local?
- Shared through the host: live feed, friendly roster from the connected host folder, saved service records and collected history. One service owns its runtime databases.
- Specific to each browser: monitor layout, camera preferences and other browser-local UI state. Opening the same app on a different device does not copy those preferences.
- Specific to the host machine: installed local agents, credentials, RS-SDK files and gameplay harness. Opening the dashboard from a laptop does not discover that laptop’s CLIs or bot folders. External agents require their own configured connections.
- Rendering performance: the viewing device draws the 3D world. Hosting on a Mac mini improves service availability; it does not offload the laptop’s WebGL rendering or guarantee lower latency. Use fewer visible cameras on smaller devices.
For a laptop-based MCP client, run the MCP bridge from a Palantir checkout on the laptop and point RS_WATCH_URL at the matching forwarded localhost port. The Settings-generated stdio snippet contains the server’s installation path; that path is only directly usable by a client on the server. Adapt the bridge path to the laptop’s checkout instead of copying a Mac mini path blindly. The bridge does not require a second observer server.
Troubleshooting and current limits
| Symptom | Check |
|---|---|
| Connection refused | Is Palantir running on the host’s chosen port? Is the SSH tunnel still open? |
| Address already in use | Another service already occupies the laptop port. Use a matching available port on host and laptop. |
| Local access only / Origin not allowed | Use http://127.0.0.1:PORT through the tunnel, with the same port as the host service. |
| Different bots or missing history | You may have opened a separate local installation. Confirm which computer the tunnel reaches and which RS-SDK folder that host uses. |
| Map moves but NPC detail disappears | Another camera/device may have moved the shared detail area. Check coverage before selecting Focus details. |
| Map is slow | Reduce visible cameras and check the viewer’s GPU, network and feed age. A tunnel does not increase source freshness. |
A direct http://mac-mini.local:5197, LAN IP or Tailscale IP URL is not supported by the current loopback-only server. Tailscale can carry SSH; simply installing Tailscale or enabling Serve does not change the app’s Host/Origin policy. Direct private HTTPS/domain access needs a reviewed deployment configuration and authentication work; see deployment boundaries.
The UI has responsive and touch controls, but this is not automatic phone/tablet network access. Those devices need a compatible tunnel client that exposes the same local port to their browser; that device-specific setup has not been validated for this source preview.
Installing Palantir separately on two Macs is also possible, but creates separate local data and configuration. Keep their code current through GitCafe; do not share a writable SQLite database between installations.
Verification
For this guide, source inspection confirmed loopback binding, port-specific Host/Origin checks and same-origin viewer connections. The documented OpenSSH options were parsed locally; the running app accepted the matching localhost host/port and rejected mismatched-port and LAN-style Host headers. This documentation update did not establish or test a new connection to your Mac mini.
Reference: OpenSSH local forwarding and -N. Tailscale’s Serve documentation describes a different exposure mechanism; it is not the tunnel recipe above.