InsideHow RoachNet fits together
On this page
The app and its helper
- RoachNet.app is the window: Home, RoachClaw, Dev, the Vault, Maps, the Org and Runtime. It lives in
~/RoachNet/app. roachnet-runtimeis the helper inside it, atRoachNet.app/Contents/Helpers/roachnet-runtime. The app starts it, and it runs the four local servers below, so the app, your scripts, your phone and other model clients all talk to the same helper.- RoachNet Setup installs and upgrades both. It stages a new version beside the old one, starts it once as a test, and only then swaps it in.
Each time the app starts the runtime, it picks a fresh port, which it writes to a file only your account can read, and a fresh launch token, which since 1.1.3 it hands to the runtime on its standard input and keeps out of every file. Find the port and token shows how a script finds the port and uses a RoachClaw API token.
Four servers on 127.0.0.1
The runtime talks to everything through four local servers. None of them listens on your network.
| Server | Who talks to it | Address |
|---|---|---|
| Loopback API | RoachNet.app and your own scripts | A fresh port each launch |
| Model server | Tools that speak the Ollama, OpenAI or Anthropic APIs | 127.0.0.1:36434 |
| Companion bridge | Your paired iPhone, through a path you set up | 127.0.0.1:38111, while the bridge is on |
| Setup service | RoachNet Setup | An ephemeral port, only while Setup is open |
All four refuse a Host header that isn't a loopback name and a request from another website, so a web page can't reach them through your browser. Cluster is the one part that listens on the network, and only while you have it on.
How a model runs
Models run on RoachInference, RoachNet's own engine for GGUF files on the Mac's GPU. Before a model loads, RoachNet works out how much memory it needs from the file alone, and if it won't fit, it says so with the sizes instead of letting the Mac swap. RoachClaw has the details.
RoachClaw, the Org's agents and the model server all use the same local models. Two other paths are there if you want them:
- Your own Ollama, with
ROACHNET_INFERENCE_ENGINE=ollama. See Keep using your own Ollama. - Your Claude or ChatGPT plan, through your own signed-in CLI. See Plans as models.
Where things are kept
| Folder | What's in it | Back it up? |
|---|---|---|
~/RoachNet/app, runtime, bin |
The app, its helper and support files. Upgrades replace them. | No |
~/RoachNet/storage |
Your Vault, models, maps, Org, settings and traces. Upgrades keep it. | Yes |
~/Library/Application Support/roachnet |
The installer's settings, including the companion token's SHA-256 (the token itself before 1.1.3) | No |
Back up ~/RoachNet/storage and you've backed up everything that's yours. Folders and files lists what's inside it.
Your phone and your other Macs
- Your iPhone reaches the companion bridge through your tailnet or an HTTPS relay you run. RoachTail pairs it, with no RoachNet server involved, and gives it a token that opens only the companion's routes.
- Your other Macs can share one model with Cluster. Each Mac holds a run of the model's layers, and every message between them is encrypted. In 1.1.0, Cluster was tested with two runtimes on one Mac, not across two physical Macs.
What goes online
The runtime goes online to fetch what you ask for, to check GitHub for updates, to refresh the catalog lists, and for features you turn on. Network and privacy lists each case.
Related
- The local API
- Security
- Command line covers
roachnet-runtimeitself.