Docs menuGetting started

Start a tunnel

Install LPM CLI. Then sign in to LPM.dev Registry:

lpm login

To start a tunnel or to manage domains, LPM CLI needs the session that lpm login creates. A standalone registry token, such as a token in .npmrc, does not work. Your account also needs a Pro plan, or you must be a member of an organization on the Organization plan.

Start with the development server

Use one command to start the project and expose its development server:

lpm dev --tunnel

LPM CLI waits until the local service is ready. Then it connects the service to the tunnel relay and prints the public URL and the local inspector URL.

Expose an existing server

If your server already listens on a known port, pass the port:

lpm tunnel 3000
lpm tunnel 4000

On the Pro plan, the tunnel uses your account URL, <username>-<code>.lpm.fyi. The code is eight random characters, so nobody can guess the URL:

Tunnel ready
  public URL  https://acme-ab3k9mzq.lpm.fyi
  inspector   http://127.0.0.1:54218
  local       http://127.0.0.1:3000

To stop the tunnel, press q or Ctrl-C.

You can also run the command without a port:

lpm tunnel

Without a port, lpm tunnel uses the only active lpm dev endpoint. If no endpoint is active, or more than one is active, the command stops with an error. Then run it again with the port of the server that you want to expose.

Name the session

To find the requests of a test later, give its session a name:

lpm tunnel 3000 --session "stripe-test"

The name appears in the session list of the inspector and stays attached to the captured requests of that session. lpm dev --tunnel does not accept --session.

Keep webhook endpoints responsive

By default, the tunnel answers 502 if it cannot reach the local server. During webhook development, repeated failures can make a provider retry or turn off an endpoint.

To answer 200 OK when the local server is unavailable, add --auto-ack:

lpm tunnel 3000 --auto-ack

LPM CLI answers 200 OK only after it stores the request in the inspector database. If it cannot store the request within 10 seconds, it answers 503.

The inspector marks these requests as auto-acknowledged, so you can tell them apart from requests that your application handled. When the server is available again, replay them from the browser inspector.

Protect the public URL

On the Pro and Organization plans, a tunnel can require a token for each session:

lpm tunnel 3000 --tunnel-auth

LPM CLI generates the token and prints it in the auth row as an X-Tunnel-Auth header. If the output is not a terminal, LPM CLI hides the token. With --json, the token is in the tunnel_auth field.

API clients send the token in this header:

X-Tunnel-Auth: <token>

The relay also accepts the token in the __tunnel_auth=<token> query parameter. It then redirects to the same URL without the parameter and stores the token in an HTTP-only cookie for one day. A browser visitor without a token sees a form that asks for the token. After a correct entry, the relay stores the same cookie.

The relay removes the token from each request before it forwards the request to your server. It does not use the Authorization header for the token, and it forwards that header unchanged. If a request has the query parameter, the relay answers with a redirect and does not forward that request to your server. For this reason, a webhook provider must send the X-Tunnel-Auth header to call a protected tunnel. Use tunnel authentication for previews and for clients that can send this header.

LPM CLI generates a new token each time the tunnel starts.

Open the inspector

LPM CLI starts the local inspector server on a free port and prints its URL. While lpm tunnel runs, press o to open the inspector in your browser.

To set the inspector port, or to turn off the inspector server, use these flags:

lpm tunnel 3000 --inspect-port 4500
lpm tunnel 3000 --no-inspect

Without --inspect-port, the operating system selects a free port, so the inspector does not conflict with development servers. If another process uses the port that you pass, the command fails.

lpm dev --tunnel also accepts --no-inspect and --inspect-port. It prints the inspector URL in its startup output.

Common flags

FlagEffect
<port>Expose this local port. Without it, LPM CLI uses the only active lpm dev endpoint.
<domain>Use a claimed domain for this session
--tunnel-authRequire the generated tunnel token (Pro or Organization)
--auto-ackStore the request and answer 200 OK when the local server is down
--session <NAME>Name this tunnel session in the inspector
--no-inspectDo not start the local inspector web server
--inspect-port <N>Bind the inspector to this exact local port

lpm dev --tunnel accepts --tunnel-auth and takes a claimed domain with --domain. It does not accept --auto-ack or --session.

The LPM CLI tunnel reference lists every command form, configuration field, and global flag.

Continue