Grounded docs — LAN sharing

// Off by default

What it does #

Normally Core only answers on 127.0.0.1:7437: this computer and nothing else. Turning sharing on opens a second listener on port 7438 that other computers on your local network can reach. Every request on it must carry a credential from pairing; the normal :7437 listener doesn't change.

Home and office networks only

The shared listener speaks plain HTTP, not HTTPS. Use it on a network you trust. A paired computer can read and write the cabinet's memory, so only pair your own machines.

// Two minutes

Share a cabinet #

On this computer

Share this cabinet

In Companion, open Settings and choose Share this cabinet. It shows a six-digit code and this computer's network address.

On the other one

Enter the code

In Companion there, add a cabinet with that address, choose pairing, and enter the code before it expires (3 minutes by default).

After that

It stays paired

The other computer keeps its own credential. The code expiring doesn't disconnect it, and neither does restarting Core.

To add another computer later, choose Allow another computer: that opens a fresh code without touching the computers already paired.

// Under the hood

How pairing works #

The code is only for joining. It is valid for a short window (3 minutes unless you ask for 1–60) and is never used again after pairing.
Pairing hands out a credential. The new computer sends the code to POST /pair and gets back a long random token, which it sends on every request after that as x-grounded-client-token.
Only a fingerprint is stored. Core keeps a SHA-256 hash of each token in sharing.json in its home folder, never the token itself.
Guessing is throttled. Ten wrong codes in a row lock pairing for 30 seconds.
Sharing survives restarts. If sharing was on when Core stopped, the listener comes back when it starts, and paired computers keep working.

// Host administration

What stays local #

Some actions change how Core is set up rather than what it remembers. The shared listener refuses them with 403 LOCAL_ONLY, even for a paired computer:

/sharing — turning sharing on or off, and seeing the code.
/addons/* — installing or disabling add-ons. The read-only catalog, GET /addons, still answers.
POST /databox/:box/index — rebuilding a Databox index. Querying a box still works.

// Closing it

Stop sharing #

Stop network sharing in Companion closes port 7438 at once, and it stays closed across restarts. Paired computers are remembered: if you share again, they reconnect without a new code.

Core has no button yet to forget a single computer. To forget all of them, stop sharing, stop Core, delete sharing.json from the Grounded home folder (~/.grounded), and start Core again.

// For scripts

API #

These routes answer only on the computer running Core (127.0.0.1:7437).

Method	Path	Purpose
GET	`/sharing`	Status: whether the listener is up, whether a code is open (and the code), how many computers are paired, and this computer's LAN addresses.
POST	`/sharing`	Turn sharing on and open a pairing window. Optional `{"minutes": 1..60}`, default 3. Calling it again opens a fresh code.
DEL	`/sharing`	Turn sharing off and close the listener.

On port 7438, POST /pair with the header x-grounded-share-code returns {"token"}. A closed window answers 410, a wrong code 401, a lockout 429. GET /health on the host includes a sharing block without the code.