SSH tunneling

Connect Cocobox to databases that live in a private network through an SSH bastion.

Last updated May 1, 2026

If your database doesn’t accept connections from the public internet — and it shouldn’t — Cocobox can tunnel through an SSH bastion you control.

How it works

When you mark a connection as SSH-tunneled, Cocobox opens an SSH session to your bastion using the SSH credentials you provide, then forwards a local TCP port through that session to your database’s host:port. The DB connection then runs over the encrypted tunnel.

[Cocobox] ──TCP→ [Your bastion: 22 SSH] ──TCP→ [Your DB host: 3306/5432]

The bastion never sees your database password — only the encrypted MySQL/Postgres protocol bytes.

Configure

In the connection dialog, toggle Use SSH tunnel:

Field	Notes
SSH host	Public IP or DNS of your bastion.
SSH port	Default 22.
SSH user	The user we authenticate as.
SSH auth	`key` (paste a private key) or `password`. Keys recommended.
DB host	The hostname as seen from the bastion (often `127.0.0.1` or a private DNS name).
DB port	The port on that host the DB listens on.

Hardening the bastion

Recommended sshd_config for a Cocobox-only bastion user:

Match User cocobox
  PasswordAuthentication no
  PermitTTY no
  PermitTunnel no
  AllowAgentForwarding no
  AllowTcpForwarding yes
  ForceCommand /usr/sbin/nologin
  AllowStreamLocalForwarding no

Combined with a key-only login, this user can only forward TCP — never spawn a shell, never forward local-domain sockets.

For static egress IPs (so you can lock down the bastion’s firewall), enterprise plans include dedicated outbound IPs. Contact devs@cocobox.io.

Test & save

The Test connection button performs the full chain: SSH connect → forward → DB authenticate → SELECT 1 → tear down. Failures report which step broke. Save once it’s green.

Troubleshooting

SSH: Permission denied — wrong key, wrong user, or ~/.ssh/authorized_keys mode is too open.
SSH: Connection timed out — your bastion’s firewall is blocking Cocobox’s outbound IP. Allow the Cocobox CIDR ranges.
DB: ECONNREFUSED from inside the tunnel — the DB host/port from the bastion’s perspective is wrong.
Tunnel idle timeout — long-running queries on small bastions sometimes fall to the bastion’s idle timeout. Set ClientAliveInterval 60 on sshd.