portless CLI
A Vercel Labs CLI: instead of localhost:3000 the dev server opens at a stable address like https://myapp.localhost, with its own for each git branch
- 12,760 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- Adds its own root certificate to the system trust store and takes port 443 with a sudo request
- Edits /etc/hosts and can install a root-owned service that starts at boot
- The --funnel and --ngrok flags expose the dev server to the internet, and --lan opens it to the whole local network
Install
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/portlessDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Adds its own root certificate to the system trust store and takes port 443 with a sudo request
- Edits /etc/hosts and can install a root-owned service that starts at boot
- The --funnel and --ngrok flags expose the dev server to the internet, and --lan opens it to the whole local network
This is third-party code. Review the repository files before installing.
What it does
portless replaces port numbers in local development with names. The command portless myapp next dev starts your dev server and opens it at https://myapp.localhost. A reverse proxy does the work: on first start it creates a local certificate, adds it to the system trust store and takes port 443 (on macOS and Linux it asks for sudo for this). portless gives the app a random port from the 4000–4999 range through the PORT variable, and for Vite, Astro, Angular, Expo and other frameworks that ignore it, it injects the --port flag itself. The bare portless command runs the dev script from package.json and takes the name from the package, the git root or the folder. In a monorepo one portless.json at the root covers all packages, and names like api.myapp give subdomains. In a linked git worktree the branch name is prepended to the address, so fix-ui gets fix-ui.myapp.localhost without touching the config. The --tailscale, --funnel and --ngrok flags open the app to a team or to the internet, and --lan makes it reachable on network devices as myapp.local. For agents portless removes port confusion: the app's address is always the same. The repository has two skills: portless with a setup guide and oauth for cases where a sign-in provider rejects a .localhost address.
Who it is for. For web developers with several dev servers and monorepos, and for those whose agents often miss the port when testing an app.
Good fit when
- Several projects ask for port 3000 at once and the server dies with EADDRINUSE
- An agent tests the app and uses the wrong port: a stable address removes the guessing
- You work with git worktrees and need a separate address per branch without editing configs
- Cookies and localStorage of different projects mix on localhost and need to be separated by name
- You need to show the dev server to a colleague over Tailscale or to a phone over Wi-Fi with --lan
Not a fit when
- The computer has Node.js older than version 24: portless needs Node.js 24 or newer
- You cannot add a root certificate to the system and take port 443: by default portless does just that
- The agent needs help with Next.js code itself: the catalog has Next.js DevTools MCP for dev-mode debugging, while portless only gives the server a name
- The app runs in a container or on a remote machine with no access to your browser: the proxy works on the local addresses 127.0.0.1 and ::1
Example request
Set up portless in this monorepo so web and api open as myapp.localhost and api.myapp.localhost, and check the result with portless listLimitations
The project is pre-1.0: the author warns that the state directory format may change between releases, and then portless trust has to be run again. With a per-project install different team members may run different versions.
Node.js 24 or newer and macOS, Linux or Windows are required. --tailscale and --funnel need the Tailscale client with HTTPS certificates enabled, --ngrok needs the ngrok client with a token. On Linux the --lan mode relies on avahi-publish-address from the avahi-utils package, on macOS on dns-sd.
In Safari .localhost subdomains do not open on some configurations: by default portless syncs a block in /etc/hosts, which the PORTLESS_SYNC_HOSTS=0 variable turns off. Without a terminal or with CI=1 portless asks no questions and exits with an error.
Frameworks that check origins, such as Next.js in LAN mode, need the .local names added to allowedDevOrigins. Google and Apple reject .localhost addresses, so OAuth needs the --tld flag with a domain from the Public Suffix List.
Apache-2.0 license.
How to disable. portless clean removes the state in ~/.portless, the root certificate from the system store and the block in /etc/hosts, and portless service uninstall removes the proxy autostart. Then remove the package with npm uninstall -g portless. To bypass the proxy once, run the command with PORTLESS=0.
FAQ
Why does portless ask for sudo?
By default the proxy takes port 443, and on macOS and Linux privileged ports need elevated rights. For unprivileged addresses there is port 1355 and the -p flag. sudo is also needed to add the local certificate to the system store.
What if Safari does not open the .localhost address?
Run portless hosts sync: the command reconciles routes with /etc/hosts. The entries are removed later with portless hosts clean. Chrome, Firefox and Edge resolve .localhost subdomains to 127.0.0.1 themselves.
How does portless work with several worktrees?
In a linked worktree portless run prepends the branch name as a subdomain: the main copy stays myapp.localhost, and the fix-ui branch gets fix-ui.myapp.localhost. The --name flag changes the base name while the branch prefix stays.
How do I open the app from a phone?
Start the proxy with portless proxy start --lan: it listens on 0.0.0.0, announces names over mDNS, and the app is reachable as <name>.local on devices of the same network. The network address is detected automatically and follows Wi-Fi changes.
How do I expose the server outside?
--tailscale publishes the app on your Tailscale network, --funnel opens it to the whole internet through Tailscale Funnel, and --ngrok builds an ngrok tunnel. The tunnel is removed when the app exits.
What does portless doctor check?
The command changes nothing and looks at Node.js, the state directory, proxy liveness, route entries, certificate trust, name resolution and the LAN mode prerequisites, then prints fix suggestions.
Discussion
No questions or reviews yet.
Related
CLI toolsA tunnel for localhost with self-hostable relays: a public HTTPS address for a local service, no account, plus skills for agents
The remote MCP server of Devopness, a platform that builds infrastructure and deploys apps in your own cloud accounts
A local gate in front of git push: the branch goes through review, tests, docs and lint in a separate worktree before it reaches the remote with a PR
3X-UI on your VPS
3x-ui-vps
Skill that deploys the 3X-UI panel and Xray VLESS behind nginx on an Ubuntu server and maintains it through bundled scripts
Container by Aerovato
Container
A CLI for persistent per-project Linux workspaces in Docker or Podman that keep the agent away from the rest of your system
A CLI that publishes a built frontend to IPFS in one command and deploys small full-stack projects; ships agent skills
README in short
The repository holds the TypeScript packages/portless package with tests, site documentation, examples, a changelog and two skills. The project page covers installation, running an app, configuration in portless.json and package.json, monorepos, Turborepo, subdomains, git worktrees, custom top-level domains, HTTP/2, the startup service, LAN mode, sharing through Tailscale and ngrok, a reference of commands and variables, removal and troubleshooting.