Tunnel / Proxy

DBX can open connection layers for databases that are not directly reachable. Configure them from the connection dialog's Tunnel / Proxy tab.

Tunnels run where the DBX backend runs. On Desktop, local paths and temporary listeners belong to your computer. In Docker/Web, paths, network egress, and temporary listeners belong to the server or container, not the computer running the browser.

DBX supports three tunnel / proxy types:

Type	Use When
SSH tunnel	You have SSH access to a bastion host or database server.
Proxy	Your network requires SOCKS5 or HTTP CONNECT proxy access.
HTTP tunnel	Only a web server can reach the database, and SSH/VPN is not available.

For network databases, DBX opens a temporary port in its current runtime and points the database driver at that port. The tunnel / proxy layer forwards protocol bytes to the real target. A connection may combine multiple transport layers, which DBX establishes in the order shown in the connection dialog.

Per-Connection and Shared Profiles

Configure a layer directly under a connection's Tunnel / Proxy tab, or create reusable profiles under Settings → Tunnels:

Shared profiles support SSH, SOCKS5 / HTTP CONNECT proxies, and HTTP tunnels.
Multiple database connections can reference the same profile.
Editing a profile changes every referencing connection the next time it connects.
The SSH test verifies reachability and authentication. The proxy test performs a proxy handshake and may use an optional target host:port.
HTTP tunnels open lazily only when real target traffic starts, so there is no standalone HTTP-tunnel profile test.

Detach a profile from an individual connection when that connection needs different credentials or a custom layer order.

SSH Tunnel

SSH tunnels are built in. You do not need to create a manual terminal port forward.

Field	Description
SSH Host	Hostname or IP of the SSH server
SSH Port	Port for SSH (default: 22)
SSH User	Username for SSH authentication
Connect Timeout	Maximum time DBX waits while opening the SSH connection; default is 5 seconds

Enter a private key file that the DBX backend can read, for example ~/.ssh/id_rsa or ~/.ssh/id_ed25519:

Key Path — Desktop can browse local files. Web requires a server- or container-side path entered manually.
Key Passphrase — Enter the passphrase if your key is encrypted.

Key authentication is more secure than password authentication.

Use a private key as the primary credential with password as a fallback. DBX tries key authentication first; if the server rejects the key and continues to offer password authentication, it automatically falls back to password authentication.

Key Path — Browse and select your key file.
Key Passphrase — Enter the passphrase if your key is encrypted.
Password — Enter your SSH password as a fallback.

This is useful when a key may be temporarily revoked or when different hops in a multi-hop tunnel require different methods.

Enter your SSH password directly. This works on servers that allow password authentication.

Uses only SSH none authentication and sends no password or private key. This is intended for SSH proxies or special gateways that explicitly allow credential-free login. A rejection does not fall back to another method.

Host-Key Verification

DBX verifies the SSH host key before it sends a credential. Trusted keys come from the system known_hosts files and DBX's own known_hosts under the data directory:

An unknown host prompts you to review and explicitly accept its fingerprint.
You can trust it for the current connection only or remember it in DBX's known_hosts.
DBX rejects a changed key for a previously known host.
If the confirmation UI is unavailable, times out, or rejects the key, the connection fails without sending a password or private key.

Expose Tunnel to LAN

LAN exposure changes the SSH listener from 127.0.0.1 to 0.0.0.0. This expands the attack surface of the DBX runtime and should only be used on trusted networks with appropriate firewall rules.

On Desktop, this may make the temporary port reachable through your computer. In Docker/Web, the listener is inside the server or container; external reachability still depends on published ports, container networking, and the host firewall.

Proxy

Use a proxy layer when your environment requires an outbound proxy instead of SSH.

DBX supports:

SOCKS5 proxy
HTTP CONNECT proxy
Optional proxy username and password

A shared proxy profile may include an optional test target such as mysql.internal:3306. Without one, the test verifies only the proxy endpoint and credentials. Use the database connection test to verify the complete route.

HTTP Tunnel

The feature is an HTTP tunnel. The script currently provided by DBX is dbx_tunnel.php, so the deployment artifact is PHP-specific, but the connection type in DBX is HTTP tunnel.

Use HTTP tunnel when the database is inside a private network, but a web server in that network can reach it. This matches environments where only HTTP/HTTPS is available and SSH tunnel permissions are too broad or unavailable.

Deploy The Script

Upload deploy/dbx_tunnel.php to a PHP web server that can reach the database.

Configure these environment variables on the PHP server:

Variable	Required	Description
`DBX_TUNNEL_TOKEN`	Yes	Shared token. Enter the same value in DBX.
`DBX_TUNNEL_ALLOWED_HOSTS`	No	Comma-separated target host allow-list. Strongly recommended.
`DBX_TUNNEL_DIR`	No	Session queue directory. Defaults to a temp directory.
`DBX_TUNNEL_MAX_SESSION_SECONDS`	No	Maximum session lifetime. Defaults to `3600`.
`DBX_TUNNEL_PHP`	No	PHP CLI path used when PHP-FPM `fastcgi_finish_request` is not available.

In DBX, add an HTTP Tunnel layer and fill:

Field	Description
Tunnel Script URL	URL of `dbx_tunnel.php`, for example `https://example.com/dbx_tunnel.php`
Tunnel Token	Value of `DBX_TUNNEL_TOKEN`
Tunnel Timeout	Timeout for opening the HTTP tunnel and target database connection

The database host and port should be the address as seen from the PHP server, not necessarily the address as seen from your laptop.

HTTP Tunnel Flow

DBX database driver
  -> 127.0.0.1:<local temporary port>
  -> DBX HTTP tunnel client
  -> HTTP POST requests
  -> dbx_tunnel.php on the web server
  -> TCP connection from PHP to the private database
  -> database

The request protocol is short HTTP polling:

DBX starts a TCP listener in its current runtime.
The database driver connects to that local port.
DBX sends open to dbx_tunnel.php with a session id, target host, target port, and connect timeout.
The PHP script validates the token and allow-list, then starts a worker that opens a TCP socket to the database.
Bytes from the database driver are sent to the script with write.
DBX polls the script with read; response bytes are written back to the local database driver connection.
When the connection ends, DBX sends close and the PHP worker closes the database socket.

This does not require DBX Web and does not use WebSocket.

Security And Limits

Use HTTPS for the script URL.
Set a long random DBX_TUNNEL_TOKEN.
Set DBX_TUNNEL_ALLOWED_HOSTS so the script cannot become a general internal TCP relay.
Restrict public access to the script path where possible.
HTTP tunnel is convenient, but it is usually slower than direct TCP, VPN, or SSH because it forwards bytes through HTTP polling and a server-side queue.
If combined with other layers, HTTP tunnel must be the first tunnel / proxy layer because it is the outermost network boundary.
The script can reach target hosts from the private network. Deploy and operate it with the least-exposure and credential guidance under Production Safety.

File Databases

SQLite and Access connections are file-based and do not use tunnel / proxy layers. DuckDB usually uses a local file as well, so only configure tunnel / proxy layers when the selected driver profile uses a network endpoint.

An Oracle TNS descriptor may contain multiple failover addresses. DBX does not rewrite that descriptor through one temporary endpoint, so TNS mode cannot be combined with SSH, proxy, or HTTP tunnel layers. Use Service Name or SID mode when a tunnel is required.