# aeroxy/tunnix architecture

> Architecture diagram of the GitHub repository aeroxy/tunnix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aeroxy/tunnix
- Repository: https://github.com/aeroxy/tunnix

## Overview

1. **What this repo is**
   - `tunnix` is a single Rust binary that runs in two major modes: `server` and `client`.
   - Its core job is to carry SOCKS5, HTTP proxy, remote shell, and file-transfer traffic through an HTTP/SSE tunnel, encrypted end-to-end.

2. **Top-level architecture**
   - The client sits next to local apps and exposes a local proxy port.
   - The server sits on the remote host and exposes HTTP endpoints.
   - Traffic flows: local app → client listener → encrypted tunnel over HTTP/SSE → server router → target TCP service.

3. **Client ingress boundary**
   - `proxy.rs` accepts incoming TCP connections on the local port and peeks the first byte to auto-detect protocol.
   - `socks5.rs` handles SOCKS5 CONNECT sessions.
   - `http_proxy.rs` handles HTTP proxying, including HTTP CONNECT and plain HTTP forwarding.
   - This means the client is the protocol adapter between local apps and the tunnel.

4. **Connection handling and multiplexing**
   - `relay.rs` is the bidirectional pipe between a local connection and a tunnel session.
   - It tracks connection IDs and lets many local connections share one tunnel transport.
   - The tunnel is session-based rather than one TCP socket per target connection.

5. **Tunnel transport**
   - `tunnel.rs` implements the client side of the HTTP/SSE transport.
   - The transport uses `POST /send/{session}` for encrypted binary payloads and `GET /stream/{session}` as an SSE event stream.
   - This design avoids WebSockets and works in environments that allow plain HTTP but block direct TCP.

6. **Server-side HTTP boundary**
   - `server.rs` is the remote HTTP server, built on `hyper`.
   - It strips optional path prefixes, routes session traffic, and exposes HTTP endpoints such as health checks.
   - It is the network-facing boundary on the remote host; everything past it is internal tunnel/session handling.

7. **Cryptography and shared wire format**
   - `crypto.rs` provides the end-to-end protection layer.
   - The repo uses Argon2id to derive keys from the shared password and ChaCha20-Poly1305 for authenticated encryption.
   - `protocol.rs` likely defines the framing/messages that both sides use inside the encrypted channel.

8. **Optional remote execution path**
   - `exec.rs` implements `remote-exec`, which is an opt-in shell/command execution channel over the same tunnel.
   - On the server side it requires explicit authorization via `--allow-exec`.
   - The PTY-based design matters architecturally: it is interactive, terminal-aware, and Unix-only.

9. **Optional file transfer path**
   - `transfer.rs` and `archive.rs` implement `push`/`pull`.
   - Files and directories are packed into tar archives, compressed with zstd, then sent through the encrypted tunnel.
   - This is a separate application-layer stream from proxy traffic, but it reuses the same auth and transport infrastructure.

10. **Configuration and hot reload**
   - `config.rs` loads CLI flags, config files, defaults, and environment-based password input.
   - `reload.rs` watches config changes and reloads selected fields without restart.
   - Hot-reloadable settings include password, headers, path prefix, and some response text; listener addresses and logging level require restart.

11. **Important integration boundaries**
   - The client boundary is “local app protocol termination” for SOCKS5 and HTTP proxy.
   - The server boundary is “HTTP ingress” and “remote TCP egress” to target services.
   - A reverse proxy or platform URL may sit in front of the server; `path_prefix` and custom headers exist specifically to survive those deployment constraints.

12. **Tests and operational packaging**
   - `tests/transfer_roundtrip.rs` validates the archive/transfer path.
   - `tests/reconnect_on_url_change.rs` covers tunnel resilience when the server URL changes.
   - The repo also includes a Homebrew formula and Cargo-based build/release tooling, indicating it is packaged as a deployable CLI binary rather than a library.

Main entry points: [`src/server.rs`](https://github.com/aeroxy/tunnix/blob/main/src/server.rs) (Server), [`src/main.rs`](https://github.com/aeroxy/tunnix/blob/main/src/main.rs) (Main), [`src/proxy.rs`](https://github.com/aeroxy/tunnix/blob/main/src/proxy.rs) (Local proxy), [`src/tunnel.rs`](https://github.com/aeroxy/tunnix/blob/main/src/tunnel.rs) (Tunnel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_client["Client side"]
  node_client_proxy["Local proxy<br/>listener<br/>[proxy.rs]"]
  node_socks5["SOCKS5<br/>proxy adapter<br/>[socks5.rs]"]
  node_http_proxy["HTTP proxy<br/>proxy adapter<br/>[http_proxy.rs]"]
  node_relay{{"Relay<br/>connection mux<br/>[relay.rs]"}}
  node_local_app[("Local apps<br/>client workload")]
end

subgraph group_group_transport["Tunnel core"]
  node_tunnel["Tunnel<br/>http/sse transport<br/>[tunnel.rs]"]
  node_protocol["Protocol<br/>wire framing<br/>[protocol.rs]"]
  node_crypto{{"Crypto<br/>encryption<br/>[crypto.rs]"}}
end

subgraph group_group_server["Server side"]
  node_server["Server<br/>http ingress<br/>[server.rs]"]
  node_exec["Remote exec<br/>pty command<br/>[exec.rs]"]
  node_transfer["Transfer<br/>file stream<br/>[transfer.rs]"]
  node_archive["Archive<br/>tar/zstd pack<br/>[archive.rs]"]
  node_proxy_target[("TCP target<br/>remote egress")]
  node_health(("Health<br/>endpoint"))
end

subgraph group_group_ops["Config and ops"]
  node_main["Main<br/>cli entry<br/>[main.rs]"]
  node_config["Config<br/>settings<br/>[config.rs]"]
  node_reload["Reload<br/>[reload.rs]"]
  node_formula["Formula<br/>packaging<br/>[tunnix.rb]"]
end

node_main -->|"loads"| node_config
node_main -->|"client mode"| node_client_proxy
node_main -->|"server mode"| node_server
node_main -->|"enables"| node_reload
node_client_proxy -->|"routes"| node_socks5
node_client_proxy -->|"routes"| node_http_proxy
node_client_proxy -->|"hands off"| node_relay
node_local_app -->|"connects to"| node_client_proxy
node_relay -->|"opens session"| node_tunnel
node_tunnel -->|"frames"| node_protocol
node_tunnel -->|"encrypts"| node_crypto
node_server -->|"decrypts"| node_crypto
node_server -->|"parses"| node_protocol
node_server -->|"forwards to"| node_proxy_target
node_server -->|"routes"| node_exec
node_server -->|"routes"| node_transfer
node_transfer -->|"packs"| node_archive
node_reload -->|"updates"| node_config
node_config -->|"configures"| node_server
node_config -->|"configures"| node_tunnel
node_formula -.->|"packages"| node_main
node_health -->|"served by"| node_server

click node_main "https://github.com/aeroxy/tunnix/blob/main/src/main.rs"
click node_config "https://github.com/aeroxy/tunnix/blob/main/src/config.rs"
click node_reload "https://github.com/aeroxy/tunnix/blob/main/src/reload.rs"
click node_client_proxy "https://github.com/aeroxy/tunnix/blob/main/src/proxy.rs"
click node_socks5 "https://github.com/aeroxy/tunnix/blob/main/src/socks5.rs"
click node_http_proxy "https://github.com/aeroxy/tunnix/blob/main/src/http_proxy.rs"
click node_relay "https://github.com/aeroxy/tunnix/blob/main/src/relay.rs"
click node_tunnel "https://github.com/aeroxy/tunnix/blob/main/src/tunnel.rs"
click node_protocol "https://github.com/aeroxy/tunnix/blob/main/src/protocol.rs"
click node_crypto "https://github.com/aeroxy/tunnix/blob/main/src/crypto.rs"
click node_server "https://github.com/aeroxy/tunnix/blob/main/src/server.rs"
click node_exec "https://github.com/aeroxy/tunnix/blob/main/src/exec.rs"
click node_transfer "https://github.com/aeroxy/tunnix/blob/main/src/transfer.rs"
click node_archive "https://github.com/aeroxy/tunnix/blob/main/src/archive.rs"
click node_formula "https://github.com/aeroxy/tunnix/blob/main/Formula/tunnix.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_proxy,node_socks5,node_http_proxy,node_relay,node_local_app toneBlue
class node_tunnel,node_protocol,node_crypto toneAmber
class node_server,node_exec,node_transfer,node_archive,node_proxy_target,node_health toneMint
class node_main,node_config,node_reload,node_formula toneRose
```

## Components

### Client side

Local protocol adapters and tunnel relay

- [Local proxy](https://github.com/aeroxy/tunnix/blob/main/src/proxy.rs): listener · Accepts local TCP connections and auto-detects protocol · `src/proxy.rs`
- [SOCKS5](https://github.com/aeroxy/tunnix/blob/main/src/socks5.rs): proxy adapter · Handles SOCKS5 CONNECT sessions · `src/socks5.rs`
- [HTTP proxy](https://github.com/aeroxy/tunnix/blob/main/src/http_proxy.rs): proxy adapter · Handles HTTP proxying and CONNECT forwarding · `src/http_proxy.rs`
- [Relay](https://github.com/aeroxy/tunnix/blob/main/src/relay.rs): connection mux · Bridges local sockets to shared tunnel sessions · `src/relay.rs`
- **Local apps**: client workload · Applications using SOCKS5 or HTTP proxy locally

### Tunnel core

Shared encrypted session and wire format

- [Tunnel](https://github.com/aeroxy/tunnix/blob/main/src/tunnel.rs): http/sse transport · Client-side encrypted POST and SSE stream transport · `src/tunnel.rs`
- [Protocol](https://github.com/aeroxy/tunnix/blob/main/src/protocol.rs): wire framing · Defines tunneled message framing and session messages · `src/protocol.rs`
- [Crypto](https://github.com/aeroxy/tunnix/blob/main/src/crypto.rs): encryption · Derives keys and encrypts payloads end to end · `src/crypto.rs`

### Server side

HTTP ingress and remote execution/transfer handlers

- [Server](https://github.com/aeroxy/tunnix/blob/main/src/server.rs): http ingress · HTTP boundary that routes sessions and endpoints · `src/server.rs`
- [Remote exec](https://github.com/aeroxy/tunnix/blob/main/src/exec.rs): pty command · Runs interactive shell sessions when explicitly allowed · `src/exec.rs`
- [Transfer](https://github.com/aeroxy/tunnix/blob/main/src/transfer.rs): file stream · Implements push and pull over the tunnel · `src/transfer.rs`
- [Archive](https://github.com/aeroxy/tunnix/blob/main/src/archive.rs): tar/zstd pack · Packs files and directories for transfer · `src/archive.rs`
- **TCP target**: remote egress · Destination services reached from the server side
- **Health**: endpoint · Operational HTTP check exposed by the server

### Config and ops

Runtime configuration, reload, and packaging

- [Main](https://github.com/aeroxy/tunnix/blob/main/src/main.rs): cli entry · Dispatches client or server mode and wires startup · `src/main.rs`
- [Config](https://github.com/aeroxy/tunnix/blob/main/src/config.rs): settings · Loads flags, files, env, and defaults · `src/config.rs`
- [Reload](https://github.com/aeroxy/tunnix/blob/main/src/reload.rs): hot reload · Watches config changes and updates selected runtime fields · `src/reload.rs`
- [Formula](https://github.com/aeroxy/tunnix/blob/main/Formula/tunnix.rb): packaging · Homebrew packaging for CLI distribution · `Formula/tunnix.rb`

## Connections

- Main → Config: loads · Startup configuration and runtime options
- Main → Local proxy: client mode · Starts local listener and tunnel client
- Main → Server: server mode · Starts remote HTTP ingress
- Main → Reload: enables · Optional hot reload of selected settings
- Local proxy → SOCKS5: routes · Dispatches SOCKS5 sessions
- Local proxy → HTTP proxy: routes · Dispatches HTTP proxy sessions
- Local proxy → Relay: hands off · Passes accepted connections into the shared relay
- Local apps → Local proxy: connects to · Local applications speak proxy protocols
- Relay → Tunnel: opens session · Multiplexes many local connections over one tunnel transport
- Tunnel → Protocol: frames · Encodes session messages into the shared wire format
- Tunnel → Crypto: encrypts · Protects all tunnel payloads end to end
- Server → Crypto: decrypts · Uses shared password-derived keys for ingress traffic
- Server → Protocol: parses · Understands the tunneled message framing
- Server → TCP target: forwards to · Connects remote sessions to target TCP services
- Server → Remote exec: routes · Hands exec sessions to the interactive PTY path
- Server → Transfer: routes · Hands file transfer sessions to the transfer path
- Transfer → Archive: packs · Archives and compresses payloads before sending
- Reload → Config: updates · Applies hot-reloadable configuration fields
- Config → Server: configures · Supplies headers, prefix, and server behavior
- Config → Tunnel: configures · Supplies password and transport settings
- Formula → Main: packages · Distribution packaging for the CLI binary
- Health → Server: served by · Operational endpoint on the HTTP boundary