Skip to content
AccessVault Docs

SSH Tunneling

Many production databases aren’t reachable directly — they sit in a private network behind an SSH bastion (jump host). AccessVault can open an SSH tunnel for you, equivalent to ssh -L, and route the database connection through it. The tunnel runs in-process (pure Rust); no external ssh binary is involved.

Enable the tunnel

In the connection form, tick Use SSH tunnel. The expanded section notes the key mental model: the Host and Port at the top of the form now refer to the database as seen from the bastion (often a private IP or internal hostname), while the SSH fields describe the bastion itself.

Fill in:

  • SSH Host — the bastion, e.g. bastion.example.com.
  • SSH Port — defaults to 22.
  • SSH Username
  • Auth method — Password or Public key.

Password vs key authentication

  • Password — enter it in the SSH Password field. Like database passwords, it’s stored in the macOS Keychain.
  • Public key — set Private key path (e.g. ~/.ssh/id_ed25519; ~ is expanded, and a Browse button opens a file picker). If the key is encrypted, enter its Passphrase — leave it blank for unencrypted keys.

There is no ssh-agent support yet — AccessVault reads the key file directly.

Test Connection exercises the full path and reports the SSH step separately, so you can tell a bastion failure from a database failure.

Keepalives and reconnection

  • Keepalive: the tunnel sends a keepalive every 30 seconds by default; after 3 missed keepalives (≈90 seconds) the tunnel is considered dead.
  • Auto-reconnect: a dropped tunnel is rebuilt automatically on your next query or command — same local port, with credentials re-resolved from the Keychain (so a rotated SSH password is picked up). You’ll see a toast in the app, and the reconnect is recorded in the audit log as a builtin:ssh_reconnect entry.

Note the reconnect is demand-driven, not a continuous background self-healer: if the tunnel drops while you’re idle, nothing happens until something next needs the connection.

Host keys — an honest caveat

The current beta does not verify SSH host keys: every host key is accepted (a warning is logged). This means the tunnel does not yet protect against an active machine-in-the-middle on the SSH connection. Host-key verification (known_hosts) is planned. If this matters for your threat model, restrict the network path to the bastion by other means until it ships.

Troubleshooting

Tunnel keeps dropping, or the port seems stuck? See Troubleshooting.