RedP2P.
Documentation / redp2p.c
Home GitHub
RedP2P / Documentation

redp2p.c.

A small C library and CLI for exposing local TCP and UDP services through direct peer-to-peer tunnels.

A temporary TCP index coordinates registration, lookup, candidate exchange, and UDP hole punching. Application traffic travels directly between peers.

C11TCP + UDPKCP over UDPOptional STUNNo traffic relay
RedP2P is the umbrella project. redp2p.c is the C library and CLI that provides its direct connectivity primitive.

Quick start

The shortest path from zero to a working TCP tunnel uses three processes: an index, a publisher, and a consumer.

01

Run the index

Start a small TCP coordination service reachable by both peers.

02

Publish

Register a local service and wait for incoming peer sessions.

03

Connect

Expose the remote service through a local port on the consumer.

# index
redp2p idx 9876

# publisher: expose local TCP port 8080
redp2p pub web@idx.example.com:9876 --tcp 8080

# consumer: expose it locally on TCP port 9000
redp2p con web@idx.example.com:9876 --tcp 9000

Now a local connection to 127.0.0.1:9000 is bridged to the publisher's local TCP service on port 8080.

Mental model

The index is coordination infrastructure, not a data plane. It helps two peers discover enough information to establish a direct UDP path, then application traffic stays between those peers.

INDEXTCP coordination PUBLISHERlocal serviceCONSUMERlocal bridge registration · lookup · candidates DIRECT UDP PATHTCP mode: KCP · UDP mode: datagrams

Run an index

The index uses TCP and stores only temporary coordination state.

redp2p idx 9876

Publisher seats

redp2p idx 9876 --seats 128

Proof-of-work registration cost

redp2p idx 9876 --pow 20

Publish a service

TCP:

redp2p pub web@idx.example.com:9876 --tcp 8080

UDP:

redp2p pub game@idx.example.com:9876 --udp 7777

The identifier before @ is an arbitrary service label registered in the selected index. IDs may contain ASCII letters and digits.

Connect to a service

Expose a remote TCP service on a local port:

redp2p con web@idx.example.com:9876 --tcp 9000

Expose a remote UDP service:

redp2p con game@idx.example.com:9876 --udp 9000

Optional STUN

redp2p pub web@idx.example.com:9876 --tcp 8080 \
  --stun stun:stun.cloudflare.com:3478

STUN discovers an externally visible endpoint. It does not relay application traffic and is not part of an established tunnel.

CLI reference

Command / flagDescription
idx <port>Start an index server.
idx <port> --seats <N>Set total publisher seats.
idx <port> --pow <N>Set publisher registration proof-of-work cost.
idx <port> --listList active publisher IDs from the local index.
idx <port> -lAlias for --list.
pub <id>@<index[:port]> --tcp <port>Publish a local TCP service.
pub <id>@<index[:port]> --udp <port>Publish a local UDP service.
con <id>@<index[:port]> --tcp <port>Expose a remote TCP service locally.
con <id>@<index[:port]> --udp <port>Expose a remote UDP service locally.
del <id>@<index[:port]>Remove a published service.
--sweep <N>Set the bounded UDP port sweep range.
--stun <url>Enable optional STUN endpoint discovery.
-h, --helpShow help and usage.
-v, --versionShow build version.

Public API

The public C API lives in libredp2p.h. Reusable behavior is implemented in the single src/libredp2p.c compilation unit.

#include "libredp2p.h"

redp2p_t *ctx = NULL;
if (redp2p_open(&ctx) == REDP2P_OK) {
    redp2p_set_protocol(ctx, REDP2P_PROTO_TCP);
    redp2p_set_port(ctx, 8080);
    redp2p_wait(ctx, "idx.example.com", 9876, "web", 0);
    redp2p_close(ctx);
}
redp2p_open()

Allocate a caller-owned context.

redp2p_serve_index()

Run an index server.

redp2p_wait()

Publish a local service and accept peer sessions.

redp2p_connect()

Expose a remote service through a local bridge.

redp2p_deregister()

Remove one published service.

redp2p_list_publishers()

List active publisher IDs.

redp2p_stop()

Request termination of a blocking operation.

redp2p_close()

Release the context and associated resources.

Lifecycle

  • redp2p_options_default() returns initialized runtime options.
  • redp2p_options_load_env() loads supported environment values.
  • redp2p_options_free() releases option-owned allocations.
  • redp2p_open() creates the context.
  • A blocking role runs with serve_index, wait, or connect.
  • redp2p_stop() requests termination.
  • redp2p_close() releases the context.

Configuration

CLI flags override environment variables, which override built-in defaults.

REDP2P_PASS
REDP2P_VIP
REDP2P_POW
REDP2P_SEATS
REDP2P_SWEEP
REDP2P_STUN

REDP2P_PASS, REDP2P_VIP, and proof-of-work protect publisher registration and index capacity. They are not application authentication or peer identity.

Architecture

RedP2P separates coordination from application transport.

INDEX

Coordinates

Registration, lookup, listing, candidates, punching, temporary state.

PEERS

Transport

Application traffic travels directly between peers through UDP.

APP

Owns policy

Authentication, authorization, encryption, persistence and business rules stay outside.

The index does not relay application payloads. Failure to establish a direct path is an accepted operational result.

Transport

TCP mode

The local application talks TCP to redp2p.c. The peer-to-peer path uses vendored KCP over UDP for ordering, acknowledgements, retransmission, congestion/window state and stream reconstruction.

UDP mode

UDP datagrams are transported directly and datagram boundaries are preserved. redp2p.c does not add ordering, retransmission, duplication suppression guarantees, or fragmentation of oversized application datagrams.

Security boundary

redp2p.c transports application traffic without defining the application's security model.

  • Peer authentication belongs to the application protocol.
  • User authentication and authorization belong to the application.
  • Confidentiality and payload integrity belong to the transported protocol.
  • SSH, HTTPS, TLS-enabled services, and application-specific secure protocols can run through RedP2P directly.
Registration protection is not application security. Index passwords, VIP reservations and proof-of-work control publisher registration and capacity.

Scope & limits

RedP2P is deliberately small. It is not an enterprise network platform or a universal NAT traversal system.

Inside redp2p.cOutside redp2p.c
Peer coordinationUser accounts
Direct TCP/UDP tunnelingApplication authorization
Candidate exchangeApplication encryption
UDP hole punchingPermanent network database
Optional STUN discoveryTURN-style traffic relay
Temporary index stateTelemetry, billing, fleet management

Build & test

# current host
make

# tests
make test

# clean rebuild
make clean && make

Build artifacts are generated under bin/{arch}/{platform}/. Tests link dynamically against the generated shared library and run through CTest.

Platforms

The implementation targets portable C11. Supported build targets include Linux, Windows, macOS, iOS, Android, and multiple CPU architectures. Cross-compilation does not imply equal runtime validation on every target.

make all
make x86_64/linux
make x86_64/windows
make x86_64/macos
make aarch64/linux
make aarch64/android
make armv7/linux
make riscv64/linux
make powerpc64le/linux
make s390x/linux
Beta. The project is tested primarily on Debian x86_64 and is intended for independently operated, small-scale systems.