#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 PTY replay tail in memory for reconnect catch-up. The default is 4 MiB, and it can be configured in tun-poc/config.json under the per-user config directory:

macOS: ~/Library/Application Support/tun-poc/config.json
Linux: ${XDG_CONFIG_HOME:-~/.config}/tun-poc/config.json
Windows: %LOCALAPPDATA%/tun-poc/config.json

{
  "history_size": "4MiB",
  "renderer": "ghostty"
}

history_size accepts strings with B, KiB, or MiB, and bare JSON numbers are interpreted as bytes. renderer accepts tee or ghostty; --render and TUN_POC_RENDERER override the config file. 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

The PTY is spawned at a fixed 80x24 grid (see server/internal/app/bridge.mbt). The foreground local terminal is rendered by server/terminal/, a concrete package backed by the vendored MoonBit Ghostty port.

When the bridge starts, server/terminal enters the launching host terminal's alternate screen, enables SGR mouse reporting, feeds PTY output through the vendored Ghostty port, and repaints the fixed 80x24 viewport itself. The host primary-screen scrollback is not used for the local UI; mouse wheel events adjust server-owned scrollback. host_teardown disables mouse reporting and leaves the host alternate screen before termios is restored. During setup the server also sends OSC 10/11/12 queries to probe the host foreground, background, and cursor colors; matching host replies are consumed from stdin and installed as Ghostty default colors before normal input and mouse routing continues.

The rest of server/ talks only to the small @terminal facade: new, pty_to_host, host_to_pty, host_setup, and host_teardown. PTY query replies generated by Ghostty flow back through pty_reader, which writes them to the PTY master.

Source Files

main.mbt

Site source Report issue Packages Build queue Skills Statistics