---

Remote control infrastructure for the agent harness era.

Agent harnesses can write code, run tools, and coordinate long workflows. They still need a narrow, durable path into private runtimes. pb-mapper provides that network primitive: expose one relay port, register any number of keyed TCP/UDP services behind it, and delegate access without publishing every service or sharing the relay's root credential.

pb-mapper transports bytes. The service behind a tunnel still owns its application-level authentication and authorization.

Why it fits an agent harness

• Compact and easy to embed — one Rust binary contains the relay, register, connect, status, and administrator roles. Linux releases are distributed as a small, self-contained archive with no language runtime to install.
• One public port, many control paths — registration, subscription, status, and administration all enter through the same relay port. Adding another remote-control endpoint does not require another public listener.
• Delegate access instead of the root key — keep one 32-byte administrator key on the relay and issue renewable, expiring pbmt1_ credentials to harnesses or workloads. Each credential receives an isolated namespace.
• Revoke live access — expiry, revocation, auth-state reset, and root-key rotation close affected live control and data connections.
• Native performance, production experience — the data path is implemented in Rust on Tokio, supports TCP and UDP, and has been exercised by long-running self-hosted products and real game-server traffic. The end-to-end suite covers the transport/encryption matrix and credential lifecycle.

One relay, many private services

 private runtime A ── register "app" ──┐
 private runtime B ── register "shell" ├──► pb-mapper relay :7666 ◄── agent harnesses
 private runtime C ── register "tools" ┘          one public port

• pb-mapper register runs beside a private TCP/UDP service and publishes a service name to the relay.
• pb-mapper connect runs beside an agent or operator and exposes that service on a local address.
• The relay matches both sides by namespace and service name, then forwards data bidirectionally.
• Different temporary credentials can reuse the same service names without seeing or colliding with each other.

This makes a relay a useful rendezvous layer for remote agent runtimes, coding harnesses, private APIs, model gateways, browser-control endpoints, development machines, and operational tools.

Install the agent Skill

Tell your agent:

Fetch and follow instructions from https://raw.githubusercontent.com/acking-you/pb-mapper/master/skills/pb-mapper-suite/INSTALL.md

Credential model for automation

Protocol v2 authenticates the encrypted first request without adding a separate handshake round trip. Temporary credentials are derived from the administrator key, persistent server instance ID, and key ID; the relay stores lifecycle metadata rather than a copy of each temporary secret. Optional AES-256-GCM data encryption is enabled with --codec when registering a service.

pb-mapper uses pre-shared credentials, not public-key identity. Use TLS or another application protocol when you also need certificate-based endpoint identity or protection against traffic analysis. See the authentication design for the exact boundary.

Current integration surface

Rust SDK

pb-mapper = "0.5"

use pb_mapper::{Client, ClientConfig, RegisterRequest, Transport};

let client = Client::new(ClientConfig {
    server: "relay.example.com:7666".into(),
    credential: std::env::var("MSG_HEADER_KEY")?,
    keep_alive: true,
    namespace: None,
})?;
let registration = client.register(RegisterRequest {
    key: "echo".into(),
    local_addr: "127.0.0.1:8080".into(),
    transport: Transport::Tcp,
    codec: false,
    force_namespace: false,
}).await?;
registration.wait_ready().await?;

CLI and relay server

Install the unified CLI directly from crates.io:

cargo install pb-mapper-cli --locked

The package is named pb-mapper-cli, and it installs one executable named pb-mapper. That executable contains the server, register, connect, status, and admin roles, so a separate server executable is not required.

The relay implementation is also published as the pb-mapper-server library for applications that need to embed it.

TypeScript (Node-API)

npm install pb-mapper

import { Client } from "pb-mapper";

const client = new Client({
  server: "relay.example.com:7666",
  credential: process.env.MSG_HEADER_KEY!,
});
const admin = client.admin();
const issued = await admin.issueKey(3600, "agent");

Roadmap: harness-native remote control

The current release provides the secure network, a Rust client SDK, and a Node-API package. Remaining work:

• harness-specific adapters and credential automation built on the existing pb-mapper-suite workflow;
• further shrinking the client-only Node addon (release-node + strip is already under 5 MB on linux-x64);
• browser and edge adapters for runtimes that cannot load a native Node-API addon;
• harness adapters and examples for remote model runtimes, tool servers, private APIs, development machines, and browser-control endpoints.

These are roadmap items, not yet part of the published compatibility contract.

Build and documentation

make build-pb-mapper
cargo test

• User guide: docs/user-guide.md
• Authentication and protocol v2: docs/authentication-v2.md
• Docker server guide: DOCKER_README.md
• Chinese documentation: README.zh-CN.md, docs/user-guide.zh-CN.md

Repository layout:

• crates/ — Rust workspace: core, auth, protocol, server, client, SDK facade (pb-mapper), Node-API (pb-mapper-node), CLI, and testkit
• js/ — JS package wrapping the Node-API addon (built with bun)
• ui/ — Flutter UI and native C ABI bridge
• skills/ — agent-readable deployment and release workflows
• docs/ — architecture, authentication, user guides, and project assets
• docker/, services/, scripts/ — packaging and operations

License

Released under the MIT License.