pipenet

Expose your local server to the public internet instantly

Installation

npm install pipenet

CLI Usage

# Expose local port 3000 to the internet
npx pipenet client --port 3000

# Request a specific subdomain
npx pipenet client --port 3000 --subdomain myapp

# Use a custom tunnel server
npx pipenet client --port 3000 --host https://your-tunnel-server.com

API

The pipenet client is also usable through an API (for test integration, automation, etc)

pipenet(port [,options][,callback])

Creates a new pipenet tunnel to the specified local port. Will return a Promise that resolves once you have been assigned a public tunnel url. options can be used to request a specific subdomain. A callback function can be passed, in which case it won't return a Promise. This exists for backwards compatibility with the old Node-style callback API. You may also pass a single options object with port as a property.

import { pipenet } from 'pipenet';

const tunnel = await pipenet({
  port: 3000,
  host: 'https://pipenet.dev'
});

// the assigned public url for your tunnel
// i.e. https://abcdefgjhij.pipenet.dev
tunnel.url;

tunnel.on('close', () => {
  // tunnels are closed
});

options

• port (number) [required] The local port number to expose through pipenet.
• host (string) URL for the upstream proxy server. Defaults to https://pipenet.dev.
• subdomain (string) Request a specific subdomain on the proxy server. Note You may not actually receive this name depending on availability.
• localHost (string) Proxy to this hostname instead of localhost. This will also cause the Host header to be re-written to this value in proxied requests.
• localHttps (boolean) Enable tunneling to local HTTPS server.
• localCert (string) Path to certificate PEM file for local HTTPS server.
• localKey (string) Path to certificate key file for local HTTPS server.
• localCa (string) Path to certificate authority file for self-signed certificates.
• allowInvalidCert (boolean) Disable certificate checks for your local HTTPS server (ignore cert/key/ca options).

Refer to tls.createSecureContext for details on the certificate options.

Tunnel

The tunnel instance returned to your callback emits the following events

The tunnel instance has the following methods

Server

This package includes both the client and server components. You can run your own pipenet server.

Running the Server

# Using the CLI
npx pipenet server --port 3000

# With a custom domain
npx pipenet server --port 3000 --domain tunnel.example.com

# With multiple domains
npx pipenet server --port 3000 --domain tunnel.example.com --domain tunnel.example.org

# For cloud deployments (single tunnel port mode)
npx pipenet server --port 3000 --tunnel-port 3001 --domain tunnel.example.com

# Or programmatically

import { createServer } from 'pipenet/server';

const server = createServer({
  domains: ['tunnel.example.com'],   // Optional: custom domain(s)
  secure: false,                     // Optional: require HTTPS
  landing: 'https://pipenet.dev',    // Optional: landing page URL
  maxTcpSockets: 10,                 // Optional: max sockets per client
  tunnelPort: 3001,                  // Optional: shared tunnel port for cloud deployments

  // Lifecycle hooks for tracking tunnels and requests
  onTunnelCreated: (tunnel) => {
    console.log(`Tunnel created: ${tunnel.id} at ${tunnel.url}`);
  },
  onTunnelClosed: (tunnel) => {
    console.log(`Tunnel closed: ${tunnel.id}`);
  },
  onRequest: (request) => {
    console.log(`Request: ${request.method} ${request.path} via ${request.tunnelId}`);
  },
});

// Start tunnel server if using shared tunnel port
if (server.tunnelServer) {
  await server.tunnelServer.listen(3001);
}

server.listen(3000, () => {
  console.log('pipenet server listening on port 3000');
});

Server Options

• domains (string[]) Custom domain(s) for the tunnel server.
• secure (boolean) Require HTTPS connections
• landing (string) URL to redirect root requests to
• maxTcpSockets (number) Maximum number of TCP sockets per client (default: 10)
• tunnelPort (number) Shared tunnel port for cloud deployments (enables single-port mode)

Server Hooks

The server supports lifecycle hooks for tracking tunnels and requests:

• onTunnelCreated(tunnel) - Called when a new tunnel is created. Receives { id, url, domain }.
• onTunnelClosed(tunnel) - Called when a tunnel is closed. Receives { id, url, domain }.
• onRequest(request) - Called when a request is proxied through a tunnel. Receives { method, path, tunnelId, headers, remoteAddress }.

The domain field identifies which configured domain was used when the tunnel was created, which is useful when running a server with multiple domains.

The onRequest hook provides access to request headers and the client's remote IP address, useful for logging, rate limiting, or authentication.

Server API Endpoints

• GET /api/status - Server status and tunnel count
• GET /api/tunnels/:id/status - Status of a specific tunnel
• GET /:id - Request a new tunnel with the specified ID

Cloud Deployments

When deploying pipenet server to cloud platforms like fly.io, Docker, or Kubernetes, you typically can only expose a limited number of ports. By default, pipenet creates a random TCP port for each tunnel client, which doesn't work well in these environments.

Use the --tunnel-port option to enable single-port mode, where all tunnel clients connect to a single shared port:

# fly.io example
pipenet server --port 8080 --tunnel-port 8081 --domain tunnel.example.com --secure

Then expose both ports in your deployment configuration. For fly.io:

[[services]]
  internal_port = 8080
  protocol = "tcp"
  [[services.ports]]
    port = 80
    handlers = ["http"]
  [[services.ports]]
    port = 443
    handlers = ["http", "tls"]

[[services]]
  internal_port = 8081
  protocol = "tcp"
  [[services.ports]]
    port = 8081

Why pipenet?

pipenet was developed by glama.ai to enable local Model Context Protocol (MCP) servers to connect with remote AI clients (e.g., to give AI assistants access to your local file system).

This capability is now integrated into mcp-proxy.

pipenet vs localtunnel

pipenet is a modernized fork of localtunnel with several improvements:

Key Differences

Cloud Deployment Support: localtunnel creates a random TCP port for each tunnel client, which doesn't work in containerized environments like Docker, fly.io, or Kubernetes where only specific ports are exposed. pipenet solves this with the --tunnel-port option, enabling all clients to connect through a single shared port.

Modern JavaScript: pipenet uses ES modules and is written in TypeScript, providing better IDE support, type safety, and compatibility with modern JavaScript tooling.

Acknowledgments

pipenet is based on localtunnel.

Development of pipenet is sponsored by glama.ai.