Skip to content
Novaterra

Novaterra on your phone

A phone is a Leaf

A phone cannot host a node. iOS terminates background processes, so there is no Fastify server, no SQLite file and no sandbox living on an iPhone. In the node profiles — Seed, Leaf, Home, Hall — a phone is a Leaf: a client of somebody’s node rather than a node itself.

So there is no separate mobile app to install. The thing you put on your home screen is the web app, pointed at a node that is running somewhere else: your desktop on the same wifi, or a node you have published.

Reaching your node on the same wifi

By default the dev server binds the loopback only, so nothing outside the machine can reach it. Bind it to the network on purpose:

NOVA_LAN=1 pnpm --filter @novaterra/web dev

Vite then prints every address it is listening on. Use the one on the same network as your phone — on a laptop that is usually the Wi-Fi adapter’s address, something like 192.168.x.x:

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.100.20:5173/

Open that Network address on the phone. Note the port is the web app’s, not the API’s. Do not point the phone at :4000: the API allows a fixed list of CORS origins, your phone’s address is not on it, and a browser will drop every credentialed response. The web server proxies /api to the node, so the page and its API calls share one origin, there is no cross-origin request to have an opinion about, and the session cookie is stored and sent exactly as it is on localhost.

You log in on the phone the same way you do anywhere: the same account, the same password.

NOVA_LAN=1 puts your node’s whole web surface on the network with no password in front of it. Use it on a network you trust, and turn it off when you are done. Anyone who can reach the port can reach the login page — and, through the proxy, the API.

If the address does not answer at all, check that your phone is on the same network as the machine and not on a guest SSID, and that the machine’s firewall allows the port.

Installing it to the home screen

Installing needs HTTPS. This is a browser rule, not a Novaterra one: a service worker is only available in a secure context, and http:// on a bare IP address is not one — localhost is the only exception. Over plain http on your wifi the app works and you can log in, but the browser will not install it and there is no offline mode.

To get a secure origin, publish the node behind a real hostname with a certificate. The tunnel configuration under deploy/ does this, and gives the phone an https:// address to open.

Android, in Chrome

Chrome offers to install the app itself once it has a manifest, a secure origin and a service worker with a fetch handler. Take the prompt, or use ⋮ → Add to Home screen → Install. You get a standalone window with no browser chrome, its own icon and its own entry in the app switcher.

iPhone and iPad, in Safari

There is no install prompt on iOS and there never has been. The only route is by hand:

Share → Add to Home Screen → Add. It must be Safari; Chrome on iOS cannot add a web app to the home screen.

What you get once it is there:

  • A standalone window with no Safari chrome, honouring display: standalone.
  • The app icon and name from the manifest, and a status bar tinted to the world’s colour.
  • The layout drawn to the edge of the display, with the bottom bar sitting clear of the home indicator.
  • Offline support and a service worker — from iOS 11.3, and still only on a secure origin.

What you do not get:

  • No install prompt. Nobody is ever told the app can be installed; you have to know.
  • Only Safari can do it. A link opened from another app will not offer it.
  • Storage is evicted after about seven days of not opening the app (Safari’s Intelligent Tracking Prevention). That clears the offline cache. It does not log you out — the session cookie is not what ITP evicts here — but the first launch after a long gap needs the network again.
  • No web push unless the app is on the home screen, and only from iOS 16.4.
  • Each home-screen app has its own storage, separate from Safari’s, so adding it twice gives you two of them.

What works offline, and what cannot

The service worker caches the shell: the HTML, the stylesheets and the JavaScript. It never caches anything under /api, because those responses are one person’s messages, files and ledger, and a cache entry outlives the session and is readable by whoever picks the phone up next.

So offline you get the app, its layout and its navigation, and every panel that needs the node says it cannot reach it. That is the honest behaviour: the shell is yours, the substance is your node’s.

When a new version arrives

You are told, and nothing changes under you. A new build installs in the background and waits; the app raises one toast — “A new version is ready” — with a Reload button. Reloading hands over. Until you do, you keep using the version you already have, working, including offline.