Summary
Enable the Hatchbox web app (hatchbox.ai) to communicate securely with a user’s local hb server via a lightweight broker.
The broker acts purely as a messenger — never running jobs or storing data — and allows full control of Hatchboxes even when the user is not on the same local network.
Goals
-
Keep all execution local — no job data or code ever leaves the user’s machine.
-
Prefer direct, local connections for speed and simplicity.
-
Fall back to broker-based relaying when the user is remote.
-
Keep the UI identical across both connection types.
Connection Modes
1. Local Direct Mode
When the browser and the Hatchbox server are on the same Wi-Fi or LAN, the web app connects directly.
This gives instant communication with no dependency on the broker.
It’s the default and preferred mode.
2. Broker Relay Mode
If the local server isn’t reachable, the browser stays connected through the broker.
The broker simply forwards encrypted messages between the browser and the user’s machine.
It never executes, inspects, or stores any job data.
Relay mode is optional and requires the user to explicitly allow it.
How It Works
-
-
When hb server starts, it logs into the broker and announces “I’m online for this account.”
-
The browser checks the broker to see if any linked devices are available.
-
-
The user runs hb server login and gets a short code.
-
They enter this code on hatchbox.ai to pair their device with their account.
-
From then on, that device can be discovered and connected to securely.
-
-
The browser first attempts a direct local connection.
-
If that fails, it offers “Connect via Secure Relay.”
-
When accepted, the broker starts relaying encrypted commands and logs between the two.
-
-
All sessions use short-lived keys and strong encryption.
-
When a new browser connects, the local Hatchbox prompts for approval.
-
Only safe actions are allowed over the relay (start, stop, stream logs, read metadata).
-
No raw filesystem access or arbitrary command execution unless explicitly approved.
-
-
The broker only keeps minimal metadata: user ID, device ID, connection state, and short-lived tokens.
-
It cannot read any of the payload content.
-
All computation remains 100% local.
Deliverables
-
Minimal broker service (WebSocket or HTTPS)
-
Device link and presence system for hb server
-
Browser logic for presence detection and relay fallback
-
Secure approval + session key exchange
-
Config option: “Allow remote relay connections”
-
Updated docs explaining local vs. relay mode
Outcome
Users will be able to:
-
Run Hatchboxes locally as they do today.
-
Log into hatchbox.ai from any device and control their local server remotely through the broker.
-
Remain fully local by default, with all sensitive activity happening on their own machine.
Summary
Enable the Hatchbox web app (hatchbox.ai) to communicate securely with a user’s local hb server via a lightweight broker.
The broker acts purely as a messenger — never running jobs or storing data — and allows full control of Hatchboxes even when the user is not on the same local network.
Goals
Keep all execution local — no job data or code ever leaves the user’s machine.
Prefer direct, local connections for speed and simplicity.
Fall back to broker-based relaying when the user is remote.
Keep the UI identical across both connection types.
Connection Modes
1. Local Direct Mode
When the browser and the Hatchbox server are on the same Wi-Fi or LAN, the web app connects directly.
This gives instant communication with no dependency on the broker.
It’s the default and preferred mode.
2. Broker Relay Mode
If the local server isn’t reachable, the browser stays connected through the broker.
The broker simply forwards encrypted messages between the browser and the user’s machine.
It never executes, inspects, or stores any job data.
Relay mode is optional and requires the user to explicitly allow it.
How It Works
When hb server starts, it logs into the broker and announces “I’m online for this account.”
The browser checks the broker to see if any linked devices are available.
The user runs hb server login and gets a short code.
They enter this code on hatchbox.ai to pair their device with their account.
From then on, that device can be discovered and connected to securely.
The browser first attempts a direct local connection.
If that fails, it offers “Connect via Secure Relay.”
When accepted, the broker starts relaying encrypted commands and logs between the two.
All sessions use short-lived keys and strong encryption.
When a new browser connects, the local Hatchbox prompts for approval.
Only safe actions are allowed over the relay (start, stop, stream logs, read metadata).
No raw filesystem access or arbitrary command execution unless explicitly approved.
The broker only keeps minimal metadata: user ID, device ID, connection state, and short-lived tokens.
It cannot read any of the payload content.
All computation remains 100% local.
Deliverables
Minimal broker service (WebSocket or HTTPS)
Device link and presence system for hb server
Browser logic for presence detection and relay fallback
Secure approval + session key exchange
Config option: “Allow remote relay connections”
Updated docs explaining local vs. relay mode
Outcome
Users will be able to:
Run Hatchboxes locally as they do today.
Log into hatchbox.ai from any device and control their local server remotely through the broker.
Remain fully local by default, with all sensitive activity happening on their own machine.