Skip to content
Back to search

portless

Replace port numbers with stable, named local URLs. For humans and agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/vercel-labs/portless with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/vercel-labs/portless'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vercel-labs-portless/badge.svg)](/listings/vercel-labs-portless)

HTML

<a href="/listings/vercel-labs-portless"><img src="/api/listings/vercel-labs-portless/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Global (recommended):**

npm install -g portless

**Or as a project dev dependency:**

npm install -D portless

> portless is pre-1.0. When installed per-project, different contributors may run different versions. The state directory format may change between releases, which can require re-running `portless trust`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 167 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # portless
  2. Replace port numbers with stable, named .localhost URLs for local development. For humans and agents.
  3. <p>
  4. <a href="https://vercel.com/labs#labs-products"><img alt="Vercel Labs Product" src="https://img.shields.io/badge/LABS-PRODUCT-0a0a0a.svg?style=for-the-badge&amp;logo=Vercel&amp;labelColor=000000" height="28"></a>
  5. <a href="https://www.npmjs.com/package/portless"><img alt="npm version: portless" src="https://img.shields.io/npm/v/portless.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
  6. <a href="https://github.com/vercel-labs/portless/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/github/license/vercel-labs/portless.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
  7. <a href="https://www.npmjs.com/package/portless"><img alt="npm downloads per month: portless" src="https://img.shields.io/npm/dm/portless.svg?style=for-the-badge&amp;labelColor=000000&amp;label=npm%20downloads" height="28"></a>
  8. <a href="https://skills.sh/vercel-labs/portless"><img alt="skills.sh" src="https://skills.sh/b/vercel-labs/portless?style=for-the-badge" height="28"></a>
  9. </p>
  10. ```diff
  11. - "dev": "next dev" # http://localhost:3000
  12. + "dev": "portless run next dev" # https://myapp.localhost
  13. ```
  14. portless runs a local reverse proxy and gives each dev server a name. Your app listens on a free port that portless assigns, and you open `https://<name>.localhost` instead of remembering which port it took. The URL stays the same across restarts, so bookmarks, cookies, OAuth redirects, and an agent's test script keep pointing at the right app.
  15. ## Install
  16. ```bash
  17. npm install -g portless
  18. ```
  19. To pin the version per project, install it as a dev dependency with `npm install -D portless`. portless is pre-1.0, so contributors may run different versions, and a change to the state directory format between releases can require running `portless trust` again.
  20. ## Quick start
  21. From a project with a `"dev"` script in `package.json`:
  22. ```bash
  23. portless
  24. # -> runs "dev", https://<project>.localhost
  25. ```
  26. Pass arguments to the script after `--`, so `portless -- --inspect` runs `dev` with `--inspect`. Forwarding arguments into a script with shell operators or a comment exits 2; run the command directly or make the script a single command. In Turbo mode only the root script is checked, and Turbo passes the arguments to each package script unchanged.
  27. The name comes from `package.json`, the git root, or the directory. Pass a name and a command to choose both:
  28. ```bash
  29. portless myapp next dev
  30. # -> https://myapp.localhost
  31. ```
  32. - The proxy starts on the first run. It serves HTTPS with HTTP/2 on port 443, so the first run creates a local certificate authority, adds it to the system trust store, and may ask for `sudo`. Use `--no-tls` for plain HTTP, or `--unprivileged` to skip `sudo` ([Unprivileged mode](https://portless.sh/commands#unprivileged-mode)).
  33. - `portless run <cmd>` infers the name and detects git worktrees. In a linked worktree, the last `/` segment of the branch becomes a subdomain, so `fix-ui.myapp.localhost` and `myapp.localhost` run side by side. Use `--prefix` or `PORTLESS_PREFIX` to set the label, or [configure the label style and hostname template](https://portless.sh/configuration#worktree-hostnames).
  34. - A name with dots is a subdomain: `portless api.myapp pnpm start` serves `https://api.myapp.localhost`.
  35. - `PORTLESS=0 pnpm dev` runs the command directly, without the proxy. Commands such as `portless get` and `portless list` still run normally.
  36. The full walkthrough is in [Getting started](https://portless.sh).
  37. ## How it works
  38. Each app gets a random port from 4000 to 4999 through the `PORT` environment variable, and registers a route from its hostname to that port. The proxy forwards `https://<name>.localhost` to the route. Most frameworks read `PORT`. For those that don't, such as Vite, Astro, Angular, Expo, and Wrangler, portless adds the matching port and host flags to the command ([Port assignment](https://portless.sh/configuration#port-assignment)). At a workspace root that uses Turbo, Turbo starts each package script itself, so read `PORT` and `HOST` in the framework config or set `"turbo": false`.
  39. Outside LAN mode, the proxy listens only on `127.0.0.1` and `::1`. It keeps `/etc/hosts` in sync for route hostnames, which custom TLDs such as `.test` need. If a route hostname will not resolve, the command that registered it warns and points you to `portless hosts sync`.
  40. To reach an app from another device or share it, use [LAN mode](https://portless.sh/commands#lan-mode) for phones on the same network, or [Tailscale](https://portless.sh/commands#share-on-tailscale), [ngrok](https://portless.sh/commands#share-with-ngrok), or a [Cloudflare quick tunnel](https://portless.sh/commands#share-with-cloudflare) with `--tailscale`, `--ngrok`, or `--cloudflare`.
  41. portless writes its own status lines to stderr, so stdout carries only your app's output. A non-empty `NO_COLOR` disables color, while `FORCE_COLOR=0` disables it and `FORCE_COLOR=1` forces it.
  42. ### Upstream aliases
  43. Use `--upstream` to route an alias to an HTTP or HTTPS service listening on loopback:
  44. ```bash
  45. portless alias api 8080 --upstream https
  46. portless alias api 8080 --upstream https://api.internal
  47. portless alias api 8080 --upstream http://api.internal
  48. ```
  49. The positional port always dials loopback. `https` enables TLS and preserves the incoming
  50. Host header. An `https://` authority enables TLS and overrides Host with the full
  51. authority, including its optional port. SNI uses a DNS hostname without the port;
  52. IP addresses are not sent as SNI. An
  53. `http://` authority overrides Host without TLS. This setting does not
  54. change client-facing proxy TLS. Authorities accept only a hostname or IP address with an
  55. optional port, without credentials, paths, queries, fragments, or whitespace.
  56. `portless list --json` includes each route's `upstream` object when one is set, with the
  57. same `tls` and `host` values.
  58. Upstream TLS connects only to an HTTP/1.1 backend on loopback. Portless disables
  59. certificate verification, so TLS does not authenticate backend identity, even through
  60. an SSH tunnel. Restart the proxy daemon after upgrading portless.
  61. ## Configuration
  62. An optional `portless.json` sets the name and script. In a monorepo, one file at the root covers every workspace package, and `portless` from the root starts all of them:
  63. ```json
  64. {
  65. "apps": {
  66. "apps/web": { "name": "myapp" },
  67. "apps/api": { "name": "api.myapp" }
  68. }
  69. }
  70. ```
  71. A `"portless"` key in `package.json` works too. Fields, precedence, Turborepo setup, and environment variables are in [Configuration](https://portless.sh/configuration).
  72. ## For AI agents
  73. Install the portless skill into an agent harness from [skills.sh](https://skills.sh/vercel-labs/portless):
  74. ```bash
  75. npx skills add vercel-labs/portless
  76. ```
  77. For MCP clients, `portless mcp` starts an MCP server over stdio. The default `core` profile lists routes, looks up URLs, and manages static aliases. `--tools all` adds proxy control and diagnostics:
  78. ```json
  79. { "mcpServers": { "portless": { "command": "portless", "args": ["mcp"] } } }
  80. ```
  81. The server does not start dev servers. Agents run `portless run <cmd>` in a shell. See [MCP server](https://portless.sh/commands#mcp-server).
  82. ## Commands
  83. Run `portless --help` for the command list and common app options. Use `portless proxy --help` for proxy options, or `portless <command> --help` for command details. `--help` and `-h` print help and never run the command. After `run <cmd>`, `compose <subcommand>`, or `--`, they belong to the wrapped command, so `portless run next dev --help` passes `--help` to Next.js. Usage errors, such as an unknown flag, a missing argument, or a command that needs `--yes` without a terminal, exit with code `2`; other failures exit with `1`. Wrapped commands (`run`, named apps, and `compose`) keep their own exit code. Value flags for `run`, named apps, and `service install` accept either `--flag value` or `--flag=value`. Use `portless list --json` or `portless get <name> --json` for JSON output.
  84. | Group | Commands | Docs |
  85. | -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  86. | Run apps | `portless`, `run`, `<name> <cmd>`, `get` | [Run an app](https://portless.sh/commands#run-an-app), [Get a service URL](https://portless.sh/commands#get-a-service-url) |
  87. | Static routes | `alias`, `compose up`, `compose down` | [Alias](https://portless.sh/commands#alias-static-routes), [Docker Compose](https://portless.sh/commands#docker-compose) |
  88. | Proxy | `proxy start`, `proxy stop`, `service install`, `service status`, `service uninstall` | [Proxy control](https://portless.sh/commands#proxy-control), [OS startup service](https://portless.sh/commands#os-startup-service) |
  89. | HTTPS and DNS | `trust`, `hosts sync`, `hosts clean` | [HTTPS](https://portless.sh/https), [Hosts](https://portless.sh/commands#hosts) |
  90. | Inspect and clean up | `list`, `doctor`, `prune`, `clean` | [Doctor](https://portless.sh/commands#doctor), [Prune orphans](https://portless.sh/commands#prune-orphans), [Clean up](https://portless.sh/commands#clean-up) |
  91. | Agents | `mcp` | [MCP server](https://portless.sh/commands#mcp-server) |
  92. `portless prune` removes stale routes and shares without killing unrelated port holders. A recorded process group that still has a live member keeps its route and shares even after it closes its port; prune records the member that survived and stops it on a retry with `portless prune --force`. A group prune cannot verify is kept and reported, never signaled. A port holder that cannot be proven part of the recorded group is kept and reported, never killed. Prune and clean stop recorded ngrok and cloudflared tunnels only when their executable names match, including on Windows.
  93. Run `portless doctor` first when a URL does not load. It checks the proxy, routes, DNS, and CA trust without changing anything, and prints suggested fixes. Use `portless doctor --json` to print the report as JSON.
  94. `portless clean` previews its cleanup and asks for confirmation. Use `portless clean --yes` (or `-y`) in CI or without a terminal. On macOS and Linux, a failed CA, state-file, or hosts step is retried with sudo for the same allowlisted targets. If the proxy cannot be confirmed stopped, its PID, port, runtime marker files, and CA files are kept and the CA stays trusted. Service, CA, state-file, and hosts cleanup failures produce a nonzero exit code.
  95. On macOS and Linux, `portless trust`, `portless proxy stop`, `portless prune`, `portless hosts sync`, `portless service install`, and `portless clean` act on a state directory only when no other user can change it. The directory and each of its parent directories must be owned by you or root and must not be writable by group or others. A parent with the sticky bit set, such as `/tmp`, is allowed. A symlink on the path counts only when you or root own it and it sits in a directory that passes the same check. `portless trust`, `portless proxy stop`, `portless prune`, `portless hosts sync`, and `portless service install` exit with the reason when the directory fails this check. Nothing is signaled and the hosts file is not changed. The proxy does not start from such a directory, and commands that register a route, such as `portless run` and `portless alias`, exit with the same reason. A proxy that is already running keeps the routes it has loaded and stops reloading them. portless never changes the permissions or owner of a state directory that fails it. Run `chmod go-w <dir>` on the directory it names, or point `PORTLESS_STATE_DIR` at a directory only you can write to. `portless clean` leaves such a directory alone, prints the reason, and exits nonzero. It skips a `/tmp/portless` directory that fails the check without an error. `portless proxy stop` and `portless clean` signal the recorded proxy PID only when nothing shows it is a different process from the one answering on the proxy port.
  96. ## Platforms
  97. portless runs on macOS, Linux, and Windows with Node.js 24 or later. `--tailscale` and `--funnel` need the Tailscale CLI, `--ngrok` needs the ngrok CLI, and `--cloudflare` needs `cloudflared`.
  98. ## Development
  99. This repo is a pnpm workspace with [Turborepo](https://turbo.build). The published package is `packages/portless/`, and the docs site is `apps/docs/`. Use Node.js 24 or later and pnpm 11:
  100. ```bash
  101. pnpm install
  102. pnpm build
  103. pnpm test
  104. pnpm lint
  105. pnpm type-check
  106. pnpm format
  107. ```
  108. [AGENTS.md](AGENTS.md) lists the files to update with each change and the release process.
  109. ## Documentation
  110. - [portless.sh](https://portless.sh): getting started, commands, HTTPS, and configuration
  111. - [Why portless](https://portless.sh/why): the problems named URLs solve
  112. - [Changelog](CHANGELOG.md)
  113. ## License
  114. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.