npm package: @mucan54/porterman
Description: Zero-config HTTPS tunnels for your local ports. Powered by Cloudflare.
Author: mucan54
Latest version: 1.5.0

# Porterman

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

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

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

## How It Works

Porterman uses [Cloudflare Quick Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) 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

```bash
npm install -g @mucan54/porterman
```

Requires Node.js 18+.

## Usage

### Expose a single port

```bash
porterman expose 3000
```

### Expose multiple ports

```bash
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:

```bash
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`:

```js
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

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

### Shell eval mode

For direct shell variable export (useful in scripts):

```bash
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:

```json
{
  "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:

```bash
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

```bash
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

```bash
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

```typescript
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