DEV Community: buhuipao

Reaching your own LAN without port forwarding, public URLs, or a VPN concentrator

buhuipao — Sat, 05 Sep 2026 05:23:47 +0000

Disclosure: I maintain Lantunnel. It is Apache-2.0 and the source is linked at the end.

Every self-hoster hits the same wall. The NAS is at home. The GPU box is at the office. Ollama is on the desktop you walked away from. All of them sit behind NAT, and none of them belong on the public internet.

The usual answers all ask you to give something up. Port forwarding puts a service on the open internet and hopes the auth holds. A public tunnel URL does the same thing with nicer branding. A classic VPN concentrator works, but now every byte between two machines in your own house takes a detour through a box you rent.

Lantunnel is my attempt at a fourth option: a small private mesh where peers talk directly whenever the network allows it, and where the fallback path still cannot read your traffic.

The shape of the system

There are three binaries, and that is the whole thing.

lantunnel-client runs on every device that joins. It imports one signed .peer profile, attaches to the Gateway, and exposes a loopback SOCKS5 proxy on 127.0.0.1:1080 plus optional native routes. Ordinary apps reach the tunnel without knowing it exists.

lantunnel-gateway is a rendezvous point and NAT-traversal signaler. It holds a tunnel's public .scope file, helps two peers punch a direct path, and relays sealed bytes when they cannot. It never holds peer private keys and never sees plaintext.

lantunnel-admin creates the tunnel offline. init-tunnel makes the owner file and the Gateway's public scope; add-peer issues one signed profile per device. It talks to nothing — no account, no callback, no network at all.

Direct first, relay only when the network refuses

New flows try a direct peer-to-peer QUIC path with UDP hole punching. Relay is the fallback, not the default. When two machines are on networks that can be punched through, the Gateway drops out of the data path entirely and the traffic is a straight line between the two peers.

When hole punching fails — symmetric NAT, hostile carrier, corporate egress — the flow falls back to the Gateway. This is where the design has to earn trust, because a relay is exactly the component that could betray you.

Relayed payloads are sealed with XChaCha20-Poly1305 under keys derived from an X25519 exchange between the two peers. The Gateway forwards bytes it cannot decrypt. It is a dumb pipe by construction, not by policy.

Identity is signed, not shared

There is no tunnel password, no group secret, no bearer token to leak into a wiki page.

Every peer holds its own Ed25519 key, proves possession of it on every attachment, and that key never leaves the machine that generated it. One profile per device — a .peer is not meant to be copied around. Revoking a laptop means revoking a laptop, not rotating a shared credential across every device you own.

The access-control list lives on the target machine too. Each client decides what it will serve. Policy sits on the box holding the data, never on the Gateway and never on someone else's server.

Whole-LAN reach, not per-service holes

A peer can export the private subnets it sits on. One client on the home network makes the NAS, the printer, and the dashboard reachable to the rest of the tunnel — without an inbound firewall rule, a public IP, or a hostname anywhere.

In practice people use it for game and media streaming (Sunshine/Moonlight, Jellyfin, Plex), private AI and dev tooling (Ollama, Open WebUI, an internal API, a staging box, a database that must never leave the LAN), and ordinary home-office plumbing (NAS, Home Assistant, cameras, SSH).

Self-hosting the Gateway

If you would rather not depend on anyone, the Gateway is in the repository, it is Apache-2.0, and it is not metered.

# On the public Gateway host
lantunnel-gateway init --public-ip <PUBLIC_IP>

# On the trusted owner machine — the Gateway private key never leaves the Gateway host
lantunnel-admin init-tunnel \
  --gateway-transport quic \
  --gateway-ip <PUBLIC_IP> \
  --gateway-port 8443 \
  --gateway-mapping-port 8444 \
  --gateway-cert ./server.crt

lantunnel-admin add-peer --tunnel <tunnel-id>.tunnel --name laptop --output laptop.peer

# Back on the Gateway host: only the public scope moves
mkdir -p state/scopes.d && cp <tunnel-id>.scope state/scopes.d/
lantunnel-gateway --config configs/gateway.yaml --check-config
lantunnel-gateway --config configs/gateway.yaml

# On each device
lantunnel-client tunnel import ./laptop.peer
lantunnel-client            # desktop UI
lantunnel-client connect '<tunnel_id>'   # same runtime, headless

Note what crosses machine boundaries: the Gateway's public certificate goes out to the owner machine, and the public .scope comes back. The tunnel signing key and the Gateway private key each stay where they were generated.

Re-running init preserves the existing config, certificate, and key. At the same config path, a changed IP, transport, data port, or mapping port is refused rather than silently replacing the Gateway identity.

One binary, UI or headless

lantunnel-client opens a desktop window by default and runs the exact same runtime under --headless on a server. There is no separate daemon build and no second code path to keep honest. It runs on macOS, Windows, Linux, Android, and iOS.

If you do not want to run a Gateway

There is a hosted option at lantunnel.app — one permanent free tunnel per account, unlimited direct peer-to-peer traffic, unlimited LAN devices behind each client, and 5 GB/month of encrypted relay fallback for when direct fails. The self-hosted path in the repository stays fully supported and unmetered either way.

Where the details live

The repository has the architecture write-up in CONTEXT.md, the wire protocol in docs/PROTOCOL.md, and a full usage guide in docs/USAGE.md covering LAN exports, access rules, servers, mobile, and troubleshooting.

Source: github.com/lantunnel/lantunnel (Apache-2.0)

I would genuinely like to hear where the NAT traversal falls over for you — the hole-punching path is the part that benefits most from networks I do not have access to.

Why I built a control plane for Codex and Claude Code instead of another AI chat UI

buhuipao — Wed, 29 Jul 2026 02:58:49 +0000

Disclosure: this write-up was drafted with an LLM from my own notes, code,
and design decisions, then reviewed and published by me. The project, the
engineering calls described below, and the code excerpts are my own work on
agent-console.

When you have one coding agent, a terminal tab is a perfectly good interface.

When you have five or ten of them across several projects, the problem changes. You are no longer having one conversation. You are managing work in different states: one session is still running, one needs approval, one has failed, and another finished ten minutes ago in a tab hidden behind the rest.

I wanted to solve one specific problem: get a cross-session view without changing how Codex and Claude Code are used.

The boundary: do not rebuild the provider UI

Agent Console does not implement a unified chat frontend. It scans persisted provider sessions, groups them by workspace, reduces them to working, waiting, idle, and failed, and invokes the provider's own resume flow. Once inside a session you are still using the native Codex or Claude Code terminal UI.

This boundary matters. A unified frontend looks tidy, but it lags behind provider features and creates a second compatibility layer for resume behaviour, keybindings, approval flows, and rendering. The layer above the native UI — discovery, state, alerts, search, navigation — is small enough to keep correct.

The Rust side is deliberately boring: ratatui for rendering, portable-pty for child processes, vt100 for terminal emulation in retained panes, rusqlite for state, and no async runtime at all. The whole thing is one synchronous loop plus threads that own PTYs.

What I learned building it

1. Discovery is parsing someone else's private format

Neither provider offers an API for "list my sessions". Both persist transcripts, so discovery means reading ~/.codex/sessions/**/rollout-*.jsonl and ~/.claude/projects/**/<uuid>.jsonl and inferring structure from records that were never meant to be a public interface.

That is fine as an observation channel and terrible as a contract. Every provider release can move a field. The mitigation was to stop branching on the provider anywhere except one table:

pub struct ProviderAdapter {
    pub kind: AgentKind,
    /// True when this file is one of the provider's session transcripts.
    pub accepts: fn(&Path) -> bool,
    /// Parse one accepted transcript. `Ok(None)` means "not a usable session".
    pub parse: fn(&Path) -> io::Result<Option<Session>>,
    /// Optional enrichment applied to the provider's parsed sessions.
    pub enrich: Option<fn(&Path, &mut [Session])>,
}

Discovery then walks the table instead of matching on an enum in five places:

for adapter in providers::enabled() {
    let root = paths.root(adapter.kind);
    let files = provider_files(root, adapter.accepts);
    let mut parsed = parse_cached_files(files, adapter, cache);
    if let Some(enrich) = adapter.enrich {
        enrich(root, &mut parsed);
    }
    sessions.extend(parsed);
}

Plain fn pointers rather than Box<dyn Fn> keep the table a const, which means adding a provider is one entry and no allocation. AGENT_CONSOLE_PROVIDERS=codex narrows the same table at runtime — useful now that both vendors are shipping their own multi-session views and one side may become redundant.

The failure mode I cared about most: a typo in that variable must not silently produce an empty dashboard. An unrecognised value logs the reason and keeps every provider enabled.

2. Owning a PTY means deciding who dies with the TUI

The obvious design is to spawn agents from the TUI process. Then closing the dashboard kills every agent, which is exactly the behaviour that makes people keep twelve terminal tabs open instead.

So managed PTYs live in a separate long-lived daemon. Closing or crashing the TUI detaches; a new TUI reconnects and replays a bounded tail. No tmux dependency, and no forced git worktrees — sessions run in place.

Running in place means two dashboards could resume the same provider session and corrupt one transcript, so each provider session ID is guarded by a cross-process lease with owner information, safe refusal, and an explicit force-takeover. This is the part where Rust helped least and process hygiene helped most: the type system says nothing about a second process on the same machine.

3. Let the model summarise, not decide

working, waiting, and failed come from provider hook events and process state, reduced deterministically with a fixed precedence. A model is used only to compress a long conversation into a glanceable task summary, it runs through the session's own provider outside the coding conversation, and it can be turned off entirely with AGENT_CONSOLE_SUMMARIZER=off.

A related detail that only shows up in practice: an alert is a state transition observed while the runtime is live, not a state. A session that is already waiting when the dashboard starts is not news. Getting that distinction wrong makes the alert list useless within a day.

4. Terminal emulation is where the time goes

pty.rs is 6,600 lines — by far the largest module, and larger than discovery, state, and the whole UI combined. Retained scrollback per pane, mouse reporting for providers that request it, alternate-screen handling, selection and clipboard, resize, and reconnect replay each look small and are not.

Two concrete lessons. Managed Codex sessions run with --no-alt-screen so the workspace pane can retain and scroll the transcript in every state. And only three Ctrl chords are actually free once Codex and Claude Code have taken theirs — Ctrl-\, Ctrl-^, Ctrl-Q — so everything else has to be forwarded untouched to the child.

Current state

v0.0.12, supporting Codex and Claude Code, with packages for macOS, Linux, and Windows and signed/notarised macOS binaries.

cargo install agent-console
agent-console doctor   # checks providers, hooks, clipboard, daemon, permissions
agent-console

Licensed MIT OR Apache-2.0. Source: https://github.com/buhuipao/agent-console

It is still early. The questions I care about are more fundamental than adding ten provider logos: is the state trustworthy, do alerts actually reduce tab switching, do shells stay attached to the right workspace, and is native resume smooth enough?

If you run several coding agents every day — what should a cross-session control layer show you, and what should it never take over?