pipenet

Expose your local server to the public internet instantly.

Supported Protocols

pipenet tunnels any HTTP-based traffic to your local server:

Protocol	Supported	Notes
HTTP/HTTPS	✅	Standard request/response
WebSocket	✅	Full duplex communication via HTTP upgrade
SSE (Server-Sent Events)	✅	Long-lived HTTP connections
HTTP Streaming	✅	Chunked transfer encoding

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

event	args	description
request	info	fires when a request is processed by the tunnel, contains method and path fields
error	err	fires when an error happens on the tunnel
close		fires when the tunnel has closed

The tunnel instance has the following methods

method	args	description
close		close the tunnel

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:

Feature	pipenet	localtunnel
Cloud deployment support	✅ Single-port mode via --tunnel-port	❌ Requires random ports
Multiple domains	✅ --domain can be specified multiple times	❌ Single domain only
TypeScript	✅ Written in TypeScript with full type definitions	❌ JavaScript only
ESM support	✅ Native ES modules	❌ CommonJS only
Active maintenance	✅ Actively maintained	⚠️ Limited maintenance
WebSocket support	✅ Full WebSocket proxying	✅ Full WebSocket proxying

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.

pipenet vs zrok

zrok is a powerful tunneling solution with SDK support for Go, Python, and Node.js. However, zrok SDKs require the environment to be initialized via the CLI first - you can't just npm install and start tunneling.

pipenet is designed for zero-setup embedding:

import { pipenet } from 'pipenet';

const tunnel = await pipenet({ port: 3000 });
console.log(tunnel.url);

No CLI initialization, no external processes, no daemon - just a pure JavaScript library that works out of the box. This makes pipenet ideal for:

• CLI tools that need tunneling as a feature (e.g., mcp-proxy --tunnel)
• Test suites that need ephemeral public URLs
• Scripts that should "just work" without setup steps

If you need advanced features like TCP/UDP tunneling, identity management, or a managed SaaS, zrok is an excellent choice.

Acknowledgments

pipenet is based on localtunnel.

Development of pipenet is sponsored by glama.ai.