Go-Tunnel User Guide

This documentation outlines the steps required to connect your local services to the internet using go-tunnel, covering server-side setup in the Web UI through running the client CLI.

1 Web UI Preparation (Server Side)

Before connecting your client CLI, you must set up your access and register your configurations on the server via the Web UI.

  • Register Subdomain: Use the Manage Domains section to manually register a subdomain, or let the system auto-generate one for you.
  • Create Configuration: Open Manage Configs and create a new configuration. Specify a Config Name, assign a Hostname (from Manage Domains), and define your Local Target (e.g., 127.0.0.1:8080).

Mode: http

Used for standard web applications. The gateway terminates SSL/TLS and forwards plain HTTP traffic to your local target.

Mode: https

Use when your local target manages its own SSL certificates. The gateway directly forwards encrypted HTTPS traffic to your target.

Mode: tcp

For non-HTTP services such as SSH (port 22) or databases. Forwards raw TCP data streams without protocol modification.

TCP Connection Example: If you expose local SSH (port 22), the server assigns a public port (e.g., gate.gotunnel.kristiawan.my.id:31234). Connect remotely using terminal: ssh user@gate.gotunnel.kristiawan.my.id -p 31234.

2 Authentication (Client Login)

Since configurations are now centrally managed on the server, you only need to authenticate once using the CLI client from your terminal.

$ gotunnel login

You will be prompted to enter your portal Username and Password. Upon success, an authentication token is securely saved on your local machine.

3 Access Token Authentication

Access Tokens (prefixed with gtk_) provide a way to authenticate the CLI client without interactive login. They are ideal for headless servers, CI/CD pipelines, and automated deployments where you cannot run gotunnel login interactively.

1

Creating an Access Token

  • Navigate to Access Tokens from the Web UI sidebar.
  • Click Create New Key.
  • Enter a descriptive Name and optionally set an Expiration Date.
  • Click Generate. Your new key (starting with gtk_) will be displayed.
2

Using the Access Token

Pass the key directly via the --token flag:

$ gotunnel run --token gtk_your_key_here my-config

Or set it as an environment variable:

$ export GOTUNNEL_TOKEN=gtk_your_key_here
$ gotunnel run my-config

Priority order: --token flag > GOTUNNEL_TOKEN environment variable > stored login credentials from gotunnel login.

3

Revoking Access Tokens

To revoke a key, go to Access Tokens in the Web UI and click the Revoke button next to the key you want to disable. Revoked keys are immediately rejected on the next connection attempt.

Important: Copy Your Key Immediately

The access token plaintext is shown only once at creation time. It is stored as a SHA-256 hash and cannot be retrieved later. If you lose the key, you must revoke it and create a new one.

4 Running the Tunnel

To view the list of configurations you created on the server, use the command gotunnel list. To start exposing your local service, execute the configuration name:

$ gotunnel run <config_name>

The client will download the port mappings from the server and automatically establish a secure tunnel connection. Once running, your local service is instantly accessible to the public!

5 Custom Domain Configuration

If you prefer to use your own custom top-level domain name (for example, yourcompany.com) instead of a subdomain, follow these steps:

1

DNS Configuration (CNAME)

Open your domain registrar or DNS management dashboard (such as Cloudflare, Namecheap, or GoDaddy) and add a CNAME record pointing your root domain directly to this tunnel server gateway.

Type Name / Host Target / Value Proxy Status TTL
CNAME @ (or yourcompany.com) gate.gotunnel.kristiawan.my.id DNS Only (No Proxy) Auto / 3600
Example Domain Configuration: If you own yourcompany.com, enter @ as the Name/Host field and gate.gotunnel.kristiawan.my.id as the Target CNAME value. If using Cloudflare, make sure Proxy status is set to DNS Only (Grey Cloud) initially so Let's Encrypt can successfully verify your domain and issue SSL certificates.
2

Register in Web UI Portal

Once DNS is configured, you must register the domain under the Manage Domains section of this portal to authorize tunneling.

  • Navigate to Manage Domains from the main sidebar.
  • Select Custom Domain type and enter your root domain name (e.g., yourcompany.com).
  • Click the Add Domain button.
3

Update Configuration in Web UI

Select your configuration in Manage Configs and add a new port mapping using your registered custom domain. Once saved, simply restart the tunnel in your terminal using gotunnel run <config_name>.

About Automatic SSL/TLS

The system automatically negotiates and generates free SSL/TLS certificates (Let's Encrypt) for your custom domain upon the first incoming request. Ensure your DNS records have fully propagated before accessing the domain.

6 CLI Commands Reference

Below is a quick reference table of all commands available in the gotunnel terminal client.

Command Description
gotunnel login Authenticate against the Web UI portal and save token credentials locally.
gotunnel list List all configurations registered under your account on the server.
gotunnel run <config> Start the secure tunnel and connect the local target to the public gateway.
gotunnel run -token <key> <config> Run tunnel using access token (headless/automated mode).
gotunnel logout Clear saved authentication credentials from your machine.
gotunnel update Check for updates and download the latest version of the client binary.
gotunnel uninstall Uninstall the gotunnel binary and remove local configuration directories.
gotunnel -v Print current client release version information.

7 Troubleshooting & FAQ

Common solutions and guidance for resolving connectivity or authentication issues.

Error: "connect: connection refused" on gotunnel run

This indicates that the gateway successfully routed traffic to your client, but your local application server (e.g., Node.js, Laravel, or Go server) is NOT currently running or listening on the configured target port. Double-check that your local service is active.

Error: "401 Unauthorized" or Session Expired

Your authentication JWT token may have expired or been revoked by an administrator. Simply run gotunnel logout followed by gotunnel login to re-authenticate and fetch a fresh session token.

Custom Domain SSL / HTTPS Not Working

When setting up a Custom Domain, DNS CNAME propagation across global nameservers can take several minutes up to a few hours. The automatic Let's Encrypt SSL certificate generation requires domain records to resolve correctly before the certificate issuance completes.