Gooseberry is designed for trusted local networks, not public internet exposure.

• The bridge runs on your Mac.
• The robot connects to the bridge over your LAN using ws://.
• Agent hooks post local events to the bridge using HTTP.
• Optional camera tracking sends low-rate robot camera frames to the bridge over the existing robot WebSocket.
• Face detection runs locally on the Mac using Apple Vision.

No cloud service is required for the Gooseberry bridge path.

Use a strong bearer token:

openssl rand -hex 24

The wrapper generates one automatically in .env. Treat it like a password. Anyone on the LAN with the token can send notifications and tracking commands to the robot.

The browser live-view URL may include the token as a query parameter for convenience. Do not share that URL or screenshots containing it.

The current firmware build also embeds the bridge URL and token. Do not publish firmware images built with your private .env as generic public downloads.

For development, keep the bridge bound to localhost when the robot is not in use. For robot use, bind to the LAN:

GOOSEBERRY_ADDR=:8765 ./scripts/gooseberry bridge

Do not port-forward the bridge through your router. Do not expose it with a tunnel unless you add a stronger deployment-specific security layer.

Avoid public Wi-Fi and guest networks. If you must use an untrusted network, disable tracking, keep the firewall restrictive, and assume plain ws:// can be observed by other clients on that network.

Tracking is opt-in:

GOOSEBERRY_TRACKING=1 ./scripts/gooseberry bridge

When bridge head tracking is enabled and AGENT.MONITOR is in normal mode, the robot streams low-rate JPEG frames to the bridge. If head tracking is disabled in the bridge, or the robot app is in no head tracking/quiet mode, the firmware does not capture or send camera frames. Frames are processed locally on the Mac. The robot does not run face detection itself; it only follows movement commands from the bridge.

Codex, Claude Code, and Pi hooks should call the local gooseberry-agent command. Keep hook commands narrow: they should only translate native harness events into Gooseberry notifications.

Do not let arbitrary remote services call /notify.

• Robot transport is plain WebSocket, not TLS.
• Token authentication protects bridge endpoints, but LAN clients can still attempt connections.
• The bridge is a local tool, not a hardened multi-user service.
• Live-view query-token URLs are convenient but leakable.