unport

Local development port manager. Access your apps via clean domains like http://api.localhost instead of localhost:3847.

Table of Contents

• Installation
• Quick Start
• How It Works
• Commands
• HTTPS Support
• Config
• License

Installation

cargo install unport-cli

Or with Homebrew:

brew tap ozankasikci/tap && brew install unport

Quick Start

# 1. Start the daemon (needs sudo for port 80)
sudo unport daemon start -d

# 2. In your project directory, create unport.json
echo '{"domain": "myapp"}' > unport.json

# 3. Start your app
unport start

# Your app is now at http://myapp.localhost

How It Works

unport runs a reverse proxy on port 80 that routes requests based on the Host header.

Browser: http://api.localhost/users
    ↓
unport daemon (port 80)
    ↓ routes api.localhost → port 4000
Your app (port 4000)

When you run unport start:

1. Reads domain from unport.json
2. Gets an available port from the daemon (4000-4999 range)
3. Detects your framework and starts your app with that port
4. Registers the domain→port mapping with the daemon

The daemon handles all routing. Your apps don't need to know about each other—just use stable domains like http://api.localhost.

Commands

Config

Create unport.json in your project:

{
  "domain": "myapp"
}

Most frameworks are auto-detected (Next.js, Vite, Express, Django, Rails, Go, etc.). If detection fails, add a start command:

{
  "domain": "myapp",
  "start": "npm run serve"
}

Your app must read the port from the PORT environment variable:

// Node.js
const port = process.env.PORT || 3000;

// Go
port := os.Getenv("PORT")

HTTPS Support

unport can serve your apps over HTTPS with automatically generated certificates.

Setup

# 1. Start daemon with HTTPS enabled
sudo unport daemon start -d --https

# 2. Trust the CA certificate (one-time setup)
sudo unport trust-ca

# 3. Start your app as usual
unport start

# Your app is now available at both:
# - http://myapp.localhost
# - https://myapp.localhost

How it works

When started with --https, unport:

1. Generates a local CA certificate (stored in ~/.unport/ca.crt)
2. Creates TLS certificates for *.localhost domains
3. Listens on both port 80 (HTTP) and port 443 (HTTPS)
4. Automatically updates certificates when new domains are registered

The CA only needs to be trusted once. After that, all *.localhost domains will have valid HTTPS.

Certificate management

# Regenerate certificates (e.g., after adding many domains)
unport regen-cert

# Remove CA from trust store
sudo unport trust-ca --remove

# Delete all generated certificates
unport clean-certs

License

MIT