pb-mapper exposes any number of local TCP/UDP services through a single public port. Instead of frp-style one-port-per-service mapping, services register under a key and anyone holding that key can reach them.
- One binary, one public port —
pb-mapperprovides every runtime role, while a service-key registry replaces per-service port planning. - Optional encryption — AES-256-GCM (via
ring) on forwarded traffic, enabled with--codecat registration. - Proven in production — on real workloads (e.g. a Palworld UDP server), latency matches frp with a directly exposed port.
With an AI coding agent (Claude Code, Cursor, Kiro), the built-in skills handle deployment interactively. The binary is downloaded locally and uploaded over SCP, so the remote host needs no GitHub access.
/pb-mapper-server-deploy— deployspb-mapper serveras a systemd service./pb-mapper-connect-deploy— deployspb-mapper connectas a managed tunnel and validates it end to end.
If the remote host can reach GitHub directly, this installs the unified pb-mapper binary and runs its server command as a systemd service on Linux (x86_64, musl) — port 7666, --use-machine-msg-header-key on, key stored at /var/lib/pb-mapper-server/msg_header_key.
curl -fsSL https://raw.githubusercontent.com/acking-you/pb-mapper/master/scripts/install-server-github.sh | bashAfter install, load the same key before running pb-mapper register or pb-mapper connect:
export MSG_HEADER_KEY="$(cat /var/lib/pb-mapper-server/msg_header_key)"
- Local service side (green) —
pb-mapper registerregisters a local TCP/UDP service. - Public network (blue) —
pb-mapper serverkeeps the registry and forwards data bidirectionally. - Remote client side (orange) —
pb-mapper connectsubscribes to a key and exposes it as a local port.
The register and connect workflows are also available in the Flutter UI.
Your web server runs on localhost:8080 at home.
Home LAN Public Server Coffee Shop
┌─────────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Web Server :8080 │ │ pb-mapper server │ │ Browser :3000 │
│ ↑ │ │ :7666 │ │ ↑ │
│ register ───────────┼──────►│ key='web' ──────┼◄──────┼── connect │
└─────────────────────┘ └──────────────────┘ └──────────────────┘
# 1. on the public server — start the central router
pb-mapper server --port 7666
# 2. at home — register the web server under key 'web'
pb-mapper register tcp --server <public-ip>:7666 --key web --addr 127.0.0.1:8080
# 3. at the coffee shop — subscribe and expose it locally
pb-mapper connect tcp --server <public-ip>:7666 --key web --addr 127.0.0.1:3000Open http://localhost:3000 in the coffee-shop browser — traffic flows through the public server back home.
| Command | Role |
|---|---|
pb-mapper server |
Central router (default port 7666) |
pb-mapper register tcp|udp |
Registers a local TCP/UDP service with the server |
pb-mapper connect tcp|udp |
Subscribes to a registered service and exposes a local port |
pb-mapper status keys|remote-id |
Queries the central router |
Flutter UI (ui/) |
GUI for server, register, connect, and status workflows |
- Rust core — the unified entry point is
src/bin/pb-mapper.rs; shared protocol and networking live insrc/commonandsrc/utils; server / register / connect internals live insrc/pb_server,src/local/server, andsrc/local/client. - Flutter UI — views in
ui/lib/src/views, FFI layers inui/lib/src/ffi, Rust bridge inui/native/pb_mapper_ffi. FFI calls run on a background isolate, and Rust returns JSON ({success, message, data}) to keep the C ABI stable.
- User guide (build / run / use):
docs/user-guide.md - Docker server guide:
DOCKER_README.md - 中文文档:
README.zh-CN.md,docs/user-guide.zh-CN.md
src/— Rust backendui/— Flutter UI + native bridgedocs/— documentation and assetsdocker/,services/,scripts/,tests/— deployment and toolingskills/— AI coding agent deployment skills (server and connect tunnel)
Released under the MIT License.