Auto mode

Auto mode keeps the Pathvela agent running in the background so your Pathvela browser tab can reach it the moment you ask — without you needing an open terminal.

Session mode vs auto mode

There are two ways the CLI runs:

  • Session mode. You start it yourself (lily, or npx pathvela) and it lives only as long as that terminal window. Close the window or press Ctrl-C and it stops immediately.
  • Auto mode. The agent is registered with your operating system so it starts on login and keeps running after the terminal closes. It's up and waiting before your browser asks for it.

Auto mode is opt-in — installing the CLI does not turn it on. You enable it yourself with lily bridge install when you want the browser to reach your local agent.

Turning it on

lily bridge install

By default the bridge can reach your home directory. To scope it to one project instead, install it with a folder:

lily bridge install --folder ~/code/my-app

The folder you grant is baked into the background service, and the agent can only read and change files inside it.

How the browser connects

When the bridge starts, it listens on a loopback address only — 127.0.0.1, never exposed to your network — and prints a short summary in the terminal, including a pairing code:

Lily is ready on this computer.

  Folder        /Users/you/code/my-app
  Pairing code  418207
  Port          8791

Open Work on Pathvela and enter the pairing code.

The pairing code is a random six-digit number, generated fresh each time. In your Pathvela tab, open Work and enter that code. From then on, requests you make in the browser are handled by the agent on your machine, scoped to the granted folder.

A few details worth knowing:

  • The bridge binds to the first free port in 8791–8793 (override with --port). It won't fall back to a random port — if all three are busy it refuses to start rather than land somewhere unexpected.
  • Only pathvela.com (and www.pathvela.com), connecting from your own machine with the correct pairing code, is allowed to reach the bridge. Nothing else on the network can.
  • Pairing is remembered so you don't retype the code every time. lily bridge reset revokes it and forces re-pairing.

Prefer to stay entirely local? lily web opens the same agent behind a local page in your browser with no code to type and nothing leaving your machine — see Commands.

Managing the bridge

lily bridge status      # is it running? is auto mode installed?
lily bridge install     # register auto mode (starts on login)
lily bridge stop        # stop the background agent now
lily bridge reset       # stop it and revoke pairing
lily bridge uninstall   # remove auto mode entirely
lily bridge log         # print the bridge log

What it registers

Auto mode uses your OS's native mechanism so the agent starts on login and survives restarts:

  • macOS: a launchd agent, com.pathvela.lily.bridge (a plist in ~/Library/LaunchAgents/).
  • Linux: a systemd user service, lily-bridge.service.
  • Windows: a startup entry (a LilyBridge Run-key launcher) plus a small watchdog task that keeps it alive.

On every platform it also registers the lily:// URL scheme, so a "open in Lily" link from Pathvela can reach the bridge.

Scope and safety

  • The agent can only touch the folder the bridge was granted — its home directory by default, or the --folder you gave it — not your whole disk.
  • Connections are local only (127.0.0.1) and gated by the pairing code; only pathvela.com is allowed as an origin.
  • Access ends the moment you lily bridge stop, lily bridge reset (which also revokes pairing), or lily bridge uninstall. In session mode, closing the terminal stops it.

Next

  • Commands — the full lily and lily bridge reference.
  • Configuration — the API key, state directory, and environment variables.