Porterman

Your ports, delivered. Zero-config HTTPS tunnels powered by Cloudflare.

One command. Real HTTPS. No servers. No accounts. No configuration.

$ porterman expose 3000
https://random-words-here.trycloudflare.com -> http://localhost:3000

How It Works

Porterman uses Cloudflare Quick Tunnels to expose your local ports to the internet. It automatically:

1. Downloads the cloudflared binary (first run only)
2. Creates a Cloudflare Tunnel for each specified port
3. Assigns a public *.trycloudflare.com HTTPS URL to each port
4. Routes traffic from the public URL to your local service

No Cloudflare account needed. No public IP needed. No SSL certificates to manage. Works behind NAT, firewalls, and any network.

Installation

npm install -g @mucan54/porterman

Requires Node.js 18+.

Usage

Expose a single port

porterman expose 3000

Expose multiple ports

porterman expose 3000 8080 5173
# https://random-abc.trycloudflare.com -> http://localhost:3000
# https://random-def.trycloudflare.com -> http://localhost:8080
# https://random-ghi.trycloudflare.com -> http://localhost:5173

Map tunnel URLs to environment variables

Append :ENV_VAR_NAME to any port to automatically save the tunnel URL to a .env.porterman file:

porterman expose 3000:FRONTEND_URL 8080:API_URL

This creates .env.porterman in the current directory:

# Generated by Porterman
FRONTEND_URL=https://random-abc.trycloudflare.com
API_URL=https://random-def.trycloudflare.com

Then in your project's .env or code, load it however your framework supports. For example with dotenv:

require("dotenv").config({ path: ".env.porterman" });
console.log(process.env.FRONTEND_URL);

The file is automatically cleaned up when Porterman stops.

Custom env file path

porterman expose 3000:APP_URL --env-file .env.tunnels

Shell eval mode

For direct shell variable export (useful in scripts):

eval $(porterman expose 3000:FRONTEND_URL --eval)
echo $FRONTEND_URL

Settings file mode

Create a <name>.porterman.json file in your project root to define tunnels and environment variable mappings declaratively:

{
  "tunnels": {
    "3000": {
      "envFiles": [
        {
          "file": ".env",
          "variables": {
            "PUBLIC_API_URL": "$tunnelUrl",
            "PUBLIC_REVERB_HOST": "$tunnelHostname",
            "PUBLIC_REVERB_PORT": 443
          }
        },
        {
          "file": "config.json",
          "filePath": "./config",
          "variables": {
            "api.url": "$tunnelUrl",
            "reverb.host": "$tunnelHostname",
            "reverb.port": 443
          }
        }
      ]
    },
    "5177": {
      "envFiles": [
        {
          "file": ".env",
          "variables": {
            "PUBLIC_FRONTEND_URL": "$tunnelUrl"
          }
        }
      ]
    }
  },
  "cleanup": true,
  "verbose": false
}

Then run:

porterman expose settings    # reads settings.porterman.json
porterman expose dev         # reads dev.porterman.json
porterman expose production  # reads production.porterman.json

Placeholders:

• $tunnelUrl — full tunnel URL (e.g., https://abc-random.trycloudflare.com)
• $tunnelHostname — hostname only (e.g., abc-random.trycloudflare.com)
• Any other value — written as-is (static value)

File types: .json files use dot notation for nested paths (e.g., "api.url" sets { "api": { "url": "..." } }). All other files are treated as env files (KEY=VALUE). You can override with an explicit "type": "env" or "type": "json" field.

filePath: Optional base directory for resolving the file path. Supports relative (from cwd) and absolute paths.

Options:

• cleanup (default: true) — delete backup file on shutdown. Override with --cleanup / --no-cleanup
• verbose (default: false) — enable verbose logging. Override with -v / --verbose

How it works:

1. Starts a Cloudflare tunnel for each port
2. Backs up original values to .<name>.porterman.backup.env
3. Writes new values into your env/JSON files
4. Restores everything on shutdown (Ctrl+C)

If porterman crashes, the backup file survives. On next startup, porterman detects it and restores your original values before proceeding.

.gitignore recommendation:

*.porterman.backup.env

The *.porterman.json config files should be committed (they're project config).

Verbose mode

porterman expose 3000 --verbose

All options

porterman expose [...ports]

Ports can be plain numbers or port:ENV_VAR pairs:
  3000              Expose port 3000
  3000:MY_URL       Expose port 3000, save URL as MY_URL

Options:
  -v, --verbose          Log all tunnel activity
  --env-file <path>      Path to write env file (default: .env.porterman)
  --eval                 Output export statements for shell eval

Other commands

porterman status          # Show running instance info
porterman stop            # Stop running instance
porterman --help          # Show help
porterman --version       # Show version

Features

• Zero config -- just specify the port(s)
• Real HTTPS -- Cloudflare handles TLS, no certificates needed
• Works anywhere -- behind NAT, firewalls, no public IP required
• Multi-port -- expose multiple services simultaneously
• Env variable mapping -- auto-write tunnel URLs to .env files
• Settings file mode -- declarative config via <name>.porterman.json with automatic backup/restore
• WebSocket support -- full WS/WSS proxying
• No account needed -- uses Cloudflare Quick Tunnels (free)
• Auto-install -- downloads cloudflared binary automatically on first run
• Cross-platform -- works on macOS, Linux, and Windows

Architecture

Internet Request
    |
    |  https://random-words.trycloudflare.com
    v
+-----------------------------+
|  Cloudflare Edge Network    |
|  (TLS termination, CDN,    |
|   DDoS protection)         |
+-----------------------------+
    |
    |  cloudflared tunnel
    v
+-----------------------------+
|  Your Machine (any network) |
|  localhost:3000             |
+-----------------------------+

Programmatic API

import { startServer } from "@mucan54/porterman";

// Simple usage
const server = await startServer({
  ports: [3000, 8080],
  verbose: true,
});

// server.urls is a Map<number, string> of port -> URL
console.log(server.urls);

// With env variable mapping
const server2 = await startServer({
  ports: [
    { port: 3000, envVar: "FRONTEND_URL" },
    { port: 8080, envVar: "API_URL" },
  ],
  envFile: ".env.tunnels",
});

// server.envVars is a Map<string, string> of ENV_VAR -> URL
console.log(server2.envVars.get("FRONTEND_URL"));

// Graceful shutdown (also cleans up .env file)
await server.close();

Limitations

• Quick Tunnels have a 200 concurrent request limit per tunnel
• URLs are randomly generated and change each time
• No SLA or uptime guarantee from Cloudflare for free tunnels
• Server-Sent Events (SSE) are not supported on Quick Tunnels

Requirements

• Node.js >= 18
• Internet connection (to reach Cloudflare)

License

MIT