Skip to main content

​
Overview

Portless can be configured using environment variables. These are useful for setting defaults in your shell config (.bashrc, .zshrc) or for per-project configuration.

​
Configuration Variables

These variables configure Portless behavior:

​
PORTLESS_PORT

Override the default proxy port (1355). 
export PORTLESS_PORT=8080
portless proxy start  # Starts on port 8080
Valid values: 1-65535
Default: 1355
Overridden by: --port / -p flag

​
PORTLESS_APP_PORT

Use a fixed port for apps instead of automatic assignment (4000-4999 range). 
export PORTLESS_APP_PORT=3000
portless run next dev  # App uses port 3000
Valid values: 1-65535
Default: Auto-assigned in 4000-4999 range
Overridden by: --app-port flag

​
PORTLESS_HTTPS

Always enable HTTPS when starting the proxy. 
export PORTLESS_HTTPS=1
portless proxy start  # Starts with HTTPS automatically
Valid values: 1, true
Default: Not set (HTTP)
Overridden by: --no-tls flag

​
PORTLESS_SYNC_HOSTS

Automatically sync /etc/hosts whenever routes change. Requires proxy to be started with sudo. 
export PORTLESS_SYNC_HOSTS=1
sudo portless proxy start  # Auto-syncs /etc/hosts on route changes
Valid values: 1
Default: Not set (manual sync only)
Requires: Proxy started with sudo

​
PORTLESS_STATE_DIR

Override the state directory location. 
export PORTLESS_STATE_DIR=/custom/path
portless proxy start  # Uses /custom/path for state
Default:
  • Port < 1024 (privileged): /tmp/portless
  • Port >= 1024 (unprivileged): ~/.portless

​
PORTLESS

Skip the proxy and run commands directly. 
export PORTLESS=0
portless run next dev  # Runs "next dev" directly, no proxy

# Also accepts:
export PORTLESS=skip
Valid values: 0, skip
Default: Not set (uses proxy)

​
Injected Variables

These variables are injected into your app’s process by Portless:

​
PORT

The port your app should listen on. 
# Automatically set when running your app
portless run next dev
# PORT=4123 (example random port)
Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically.

​
HOST

The host your app should bind to. Always set to 127.0.0.1. 
portless run next dev
# HOST=127.0.0.1
Prevents frameworks from binding to IPv6 ::1.

​
PORTLESS_URL

The public URL of your app. 
portless myapp next dev
# PORTLESS_URL=http://myapp.localhost:1355
Use this to:
  • Generate absolute URLs in your app
  • Configure OAuth redirect URIs
  • Reference your app from other services
// In your app code
const publicUrl = process.env.PORTLESS_URL || 'http://localhost:3000';
console.log(`App running at ${publicUrl}`);

​
__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS

Set to .localhost for Vite compatibility. 
portless run vite dev
# __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS=.localhost
Prevents Vite from rejecting requests with .localhost host headers.

​
Examples

​
Permanent HTTPS Setup

Add to .bashrc or .zshrc: 
export PORTLESS_HTTPS=1
Now every time you start the proxy, it uses HTTPS: 
portless proxy start  # Uses HTTPS automatically

​
Custom Port for Development

export PORTLESS_PORT=8080
portless run next dev
# -> http://myapp.localhost:8080

​
Auto-Sync Hosts for Safari

Add to shell config: 
export PORTLESS_SYNC_HOSTS=1
Start proxy with sudo: 
sudo portless proxy start
Now /etc/hosts updates automatically when routes change.

​
Fixed App Port

export PORTLESS_APP_PORT=3000
portless run next dev  # Always uses port 3000

​
Custom State Directory

export PORTLESS_STATE_DIR=~/my-project/.portless
portless proxy start
# State stored in ~/my-project/.portless/

​
Skip Proxy Temporarily

# One-off skip
PORTLESS=0 pnpm dev

# Skip for session
export PORTLESS=skip
pnpm dev  # Runs without proxy
unset PORTLESS  # Re-enable

​
Use in Scripts

package.json: 
{
  "scripts": {
    "dev": "portless run next dev",
    "dev:direct": "PORTLESS=0 next dev"
  }
}
Makefile: 
dev:
	export PORTLESS_HTTPS=1 && portless run next dev

dev-without-proxy:
	export PORTLESS=skip && portless run next dev

​
Environment Priority

When multiple configuration sources exist, priority is:
  1. CLI flags (highest priority)
  2. Environment variables
  3. Defaults (lowest priority)
Examples: 
# Port from environment
export PORTLESS_PORT=8080
portless proxy start
# Uses port 8080

# Flag overrides environment
export PORTLESS_PORT=8080
portless proxy start -p 9000
# Uses port 9000

# HTTPS from environment
export PORTLESS_HTTPS=1
portless proxy start
# Uses HTTPS

# --no-tls overrides HTTPS environment
export PORTLESS_HTTPS=1
portless proxy start --no-tls
# Uses HTTP (HTTPS disabled)

​
Validation

​
Invalid Port

export PORTLESS_PORT=abc
portless proxy start
# Ignores invalid value, uses default (1355)

export PORTLESS_PORT=99999
portless proxy start
# Ignores out-of-range value, uses default (1355)

​
Invalid App Port

export PORTLESS_APP_PORT=abc
portless run next dev
# Error: Invalid PORTLESS_APP_PORT="abc". Must be 1-65535.

​
Debugging

To see which port Portless is using: 
portless list
# Shows active routes with ports

# Check state files
cat ~/.portless/proxy.port
# or
cat /tmp/portless/proxy.port

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us