tunnelto

To host your own tunnelto server:

1. Compile the server for the musl target (a musl_build.sh script is available in the repo for Docker-based builds).
2. Use the provided Dockerfile to create an Alpine-based image containing the server binary.
3. Deploy the image to your preferred environment.

Note on Scaling: The current implementation does not support multiple running servers with centralized coordination. If you deploy multiple instances, clients must connect to the same instance that handles the remote TCP stream. The official tunnelto.dev version uses Fly.io's Private Networking to manage a distributed system via a gossip mechanism.

To expose a local web server running on port 8000 to a public URL, run the following command:

tunnelto --port 8000

To test the full tunnel lifecycle locally, run the server, then a client, and then make a request.

1. Run the Server: Expects TCP traffic on 8080 and control websockets on 5000.

   ALLOWED_HOSTS="localhost" cargo run --bin tunnelto_server

2. Run the Client: Connects to your local server.

   CTRL_HOST="localhost" CTRL_PORT=5000 CTRL_TLS_OFF=1 cargo run --bin tunnelto -- -p 8000

3. Test the Tunnel: Use curl to hit the local server port using the subdomain header.

   curl -H '<subdomain>.localhost' "http://localhost:8080/some_path?with=somequery"

The server uses a Config object initialized via Config::from_env(). While the specific environment variable names are defined in the config module (not fully visible in this file), the server relies on the following configuration keys to determine its operational ports and observability settings:

• control_port: The port used by the control server.
• internal_network_port: The port used by the network service.
• remote_port: The port the server listens on for incoming remote connections.
• honeycomb_api_key: If provided, the server enables observability via Honeycomb using the t2-service dataset.

Use the following flags and options to customize your tunnel connection:

• -p, --port <port>: Sets the port to forward incoming tunnel traffic to.
• --host <local-host>: Sets the HOST (e.g., localhost) to forward incoming traffic to [default: localhost].
• --scheme <scheme>: Sets the SCHEME (e.g., http or https) to forward incoming traffic to [default: http].
• -s, --subdomain <sub-domain>: Specifies a sub-domain for this tunnel.
• -k, --key <key>: Sets an API authentication key to use for this tunnel.
• --dashboard-address <dashboard-address>: Sets the address of the local introspection dashboard.
• -v, --verbose: Increases verbosity (can be used multiple times).
• -h, --help: Prints help information.
• -V, --version: Prints version information.

The tunnelto CLI includes the following subcommand:

• set-auth: Store the API Authentication key.

If your connection fails due to authentication issues, the CLI provides specific guidance:

• Missing Key: If no secret key is configured, it suggests using the --key option.
• Invalid Key: If a key is provided but rejected, it directs you to verify your key at https://dashboard.tunnelto.dev.

Common error types handled by the client include:

• Error::AuthenticationFailed
• Error::NoResponseFromServer
• Error::WebSocketError
• Error::Timeout