#tun-poc-server

The server agent for tun-poc. Runs on the machine you want to expose, opens a single outbound WebSocket to a relay, and spawns a PTY per incoming session so clients get a real shell.

No inbound ports are required — it works behind home routers, corporate firewalls, and carrier-grade NATs.

Responsibilities:

Register with the relay and accept sessions keyed by ServerId.
Fork a PTY per session (pty/, tty/) and stream I/O both ways.
Keep the local shell alive across relay disconnects and reattach on reconnect.
Resolve XDG paths for scoped credential storage (xdg/).

#Run

# connect to the hosted relay
moon run server --target native

# connect to the China-hosted relay
moon run server-cn --target native

# expose a specific program instead of the default shell
moon run server --target native -- /bin/bash
moon run server --target native -- -- htop

# point at a self-hosted relay
moon run server --target native -- --relay your.relay.example.com

The agent prints the ServerId it registered under — keep the process running for the session to stay reachable.

#Build And Publish Artifacts

Server release binaries are built from the repo root:

make build-server
make build-server-linux

The outputs are written under downloads/ as tun-server-<platform> files with .sha256 sidecars. The current manual publishing workflow bundles those files into the relay image. See ../docs/publishing.md for the current steps and ../docs/plans/2026-04-27-structured-publishing-workflow.md for the plan to publish server binaries independently.

The server keeps a fixed 4 MiB PTY replay tail in memory for reconnect catch-up. That replay is a bounded byte suffix, not a terminal snapshot: once the tail trims, a fresh client or a client reconnecting with an older cursor can receive output from the middle of the PTY stream and cannot rely on replay alone to reconstruct the full screen state.

#Terminal backend — virtual package

The PTY is spawned at a fixed 80×24 grid (see bridge.mbt). The server's local stdout goes through a @terminal virtual package (server/terminal/) so the rendering backend stays a build-time choice, not a runtime one.

The current default implementation is server/terminal/default.mbt: raw passthrough. PTY bytes are written straight to host stdout, host stdin is forwarded straight to the PTY, and shell queries (DSR/DA1/...) are handled by the host terminal's own stdin-to-PTY loop.

#Adding another backend

Create server/terminal_<name>/ with moon.pkg declaring options(implement: "tonyfettes/tun-poc-server/terminal") and any deps that backend needs.
Provide pub fn new() -> Terminal raise, pub fn pty_to_host(Bytes, Terminal) -> Array[Bytes], pub fn host_to_pty(Bytes, Terminal) -> Bytes, pub fn host_setup(Terminal) -> Unit, and pub fn host_teardown(Terminal) -> Unit to match server/terminal/pkg.mbti.
Add that package to overrides in server/moon.pkg to select it at build time.

No change is needed in the rest of server/ library code. server/bridge.mbt and server/bridge_state.mbt already talk only to the virtual @terminal interface.

Source Files

main.mbt

Site source Report issue Packages Build queue Skills Statistics