Configuration
Portless is configured through environment variables. No config files needed.
Environment variables
| Variable | Description | Default |
|---|---|---|
PORTLESS_PORT | Proxy port | 443 (HTTPS) / 80 (HTTP) |
PORTLESS_HTTPS | HTTPS on by default; set to 0 to disable (same as --no-tls) | on |
PORTLESS_TLD | Use a custom TLD instead of .localhost (e.g. test) | localhost |
PORTLESS_APP_PORT | Use a fixed port for the app (skip auto-assignment) | random 4000--4999 |
PORTLESS_SYNC_HOSTS | Set to 1 to auto-sync /etc/hosts (auto-enabled for custom TLDs) | off |
PORTLESS_STATE_DIR | Override the state directory | see below |
PORTLESS | Set to 0 to bypass the proxy | enabled |
State directory
Portless stores state (routes, PID file, port file, TLS marker) in a directory that depends on the proxy port:
| Condition | Path |
|---|---|
| Port below 1024 (sudo, macOS/Linux) | /tmp/portless |
| Port 1024+ (no sudo) | ~/.portless |
| Windows (any port) | ~/.portless |
Override with PORTLESS_STATE_DIR.
State files
| File | Purpose |
|---|---|
routes.json | Maps hostnames to ports |
routes.lock | Prevents concurrent writes |
proxy.pid | PID of the running proxy |
proxy.port | Port the proxy is listening on |
proxy.log | Proxy daemon log output |
Port assignment
Apps get a random port in the 4000--4999 range. Portless sets PORT and HOST before running your command. Most frameworks respect PORT automatically. For frameworks that ignore it (Vite, Astro, React Router, Angular, Expo, React Native), portless auto-injects --port and --host flags.