Tunnel / Proxy
Connect to private databases through SSH tunnels, HTTP tunnels, SOCKS5 proxies, or HTTP proxies.
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 local port and points the database driver at that port. The tunnel / proxy layer then forwards the database protocol bytes to the real target.
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 |
Select a private key file (for example ~/.ssh/id_rsa or ~/.ssh/id_ed25519):
- Key Path — Browse and select your key file.
- Key Passphrase — Enter the passphrase if your key is encrypted.
Key authentication is more secure than password authentication.
Enter your SSH password directly. This works on servers that allow password authentication.
Expose Tunnel to LAN
By default, the SSH tunnel listens on localhost only. Enable LAN exposure to bind to 0.0.0.0, which is useful for temporary team sharing or multi-device access.
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
HTTP Tunnel
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
-> databaseThe request protocol is short HTTP polling:
- DBX starts a local TCP listener.
- The database driver connects to that local port.
- DBX sends
opentodbx_tunnel.phpwith 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
closeand 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_HOSTSso 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.
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.