Protocol handbook

Technical documentation.

A practical guide to setup, forwarding, troubleshooting, limits, and the security model.

3-minute guide

Quick start

Start localhost

Run your local web app.

Choose an agent

Choose the Web, Windows, or Python agent.

Run and enter details

Open the client and answer its prompts.

Native client

webtnx.exe
# or
python3 webtnx.py

No command-line parameters are required.

01

What is WebTNX?

WebTNX is a lightweight path-based HTTP relay.

02

Why build this instead of a traditional tunnel?

WebTNX is optimized for temporary HTTP sharing on constrained infrastructure.

03

Local hosting & proxy capability

Local hosting is your localhost app; proxy capability is recreating HTTP requests there.

04

Suitability matrix

✓
Best forLocal demos and short-lived previews.
!
Not the best fitHigh-risk or streaming production workloads.
05

The complete HTTP envelope & asset paths

WebTNX forwards the complete safe HTTP envelope.

Static same-site asset paths receive the active Tunnel ID automatically.

Hop-by-hop headers are regenerated; native clients provide better header fidelity.

06

Active defense & troubleshooting

502 — Local service offline

Confirm the app and port.

CORS blocked — Web Agent only

Allow the site origin; native clients do not need CORS.

Access-Control-Allow-Origin: https://webtnx.nxlabtw.com
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

504 — Gateway timeout

The local response took too long.

Static asset path rewriting

WebTNX automatically prefixes statically identifiable same-site assets with your Tunnel ID.

413 — Payload too large

Reduce the payload.

Polling warning or tunnel offline

Keep the agent running and reconnect expired sessions.

07

Authenticated payload encryption

Registration creates separate random token and AES keys.

The relay is trusted, so this is not claimed as end-to-end encryption.

08

Service limits

  • Maximum request body: 2 MB.
  • Queue limits protect the process.
  • Timeout range: 5–120 seconds.
  • No streaming protocols.
  • Restarts end active tunnels.
09

Service availability and disclaimer

!
No continuity or compensation guaranteeWebTNX may be discontinued without compensation.
10

Frequently asked questions

WebTNX adds the Tunnel ID automatically.

TLS and AES-256-GCM protect traffic.

It keeps deployment simple.

Browsers enforce same-origin policy.

Use a different ID for each.

It protects small servers.

Wait for the old session to expire.

Short non-streaming calls can work.

Usually, with the same CORS requirements.

No; active state is in memory.

Keep the process alive with a process manager.

It disappears only after a successful check.