Remote access

Remote access serves Jimothy’s full UI to your other devices — typically your phone — over your Tailscale network. You can watch runs, read logs, approve or reject, start runs and edit settings from anywhere your tailnet reaches. Nothing is exposed to the public internet.

Requirements

• Tailscale installed and signed in on the computer running Jimothy, and connected.
• Tailscale on the phone (or other device), signed in to the same tailnet.
• Recommended: HTTPS certificates enabled for your tailnet (Tailscale admin console → DNS → HTTPS Certificates). Without them, Jimothy falls back to plain HTTP (see below).

Jimothy finds the tailscale CLI on the PATH it uses for harnesses, or at /Applications/Tailscale.app/Contents/MacOS/Tailscale, /opt/homebrew/bin/tailscale, /usr/local/bin/tailscale, /usr/bin/tailscale.

Turn it on

1. Open Settings → Remote access and switch on Use Jimothy from your phone and other devices on your Tailscale network. The switch applies immediately (no need to click Save).
2. Wait for Connecting to Tailscale… to finish. You’ll see a QR code and the address, e.g. https://my-mac.tail1234.ts.net:7443.
3. On your phone, scan the QR code with the camera. It opens a sign-in link, which signs the browser in and redirects to the app.
4. Optional: on iOS use Share → Add to Home Screen (Android: Add to Home screen) to install it like an app. This needs the HTTPS address.

The card also has Address (copy the plain URL), Sign-in link (copy the link that contains your access token; treat it like a password) and Sign out all devices.

Settings

Field	Default	Notes
Use Jimothy from your phone…	off	Applies immediately.
Local port	7718	Port of Jimothy’s remote server. Loopback only; Tailscale forwards to it.
Tailnet HTTPS port	7443	The HTTPS port your devices connect to. Use 443 for an address without a port.

Port changes take effect when you click Save on the Settings page.

What happens when you turn it on

1. Jimothy runs tailscale status --json and checks that Tailscale is Running. It reads the machine’s DNS name (e.g. my-mac.tail1234.ts.net), its Tailscale IPv4 address, and whether HTTPS certificates are available for that name.
2. With HTTPS certificates (the normal case):
   • Jimothy’s remote server listens on 127.0.0.1:<Local port> only.
   • It checks tailscale serve status --json. If something else is already served on the HTTPS port, it stops with Tailscale is already serving something else on port 7443. Pick another HTTPS port.
   • It runs tailscale serve --bg --yes --https=<Tailnet HTTPS port> http://127.0.0.1:<Local port>.
   • If Funnel (public internet exposure) is enabled on that port, it refuses and stops: Tailscale Funnel is enabled on port 7443, which would expose the factory to the internet. Run tailscale funnel --https=7443 off and try again.
   • The address is https://<machine>.<tailnet>.ts.net:<port> (no port for 443), with a real certificate.
3. Without HTTPS certificates (fallback):
   • The server listens on 127.0.0.1 and the machine’s Tailscale IPv4 address, on Local port.
   • The address is http://<machine name or IP>:<Local port>, e.g. http://my-mac.tail1234.ts.net:7718.
   • A warning explains that traffic is still encrypted by Tailscale but the page is plain HTTP, so it can’t be installed as an app, and how to fix it: turn on HTTPS certificates in the Tailscale admin console (DNS page), then toggle remote access off and on.

Turning remote access off (or quitting Jimothy) closes the server and runs tailscale serve --yes --https=<port> off for the port it set up. Jimothy only touches the serve entry on its own HTTPS port and never enables Funnel.

Signing in and sessions

• Jimothy keeps one access token (32 random bytes), stored encrypted in remote.json in the data folder.
• The QR code encodes https://<address>/pair?t=<token>. Opening it sets a session cookie and redirects to / so the token doesn’t stay in the address bar or history.
• Devices that aren’t signed in are sent to a sign-in page: Scan the QR code in Settings → Remote access on your computer, or paste the sign-in link below. You can paste the whole link or just the token.
• The session cookie (sf_session) is HttpOnly, SameSite=Lax, lasts one year, and is Secure on HTTPS.
• Sign out all devices issues a new token. Every paired phone and browser is disconnected and must scan the new QR code.

What works remotely

Everything in the UI except a few desktop-only actions:

Not available remotely	Why
Folder pickers (Browse, Choose folder)	They open a native dialog on the computer. Type paths instead.
Open workspace in editor, Reveal workspace folder	They’d open on the computer, not your device.
Managing remote access itself	The Remote access card shows You’re connected remotely… Manage remote access from the desktop app. Saving settings from a remote device never changes the remote-access settings.

Links (issues, PRs, docs) open on the device you’re using.

The remote UI receives live updates (runs, logs, inbox) over a server-sent events stream and resynchronises automatically after your phone sleeps or changes networks.

Security model

• The HTTP server never listens on a public interface. With HTTPS it only listens on loopback, and Tailscale forwards tailnet traffic to it. In HTTP fallback mode it also listens on the Tailscale IPv4 address.
• Only devices on your tailnet can reach it, and they also need the access token.
• API calls require a JSON content type, which blocks cross-site form posts from other websites.
• The API also accepts Authorization: Bearer <token>, which is handy for scripts on your tailnet. See API reference.

Anyone with the sign-in link or token has full control of Jimothy, including starting runs that execute agents on your computer. Don’t share it; use Sign out all devices if it leaks.

Troubleshooting

Message	Fix
Tailscale isn’t installed. Install it from tailscale.com/download and sign in.	Install Tailscale, or add its directory to Settings → Extra PATH entries.
Tailscale is not connected (Stopped) / (NeedsLogin)	Open Tailscale and connect / sign in.
This machine has no Tailscale IPv4 address.	HTTP fallback needs an IPv4 tailnet address. Enable HTTPS certificates instead, or check your tailnet’s IP settings.
Tailscale is already serving something else on port …	Change Tailnet HTTPS port, or remove the other serve config.
Tailscale Funnel is enabled on port …	Run the tailscale funnel … off command shown, then toggle remote access off and on.
Port already in use	Change Local port.
Phone can’t open the address	Make sure Tailscale is connected on the phone, to the same tailnet.
Sent back to the sign-in page	The token was reset. Scan the new QR code.