Tunnel / Proxy
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 local port in its current runtime (a random one by default, or a fixed one for an SSH layer) 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 |
| Local Port | Optional fixed port the tunnel listens on; empty uses a random free port |
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. - A changed key for a host already saved in DBX's
known_hostsprompts you to compare fingerprints. You can close, continue for this session only, or update the saved key and continue. DBX never edits~/.ssh/known_hosts; a mismatch there still fails closed. - 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
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.
Fixed Local Port
By default, DBX picks a random free local port for the SSH tunnel. Set Local Port (1-65535) to make the tunnel listen on a port you choose instead, for example 4059. Other local tools, such as psql or a script, can then connect through the same tunnel at 127.0.0.1:4059.
- The port is held only while the connection is open in DBX. It is released when the connection is closed.
- Only the last enabled layer can use it, and only when that layer is an SSH layer configured directly on the connection. A layer that references a shared profile from Settings → Tunnels has no Local Port field. Setting Local Port on an earlier layer fails with an error.
- If the port is already in use or cannot be bound, connecting fails with a message that asks you to close the other program or choose another port.
- The connection Test button, Test SSH tunnel, the production-database picker and other one-time drafts, scheduled backups, and a standalone stdio MCP server or the CLI use a random port, so they do not collide with a connection that is already open. Kafka with a single
127.0.0.1bootstrap server is the exception described below. - A host alias from
~/.ssh/configthat resolves to a multi-hopProxyJumpchain does not support a fixed local port yet, and connecting returns an error. Add the jump host as its own first layer and point the last layer at the target's realHostNameor at an alias withoutProxyJump, or leave Local Port empty. - RabbitMQ uses the fixed port for the AMQP connection. The management API tunnel keeps a random port.
- Kafka with a single
127.0.0.1bootstrap server always listens on the bootstrap port. Leave Local Port empty or set it to that port; a different port returns an error. - Local Port is not supported for SQLite over SSH, ClickHouse, Turso, RocketMQ, Redis Cluster, Redis Sentinel, or plugin connections that route through SOCKS5 (
proxy_route), because they connect through a remote worker, a SOCKS5 route, or per-node tunnels instead of one local tunnel port. The connection dialog shows an error if it is set. If the setting arrives some other way, such as an import, cloud sync, or a hand-edited config, Test and connecting fail with an error instead of ignoring it. - The connection dialog has no tunnel settings for Cloudflare D1. An imported Cloudflare D1 config that has Local Port set fails when connecting; opening the connection in the dialog and saving it removes its tunnel settings.
- In Docker/Web, the fixed port is opened on the server or container, not on the computer running the browser.
0.0.0.0, so any device that can reach your machine on that port can use the tunnel. Use it only on trusted networks with appropriate firewall rules.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
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.
fastcgi_finish_request() or permission to spawn PHP CLI with popen(). CGI/FastCGI shared hosting with both capabilities unavailable cannot run this TCP tunnel; the script returns HTTP 503 with the reason. A SQL-level MySQL HTTP adapter is not provided.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 and popen() is allowed. |
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 TCP listener in its current runtime.
- 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.
- 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
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.
SQLite is also a file database. A local SQLite file still does not use a TCP tunnel. In the desktop app you can attach SSH hops to a SQLite connection to open a remote SQLite file on a Linux amd64/arm64 host. DBX then starts a short-lived worker on the final SSH hop and talks to that worker; it does not copy the .db to your laptop. The path field is an absolute path on that file host, not a local file picker.
The first Test or Connect that would upload the worker asks for consent and shows the destination path and digest. You can keep the worker for the session only (deleted when you disconnect), persist it under ~/.cache/dbx/sqlite-worker/<digest>, or point at a pre-placed binary. Desktop installs the SQLite SSH Worker from Driver Manager as one package with both Linux x64 and Linux ARM64 binaries, then uploads the one that matches the file host. SQLCipher, loadable extensions, and attached databases are not supported on that remote path in v1. Backup saves a SQLite snapshot to your laptop; restore uploads a local SQLite file and applies it on the file host.
Oracle TNS descriptors 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.
Create a Connection
Configure the database profile, tunnel / proxy layers, SSL, and connection color together.
Database Support
Check which database profiles are file-based, native, compatibility-based, or plugin-backed.
Production Safety
Plan least privilege, network exposure, read-only protection, and production writes.