LocalSlip docs

Introduction

LocalSlip is a named local port registry. A name owns a TCP number on this machine. You still type the port. The slip metaphor is a mnemonic. The stored mapping is a lease in ~/.localslip/.

localhost is the machine. LocalSlip is the slip.

You start a Svelte app. Vite takes 5173. You start a second one. It takes 5174. After a reboot you start them in the other order. The ports swap. Bookmarks, firewall rules, and the phone now hit the wrong app.

Name the port so that does not happen. foo stays on 5173. bar stays on 5174. An agent or the app asks the CLI instead of hoping Vite picked the same number again.

What it is

  • Named leases persist on the machine that ran the CLI (~/.localslip/)
  • localslip get foo prints only the port, for scripts
  • A dashboard on 54321 shows leases and what is listening
  • --lan on a claim stores bind 0.0.0.0 and syncs an inbound firewall allow on Windows, macOS, and Linux

It is not DNS. It does not give you foo.localhost URLs. It is not a reverse proxy. A claim does not reserve the port at the OS. Another process can still bind it.

Claims, listeners, and collisions

Thing What it means
Claim / lease A stored name → port and bind in ~/.localslip/
Listener A process actually accepting connections
Occupied port Something is listening, or another lease already owns the number

Without --or-next, a second name cannot take a port another lease owns. You can claim a port that is already listening when the process belongs to the project you are in. A listener from another project is refused unless you pass --force. That does not evict the listener.

The documented Vite config reads the claimed port with localslip get and sets strictPort: true. The app fails if that port is busy. It does not silently take the next free port.

Network scope

Default claim bind is 127.0.0.1. --lan changes the stored bind to 0.0.0.0 and asks for an inbound firewall allow. It does not launch the app. localslip serve listens on all interfaces. http://127.0.0.1:54321 is the lease table. Any other host shows the visitor tiles. The consuming app reads the port from localslip get foo and must set its own host to match.

Allocating a port does not protect a service that you start on all interfaces yourself.

Two surfaces

Surface What it is
localslip.dev This site: what it is and how to use it
npm localslip The CLI and dashboard, on your machine

The domain never serves leases.

LocalHelm hosts start and stop on the Ports tab. Claim, release, and firewall stay on this CLI.

Next