@lobsterline/agent

Runs on your host machine. Opens a persistent outbound WebSocket to the LobsterLine relay; spawns and manages a local @lobsterline/mcp child process; tunnels MCP HTTP traffic between the two.

The agent is what makes any user-controlled machine — Mac, Linux box, VPS, container — a LobsterLine backend. No inbound network access required on the host.

Run

You first register a backend in the dashboard and copy the printed agent token (lla_...). Then on the host:

LOBSTERLINE_AGENT_TOKEN=lla_... \
LOBSTERLINE_RELAY_URL=wss://relay.lobsterline.app/agent \
npx @lobsterline/agent

Or via launchd / systemd / Windows service for permanence — the agent reconnects with exponential backoff on disconnect, and auto-restarts the MCP child if it crashes.

Local development

Point at the dev relay running on localhost:

LOBSTERLINE_AGENT_TOKEN=lla_dev_agent_smoke \
LOBSTERLINE_RELAY_URL=ws://127.0.0.1:18792/agent \
npm run dev --workspace=@lobsterline/agent

(With matching DEV_AGENT_TOKEN=lla_dev_agent_smoke on the relay so the dev token is accepted.)

Env

| Var | Required? | Default | Purpose | |---|---|---|---| | LOBSTERLINE_AGENT_TOKEN | yes | — | Per-machine token from the dashboard. Lives in env / launchd plist. | | LOBSTERLINE_RELAY_URL | no | wss://relay.lobsterline.app/agent | Override for self-hosted relay or local dev | | LOBSTERLINE_MCP_PORT | no | 18791 | Loopback port the MCP child binds to | | PING_INTERVAL_MS | no | 30000 | WS ping cadence |

What the agent is NOT

• Not a daemon manager — use launchd / systemd / pm2 for keep-alive across reboots.
• Not aware of MCP semantics — it tunnels HTTP-over-WS frames. Tier classification, destructive-command holds, scrollback — all of that is in @lobsterline/mcp.
• Not multi-process — one agent per host. (One MCP child. One relay connection.) If you want to attach multiple hosts, run one agent on each.

Trust posture

• Agent connects out only — host never opens an inbound port.
• Agent token is long-lived but revocable from the dashboard. Revoke = the relay refuses the next reconnect; in-flight requests fail.
• The MCP child binds 127.0.0.1 only and accepts no auth from local connections — the agent is the only thing talking to it.
• Compromise of the host: attacker has shell already, no point routing through MCP. Compromise of the agent token: attacker can run safe/moderate commands; destructive commands still hold for explicit confirmation surfaced to whoever has a connected client.