Related Pages

Related topics: Client Architecture, Server Architecture, Deployment & Cloud Operations

Overview & Getting Started

Purpose and Scope

pipenet is a Node.js tunneling library and CLI that exposes a local HTTP server to the public internet by assigning it a temporary public URL. It is a modernized TypeScript fork of localtunnel, maintained by Frank Fiegel and sponsored by glama.ai Source: [README.md].

The project was created to enable local Model Context Protocol (MCP) servers to be reached by remote AI clients — for example, to give an AI assistant access to a local file system. This capability is now integrated into mcp-proxy Source: [README.md].

pipenet supports the following protocols over a single tunnel Source: [README.md]:

High-Level Architecture

The package ships two complementary surfaces — a client library that connects a local port to a remote tunnel server, and a server module that hosts public-facing tunnel endpoints Source: [src/server/index.ts].

flowchart LR
  Browser[Public Client / Browser] -->|HTTPS request| Server[pipenet Server<br/>Koa + Router]
  Server -->|route by subdomain| Manager[ClientManager]
  Manager -->|match id| Agent[TunnelAgent<br/>maxConn + net.Server]
  Agent <-->|raw TCP| Client[TunnelCluster<br/>local socket]
  Client -->|forward HTTP/WS| LocalApp[Local HTTP Server]

The client uses axios to request a tunnel assignment from the server, then opens a long-lived TCP connection through TunnelCluster Source: [src/Tunnel.ts]. The server is built on koa with koa-router for routing and pump for socket streaming Source: [package.json].

Installation

pipenet is published as a native ESM package and requires Node.js ≥ 22.0.0 Source: [package.json]. The package manager pinned in the lockfile is [email protected] Source: [package.json].

# As a project dependency
npm install pipenet

# As a global CLI
npm install -g pipenet

The bin field exposes a pipenet executable that maps to the compiled CLI Source: [package.json]. Type definitions ship via dist/pipenet.d.ts, and an additional ./server subpath export gives access to the server module Source: [package.json].

CLI Usage

The CLI entry point offers a client subcommand for the most common workflow Source: [README.md]:

# 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

Common Options

The CLI is built with yargs and supports the following options (derived from the public API and README) Source: [README.md, src/pipenet.ts]:

Community note: Issue #1 reports that pipenet client --port 3303 returned a 404 immediately after printing the public URL. This behavior was caused by the client not aborting when the server returned a 4XX response, and was fixed in v1.4.2 by commit e5a5a34 ("abort tunnel creation on 4XX") Source: [src/Tunnel.ts].

Programmatic API

The library exposes a top-level pipenet function that returns either a Promise<Tunnel> or, with a Node-style callback, the Tunnel directly Source: [src/pipenet.ts]:

import { pipenet } from 'pipenet';

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

// tunnel.url  -> "https://<random>.pipenet.dev"
// tunnel.client.close() to shut down

The function is overloaded to accept either (port) or (options), plus an optional callback Source: [src/pipenet.ts]. Re-exports include Tunnel, TunnelCluster, HeaderHostTransformer, and the option types TunnelOptions / TunnelClusterOptions / TunnelRequest Source: [src/pipenet.ts].

The internal flow inside Tunnel._getInfo issues GET ${opt.host}/${assignedDomain || '?new'} and resolves once the server replies with a tunnel assignment. On any 4XX response, the callback now receives an error rather than silently retrying Source: [src/Tunnel.ts].

Development & Testing

The project uses vitest for tests, configured to discover files matching src/**/*.spec.ts with a 30s timeout Source: [vitest.config.ts]. Linting is provided by eslint with typescript-eslint, eslint-plugin-perfectionist (alphabetical sort) and Prettier Source: [eslint.config.ts]. The standard scripts are:

pnpm build          # tsc -> dist/
pnpm test           # vitest run
pnpm start:server   # node dist/server/index.js

Source: [package.json]

See Also

• Server Module & Hooks — Koa routing, ClientManager, TunnelAgent, and the --tunnel-port cloud mode.
• TunnelClient & TunnelCluster — Connection lifecycle, WebSocket upgrade, and the HeaderHostTransformer.
• Issue #1 — "Gives 404" — Historical failure mode now fixed in v1.4.2.

Related Pages

Related topics: Overview & Getting Started, Server Architecture

Client Architecture

The pipenet client is the half of the system that runs inside a developer's process (or the CLI) and forwards inbound tunnel traffic to a local HTTP/WebSocket server. The whole client fits in a small set of TypeScript classes under src/, exposed through a single pipenet() factory.

1. High-Level Architecture

The client is built as three layered components that each own one concern:

The default host, when none is supplied, is https://pipenet.dev (src/Tunnel.ts:24-26). The package ships as a native ESM module with TypeScript types (package.json:9-19) and depends on axios, debug, and the ws/Node net stack for the underlying transport (package.json:50-58).

flowchart LR
    User["Caller / CLI"] -->|"pipenet(port, opts)"| API["pipenet.ts<br/>(entry)"]
    API -->|new Tunnel| T["Tunnel.ts<br/>(state + events)"]
    T -->|axios GET /?new| S[("pipenet server")]
    S -->|url, port, maxConn| T
    T -->|net.connect| C["TunnelCluster.ts<br/>(TCP pool)"]
    C -->|Host rewrite| H["HeaderHostTransformer.ts"]
    H -->|local HTTP/WS| Local[("Local server")]
    Remote["Public client"] -->|HTTPS / WSS| S
    S -->|tunneled stream| C

2. Entry Point: `pipenet()`

src/pipenet.ts is intentionally tiny: it is a set of TypeScript overloads that accept (port), (port, opts), (opts), or any of those with a Node-style callback, and normalizes them into a single TunnelOptions object (src/pipenet.ts:23-47). It then constructs a Tunnel and either calls client.open(cb) for the callback style or wraps it in a Promise for the modern async style (src/pipenet.ts:40-47).

This is the surface that CLI users hit when running npx pipenet client --port 3000, and it is also the surface that the documented "zero-setup embedding" use case relies on: await pipenet({ port: 3000 }) (README.md). The integration test in src/pipenet.spec.ts exercises exactly this shape against an in-process tunnel server, asserting that the returned url matches ^https?://[a-z0-9-]+\.localhost:\d+$ (src/pipenet.spec.ts:48-58).

3. The `Tunnel` Class

Tunnel (src/Tunnel.ts) is an EventEmitter that represents one live tunnel. Its public surface is:

• cachedUrl, clientId, url — assigned from the server's response
• open(cb) — kicks off the two-phase process: first _init negotiates a URL with the server, then _establish opens the cluster
• close() — flips closed = true and emits 'close'

The _init step sends an HTTP GET to ${opt.host}/?new (or ${opt.host}/${subdomain}) with axios and retries every 1 s on network errors, but it now fails fast on any 4XX response (src/Tunnel.ts:_init). This is the fix shipped in v1.4.2 — "abort tunnel creation on 4XX" (v1.4.2 release notes), and it directly addresses community report #1 "Gives 404" (issue #1), where the old code kept retrying and printing a stale-looking URL like https://loud-shrimp-92.pipenet.dev instead of surfacing the server's error. After a successful handshake, _establish creates a TunnelCluster, raises the listener cap to maxConn + defaultMaxListeners, and wires the cluster's 'open', 'error', and per-tunnel events through to the Tunnel (src/Tunnel.ts:_establish).

4. `TunnelCluster`: The TCP Multiplexer

Once the server has assigned a port (random by default, or a single shared port when the server is started with --tunnel-port for cloud deployments — see README.md: "Cloud Deployments"), TunnelCluster opens a net.connect/tls.connect socket to that port and demultiplexes many logical streams over it (src/TunnelCluster.ts:25-65). Each incoming stream from the server is rewritten through HeaderHostTransformer and pipelined to localHost:localPort over plain HTTP or HTTPS depending on localHttps/localCert/localKey (src/TunnelCluster.ts:25-50).

TunnelClusterOptions (src/TunnelCluster.ts:14-29) is what the server response is mapped onto; the cluster only knows about remoteHost, remotePort, remoteIp, localPort, localHttps, maxConn, and sharedTunnel. The sharedTunnel flag is what enables single-port mode: instead of connecting to a per-tunnel random port, the client connects to the server's shared tunnel port, which is the deployment model introduced in v1.3.0 (v1.3.0 release notes). The cluster also accepts allowInvalidCert and a cachedUrl for stable reattachment across reconnects.

A bug in v1.4.0/v1.4.1 — a "close listener leak on rapid tunnel reconnections" — was fixed by v1.4.1 inside this same file path; understanding TunnelCluster's socket lifecycle is therefore important when debugging client reconnection behavior.

5. Failure Modes and Common Pitfalls

• Server 4XX errors (e.g. invalid subdomain, rate limit, unknown host): since v1.4.2, Tunnel._init rejects the promise instead of looping, so the caller sees a real error message rather than a perpetually reconnecting client (src/Tunnel.ts:_init).
• Wrong port forwarded in cloud deployments: if the server is started without --tunnel-port, each client needs its own random TCP port exposed. The README's fly.io example shows the correct two-service [[services]] block (README.md: "Cloud Deployments").
• Process exits immediately after the URL is printed: this matches the symptom in issue #1. The tunnel is held open by the long-lived TunnelCluster socket; the process only stays alive while that socket and any open streams are active, so an embedding script must await the Tunnel or attach an event listener before letting the event loop drain.
• Reusing a stale URL: the client supports cachedUrl so a process restart can try to reattach to the same tunnel, but the server must still have that tunnel registered.

See Also

• Server Architecture — the receiving side of the same protocol
• Tunnel Lifecycle and Events — event semantics for Tunnel and TunnelCluster
• Cloud Deployment Guide — --tunnel-port and single-port mode
• Project README

Related Pages

Related topics: Client Architecture, Deployment & Cloud Operations

Server Architecture

Overview

The pipenet server is the public-facing counterpart to the pipenet client. It accepts inbound HTTP, HTTPS, WebSocket, SSE, and chunked-streaming traffic on one or more public domains and proxies each request back through a long-lived TCP connection to the originating tunnel client, which in turn forwards it to a local server. The server is implemented as a single factory, createServer, that wires together a Koa HTTP front-end with a TCP tunnel layer and a ClientManager that tracks live tunnels. Source: src/server/server.ts

The public server entry point exports the factory and its associated types from src/server/index.ts, allowing the same code to be embedded by the hosted pipenet.dev service, by npx pipenet server, or by any program that needs a self-hosted tunnel endpoint. Source: src/server/index.ts

The runtime is Node.js (>=22) and uses koa, koa-router, axios, debug, pump, tldjs, human-readable-ids, and yargs. Source: package.json

Core Components

The server is composed of five cooperating classes. The first three are always active; the last two are mode-dependent.

`createServer` and `ServerOptions`

createServer(options?) returns a PipenetServer (a Koa http.Server-compatible object). ServerOptions accepts address, domains, maxTcpSockets, a secure flag, and a hooks object. The factory installs request routing, the /api/status and /api/tunnels/:id/status endpoints, the root redirect to https://pipenet.dev/, and a WebSocket upgrader. Source: src/server/server.ts

Subdomain names must be lowercase alphanumeric and between 4 and 63 characters; oversized or malformed requests are rejected with a descriptive error. Source: src/server/server.spec.ts

`ClientManager`

ClientManager is the registry of active tunnels. It tracks a Map<id, Client>, assigns random human-readable IDs via the human-readable-ids package when a preferred subdomain is unavailable, and exposes stats and hasClient for inspection. Source: src/server/ClientManager.ts

`Client` and `TunnelAgent`

Each Client owns a TunnelAgent that listens on a random local TCP port. Inbound HTTP traffic to the public URL is reparsed, re-serialized, and pumped through the agent socket to the pipenet client, which then replays it against the user's local server. WebSocket upgrades are detected on the HTTP request and proxied bidirectionally. Source: src/server/Client.ts

TunnelAgent enforces maxTcpSockets, supports createConnection() for both legacy and sharedTunnel modes, and exposes stats() for monitoring. Source: src/server/TunnelAgent.ts

`TunnelServer` (shared-port mode)

When TunnelServer is enabled, all clients connect to a single TCP port and identify themselves with an ID as the first message. The server routes each accepted socket to the registered handler. This is what makes pipenet deployable to platforms like fly.io, Docker, or Kubernetes where only a few ports can be exposed. Source: src/server/TunnelServer.ts

Request Flow

The diagram below traces a single inbound request through the architecture, from public internet to local server and back.

flowchart LR
  A[Public client] -->|HTTPS to loud-shrimp-92.pipenet.dev| B(Koa router)
  B --> C{Subdomain in ClientManager?}
  C -- no --> Z[404 / error]
  C -- yes --> D[Client]
  D --> E[TunnelAgent]
  E -->|TCP to tunnel port| F[Remote pipenet client]
  F --> G[Local server]
  G --> F --> E --> D --> B --> A
  H[TunnelServer / shared port] -. multiplexes .-> F

In shared-port mode, step 3b is replaced by a single TunnelServer that demultiplexes incoming connections by client ID before handing the socket to the correct Client handler. Source: src/server/TunnelServer.ts

Configuration, Hooks, and Common Failures

Multiple domains. ServerOptions.domains accepts an array; each public host the server should serve must be listed, otherwise requests are rejected. Multiple-domain support was added in v1.2.0. Source: src/server/server.ts

Hooks. Added in v1.4.0, the optional ServerHooks interface lets operators observe lifecycle events such as onRequest (with domain, path, tunnelId, headers, remoteAddress) for logging, rate limiting, or authentication. Source: src/server/server.ts

Cloud deployment. The CLI flag --tunnel-port <port> activates the shared TunnelServer. A typical fly.io configuration exposes one HTTP port (80/443) and the dedicated tunnel port (e.g. 8081); both must be declared in fly.toml. Source: src/server/TunnelServer.ts

API endpoints. GET /api/status reports server-wide tunnel counts; GET /api/tunnels/:id/status reports a specific tunnel. The root / redirects to the project landing page. Source: src/server/server.spec.ts

4XX errors and tunnel creation. v1.4.2 introduced a fix that aborts tunnel creation whenever the server returns a 4XX response (e.g. invalid subdomain, server policy). This addresses the "Gives 404" community report where npx pipenet client --port 3303 produced a URL but every request to it returned 404 — the client should now fail fast instead of handing out a non-functional URL. Source: src/Tunnel.ts

Listener leaks. v1.4.1 fixed a leak of close listeners on rapid tunnel reconnections, so a server that experiences flapping clients no longer accumulates listeners on its net.Server. Source: src/server/TunnelServer.ts

See Also

• README.md — usage examples and comparison with localtunnel/zrok
• src/pipenet.ts — the client-side factory used by npx pipenet client
• src/TunnelCluster.ts — client-side TCP cluster that pairs with TunnelAgent

Related Pages

Related topics: Overview & Getting Started, Server Architecture

Deployment & Cloud Operations

Overview

pipenet is an HTTP/WebSocket tunneling service that exposes a local server to the public internet. In production it is split into two cooperating processes: a public tunnel server that accepts inbound HTTP traffic on a hostname, and one or more tunnel clients that establish an outbound TCP connection back to that server and proxy requests to a local port.

The "Deployment & Cloud Operations" surface of the project covers everything required to run the server in a containerized or hosted environment: starting the Koa-based server, configuring domains, enabling the single-port shared-tunnel mode required for environments that only expose a fixed port set (Docker, fly.io, Kubernetes), observing runtime state, and integrating with the pipenet programmatic API. Source: README.md documents this split and the key operational difference from the upstream localtunnel project: pipenet's --tunnel-port flag.

The package exposes a bin entry, a programmatic createServer factory, and a client API. Source: package.json defines "main": "./dist/pipenet.js", the bin.pipenet script (./dist/cli.js), and an additional sub-export at ./server so consumers can import server types without pulling in the client. The Node engine is pinned at >=22.0.0, which must be respected when selecting container base images.

Server Lifecycle and Configuration

The server is created with createServer(opt) from src/server/server.ts, which constructs a Koa application, a router, an optional TunnelServer, and a ClientManager. CLI flags in src/cli.ts map directly onto the ServerOptions interface. The most relevant deployment options are:

When tunnelPort is supplied, createServer instantiates a TunnelServer and passes it to the ClientManager. Source: src/server/server.ts shows this conditional construction: const tunnelServer = opt.tunnelPort ? new TunnelServer() : undefined; followed by new ClientManager({ ...opt, tunnelServer }). Without tunnelPort, each tunnel client asks the server to allocate a fresh random TCP port — this works on a developer machine but is incompatible with most hosted platforms that only expose a fixed set of inbound ports.

Shared Tunnel Mode for Cloud Deployments

The shared-tunnel architecture is the primary cloud-deployment story. In this mode every client connects to a single known TCP port on the tunnel server. The server demultiplexes traffic by client id, which is safer for containerized platforms because it removes the requirement to publish a wide port range. Source: src/server/TunnelServer.ts implements the demultiplexer, while src/server/TunnelAgent.ts tracks per-client state, including started, maxTcpSockets, and live TunnelAgentStats.

A typical cloud deployment therefore looks like:

flowchart LR
    Internet((Internet clients)) -->|HTTPS on --port| Server[pipenet server]
    Server -->|Koarouter| ClientMgr[ClientManager]
    ClientMgr -->|demux by client id| TunnelSrv[TunnelServer on --tunnel-port]
    TunnelSrv -->|TCP socket pool| Agent1[TunnelAgent client A]
    TunnelSrv -->|TCP socket pool| Agent2[TunnelAgent client B]
    Agent1 --> Local1[Local service on host A]
    Agent2 --> Local2[Local service on host B]

Source: README.md frames the operational distinction this way: "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."

The shared-port design pairs with the client side. Source: src/TunnelCluster.ts describes TunnelClusterOptions.sharedTunnel, which is set when the server advertises single-port mode. The cluster opens a single TCP connection to the server and routes each HTTP request through it. Source: src/Tunnel.ts composes one or more TunnelCluster instances and exposes reconnect, header-preservation, and localHttps support.

CLI Commands and Operational Patterns

The CLI entry point in src/cli.ts dispatches on the first positional argument:

# Run a public tunnel server in cloud mode
npx pipenet server --port 3000 --tunnel-port 3000

# Connect a client through a hosted server
npx pipenet client --port 3000 --host https://tunnel.example.com

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

runClient parses optional headers as JSON, instantiates the client, and prints the assigned tunnel.url. The runServer branch (defined in the same file) wires createServer to opt.port and opt.address, and delegates HTTP listener lifecycle to Koa. Source: src/cli.ts shows the ClientOptions and ServerOptions TypeScript interfaces; the CLI is the canonical example for deploying without writing custom code.

For programmatic deployment — typical when embedding pipenet inside another service such as mcp-proxy — the public API in src/pipenet.ts exposes the pipenet() factory, which accepts either (port, options) or a single options object and returns a Promise<Tunnel> (or, when a callback is supplied, returns the Tunnel synchronously for backwards compatibility).

Observability, Hooks, and Common Failures

Operators typically want runtime visibility. Source: src/server/server.ts exposes GET /api/status, which returns { mem: process.memoryUsage(), tunnels: manager.stats.tunnels }, and GET /api/tunnels for active tunnel listings. The ClientManager exposes aggregated stats.tunnels and per-client TunnelAgentStats, so a sidecar healthcheck can poll /api/status and alert when the tunnel count drops unexpectedly. Hooks for request/error lifecycle events were added in v1.4.0 (commit e96df31) so operators can plug in logging or metrics without forking the server.

A known operational failure mode reported by users is the "your url is: ... pipenet.dev then returns the prompt" behavior in issue #1. The root cause is that the default --host is not always resolvable in some network environments, so the public hostname is assigned but the local server cannot be reached. v1.4.2 added a fix (commit e5a5a34) to abort tunnel creation on 4XX, which surfaces the failure rather than silently returning a dead URL. v1.4.1 (commit 95ad0be) also closed a socket listener leak that occurred on rapid reconnects — relevant for ops scripts that restart clients on a tight loop.

Operational best practices distilled from the source:

• Pin Node to >=22.0.0 per package.json engine field.
• Use --tunnel-port in any containerized deployment to avoid port-range publishing, per src/server/server.ts and README.md.
• List every served domain with repeated --domain flags; v1.2.0 made multi-domain explicit. Source: src/server/server.ts shows validHosts flowing into tldjs.fromUserSettings.
• Monitor /api/status for tunnels count and RSS; drop in custom hooks (v1.4.0) to ship logs.
• Upgrade to ≥ v1.4.2 to ensure 4XX responses abort tunnel creation instead of returning an invalid URL.

See Also

• README.md — high-level overview, comparison with localtunnel and zrok
• src/pipenet.ts — programmatic client API
• src/server/server.ts — createServer factory
• src/server/TunnelServer.ts — shared-port demultiplexer
• src/server/TunnelAgent.ts — per-client socket pool
• src/cli.ts — CLI surface and option definitions

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/punkpeye/pipenet/issues/1

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/punkpeye/pipenet

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/punkpeye/pipenet

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/punkpeye/pipenet

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/punkpeye/pipenet

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/punkpeye/pipenet

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/punkpeye/pipenet

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using pipenet with real data or production workflows.

• Gives 404 - github / github_issue
• v1.4.2 - github / github_release
• v1.4.1 - github / github_release
• v1.4.0 - github / github_release
• v1.3.0 - github / github_release
• v1.2.1 - github / github_release
• v1.2.0 - github / github_release
• v1.1.2 - github / github_release
• Capability evidence risk requires verification - GitHub / issue