Environment Variables

Configure Portless behavior using environment variables

Portless supports several environment variables to customize its behavior. These can be set in your shell configuration files (.bashrc, .zshrc, etc.) or exported in your terminal session.

Proxy Configuration

PORTLESS_PORT · number · default: "1355"

Override the default proxy port. The proxy will listen on this port instead of the default 1355.

Ports below 1024 require sudo to bind. Portless automatically selects the appropriate state directory based on the port number:

• Ports < 1024: Uses /tmp/portless (system-wide, shared between root and non-root processes)
• Ports >= 1024: Uses ~/.portless (user-specific)

# Use port 3000 as the proxy port
export PORTLESS_PORT=3000
portless proxy start

PORTLESS_HTTPS · string · default: ""

Enable HTTPS/HTTP2 mode by default. Set to 1 or true to always start the proxy with TLS enabled.

When enabled, Portless generates a local Certificate Authority (CA) and uses it to issue certificates for your .localhost domains. The CA is automatically added to your system trust store on first use.

# Always use HTTPS
export PORTLESS_HTTPS=1
portless proxy start  # Starts with HTTPS/HTTP2

You can override this with the --no-tls flag when starting the proxy.

PORTLESS_STATE_DIR · string · default: "auto"

Override the state directory location. By default, Portless automatically selects the state directory based on the proxy port:

• Ports < 1024: /tmp/portless
• Ports >= 1024: ~/.portless

Setting this variable forces Portless to use a specific directory regardless of the port number.

# Use a custom state directory
export PORTLESS_STATE_DIR=/var/lib/portless

See State Directory for more details on state directory structure and behavior.

Application Configuration

PORTLESS_APP_PORT · number · default: "auto"

Use a fixed port for your application instead of automatically assigning one from the 4000-4999 range.

Equivalent to the --app-port CLI flag. Useful when your application has specific port requirements or when you need to configure another service to connect to a known port.

# Always run the app on port 5000
export PORTLESS_APP_PORT=5000
portless myapp npm start

PORTLESS_SYNC_HOSTS · string · default: ""

Automatically sync /etc/hosts whenever routes change. Set to 1 to enable.

This is useful for Safari, which relies on the system DNS resolver and may not resolve .localhost subdomains automatically. When enabled, Portless adds entries to /etc/hosts for each registered route.

Important: The proxy must be started with sudo for this to work, as modifying /etc/hosts requires root permissions.

# Enable automatic hosts file syncing
export PORTLESS_SYNC_HOSTS=1
sudo portless proxy start

See Safari DNS Issues for more details.

PORTLESS · string · default: ""

Skip Portless entirely and run commands directly. Set to 0 or skip to bypass the proxy.

This is useful when you temporarily need to run your application without Portless, or when debugging connection issues.

# Run without Portless
PORTLESS=0 pnpm dev
# or
PORTLESS=skip pnpm dev

Child Process Environment

When Portless runs your application, it sets the following environment variables in the child process:

PORT · string

The port your application should listen on. This is either an automatically assigned port from the 4000-4999 range, or the value of PORTLESS_APP_PORT if set.

Most web frameworks respect this variable. For frameworks that don’t (Vite, Astro, React Router, Angular, Expo, React Native), Portless automatically injects --port and --host flags.

HOST · string · default: "127.0.0.1"

The host your application should bind to. Always set to 127.0.0.1 to ensure the proxy can connect to your app.

This prevents frameworks from binding to IPv6 ::1 instead of IPv4, which would make them unreachable by the proxy.

PORTLESS_URL · string

The public URL of your application (e.g., http://myapp.localhost:1355 or https://myapp.localhost:1355).

Use this when your application needs to construct URLs pointing to itself, such as for OAuth callbacks or webhooks.

// Example: Using PORTLESS_URL in your app
const callbackUrl = `${process.env.PORTLESS_URL}/api/auth/callback`;

__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS · string · default: ".localhost"

Internal variable set for Vite to allow .localhost subdomains. This prevents Vite from blocking requests from the proxy.

Examples

Development Environment Setup

~/.zshrc or ~/.bashrc

# Use HTTPS by default for HTTP/2 multiplexing
export PORTLESS_HTTPS=1

# Use port 80 (requires sudo, but no port in URLs)
export PORTLESS_PORT=80

Team-Shared Configuration

.envrc (with direnv)

# Use a custom state directory for this project
export PORTLESS_STATE_DIR=.portless

# Always use port 3000 for the app
export PORTLESS_APP_PORT=3000

Debugging Without Portless

# Temporarily disable Portless
PORTLESS=0 npm run dev