The laptop agent

The berth agent (berth agent) runs on your laptop in the background. It holds a connection to every paired box, runs saved forwards and the *.localhost proxy, and serves a local API that the CLI and the desktop app are clients of. Closing the app, or the app crashing, never stops a session, a forward or a queued prompt.

What it doesCopy Anchor Link

• keeps one pinned TLS connection per box, reconnecting forever, with health pings to notice a connection that died silently and sleep detection;
• serves private URLs on port 1377, http://3000.devl.localhost:1377/, and runs forwards (a fixed local port to a box port) and routes;
• relays every online box's events, so laptop hooks, plugins and the app hear about every agent on every box;
• runs laptop hooks from ~/.berth/hooks.json;
• holds the offline prompt queue and delivers it when boxes come back;
• runs an embedded Tailscale node for each other tailnet;
• keeps your kits library and serves your themes, task templates and plugins to the app.

Running itCopy Anchor Link

Any command that needs the agent starts it. To have it start at login and restart after a crash:

berth agent install      # launchd on macOS, a systemd user unit on Linux
berth agent status
berth agent uninstall
berth agent              # run it in the foreground instead
berth stop               # stop it, and every forward

berth status             # boxes, forwards and the proxy at a glance
berth events             # every event from this laptop and every box, live
berth doctor             # what's wrong on this computer, and how to fix it

How things reach itCopy Anchor Link

Where it keeps thingsCopy Anchor Link

State is in ~/Library/Application Support/berth/client/ on a Mac and ~/.config/berth/client/ on Linux ($BERTH_HOME moves it): its identity, paired boxes, forwards, routes, the queue, logs and the app's token. Things you write by hand are in ~/.berth/ ($BERTH_USER_DIR moves it): hooks, task templates, themes, plugins, kits. The full list is in files and environment.

Next: the security model, how the agent and your boxes trust each other.