DEV Community: Nexus Shell

Why ExitOnForwardFailure=yes does not prove your database is reachable

Nexus Shell — Thu, 17 Sep 2026 03:12:31 +0000

An SSH tunnel can be listening on your laptop while the service behind it is unavailable. ExitOnForwardFailure=yes is useful, but it does not turn the SSH process into a database health check.

This distinction matters when a PostgreSQL client says “connection failed” even though ssh -N is still running. Before changing credentials, separate the local listener, the SSH transport, the destination connection and the database protocol.

A small experiment, with measured results

On September 17, 2026, a loopback-only test ran on macOS with OpenSSH 10.3p1, Node.js 25.6.1 and ssh2 1.17.0. It used the system OpenSSH client, an in-process SSH server and a tiny HTTP target. It did not connect to a VPS or run PostgreSQL.

The client used local forwarding and ExitOnForwardFailure=yes. The SSH server attempted an actual TCP connection to a closed loopback port; the operating system returned ECONNREFUSED.

Change in the test	Observed result
Connect to the local forwarding port while the target is stopped	The local TCP connection succeeds; the target connection fails; the SSH process remains running
Start the HTTP target, keeping the same SSH process	A new request through the existing tunnel returns `fixture-ok`
Start a second SSH process with the same local listening port	The second process reports `Address already in use` and exits with code 255

The test asserts the process state and response body; these are not inferred from the presence of a terminal window.

The OpenSSH configuration manual describes this boundary: failure to establish a forwarding listener is different from a later failure to connect to its destination. Keep the option enabled, but test the service separately.

Map the addresses before changing anything

For a database reachable from an SSH gateway, an illustrative command is:

ssh -N -T -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:15432:db.internal:5432 \
  developer@gateway.example

Run it in a local terminal. Replace the example names with your own authorized connection details, verify the host key, and leave the process running.

Database client on the Mac
  -> 127.0.0.1:15432 on the Mac
  -> SSH connection to gateway.example
  -> db.internal:5432, reached from the gateway

The database client uses host 127.0.0.1 and port 15432. The gateway resolves and connects to db.internal. If the forwarding destination is instead 127.0.0.1:5432, that loopback address belongs to the SSH server's network context, not your Mac. OpenSSH's local-forwarding reference specifies where these connections originate.

Check the layer that actually failed

Evidence	What to investigate next
SSH cannot authenticate	SSH account, key selection and server authentication policy
`Address already in use` on the Mac	Another local listener; choose a different unused local port and update the database client
Local TCP connection succeeds, followed by a forwarding-channel error	Destination hostname, port, service listener, routing and forwarding policy on the SSH side
PostgreSQL reports an authentication error	The connection reached a PostgreSQL server; inspect database identity and authentication rules
TLS certificate verification fails	Database hostname and TLS configuration; do not disable verification to make the error disappear

A successful local TCP probe alone cannot verify a query, the database identity, or authentication. Use your normal database client with the database credentials and required TLS settings for the final check.

SSH authentication and database authentication are separate. If the gateway connects onward to another machine, the SSH encryption ends at the gateway; database TLS may still be required for the remaining hop. PostgreSQL documents this distinction in its SSH tunneling guide.

Reproduce the transport test

The complete test script and assertions are in this public Gist. Inspect it before running it. Save tunnel-lab.cjs into a fresh temporary directory, then run these commands from that directory:

npm install --ignore-scripts --omit=optional --no-audit --no-fund ssh2@1.17.0
node tunnel-lab.cjs

Expected output from the tested environment:

PASS: local TCP connect succeeded; target returned ECONNREFUSED; SSH remained running.
PASS: the same SSH process forwarded an HTTP response after the target started.
PASS: a second tunnel with the occupied local port exited 255.

The fixture binds only to 127.0.0.1, pins its generated host key in a temporary known-hosts file, and ignores your SSH configuration and authentication agent. It closes its child processes and removes that temporary host-key file afterward. The temporary package directory remains yours to remove.

The miniature server accepts authentication solely for this local experiment and permits forwarding to one fixed loopback destination. It offers no shell and is not a deployable SSH server. Do not expose it to a network. The test establishes TCP-forwarding behavior only; it does not test PostgreSQL authentication, TLS, a production OpenSSH server's policy or a desktop SSH application's implementation.

Disclosure: This report and its code were generated by Codex. Codex executed the local test and checked the technical explanation against the linked upstream documentation. It is an automated experiment report, not a claim of a human production incident.

Choosing an SFTP Workflow on Mac: CLI, Finder Mount, or Dual-Pane Client?

Nexus Shell — Tue, 18 Aug 2026 02:11:39 +0000

Moving a file to a Linux server from a Mac sounds like a one-command task. In practice, the right workflow depends on what happens around the transfer: whether you need repeatability, visual confirmation, remote editing, or a terminal open beside the files.

There are three sensible approaches. None is universally best.

1. Use the built-in `sftp` command

macOS already includes the OpenSSH SFTP client. For a quick transfer, the command line has the smallest setup cost:

sftp -i ~/.ssh/id_ed25519 deploy@example.com

Inside the session, put, get, ls, cd, and lcd cover the basics. It also supports jump hosts, alternate SSH config files, recursive transfers, resuming partial transfers, and batch mode.

The CLI is usually the right choice when:

the transfer belongs in a script or runbook;
you already know the exact remote path;
the same command should be repeatable in CI or from another machine;
you want the full behavior of your OpenSSH configuration.

Its weakness is not capability. It is context. When you are comparing several local and remote files, checking timestamps, or moving a group of items between changing directories, remembering which side of the session each path refers to becomes the work.

2. Mount the server as a drive

A mounted workflow makes the remote directory appear in Finder. This is useful when the remote files should behave like ordinary Mac files and several local apps need to open them.

Finder's built-in Connect to Server documentation lists SMB, NFS, FTP, and WebDAV, but not SFTP. An SFTP mount therefore needs an additional tool or filesystem layer.

A mount is a good fit when:

the remote directory should stay available for a long working session;
Finder, an IDE, and other apps all need access to the same files;
browsing is more important than seeing individual transfer jobs;
the connection is stable enough to behave like a filesystem.

The trade-off is that network failure now appears as filesystem behavior. Sleep, reconnects, caching, and partial writes deserve more attention than they do in an explicit upload/download workflow. For production configuration files, it is worth confirming how the mount handles interrupted saves and conflicts before relying on it.

3. Use a dual-pane SFTP client

A dual-pane client keeps the local and remote directories visible at the same time. Transfers remain explicit jobs instead of being hidden behind filesystem operations.

This model works well when:

you regularly move groups of files between a project folder and a server;
you want visible progress, cancellation, and conflict handling;
remote editing needs to upload the saved file back to the correct path;
you switch between terminal commands and file operations on the same host.

The main cost is another interface to learn. It is also less suitable than the CLI for automation, and less transparent than a mount when many unrelated Mac apps need continuous access to the remote tree.

A practical way to choose

Situation	Best starting point
One file, known path	Built-in `sftp`
Scripted or repeatable transfer	`sftp` batch mode, `scp`, or `rsync`
Remote files should behave like a Mac drive	SFTP mount
Frequent visual upload/download work	Dual-pane SFTP client
Terminal and remote files are used together	SSH client with integrated SFTP

I keep the CLI available even when using a GUI. A good desktop client should shorten repetitive work, not make the underlying protocol mysterious.

Where Nexus Shell fits

I develop Nexus Shell, a native macOS SSH client. Its file view uses the third model: local and remote directories side by side, drag-and-drop and multi-select transfers, visible transfer progress, conflict handling, remote editing, and a terminal for the same saved server.

It is deliberately Mac-only and requires Apple Silicon with macOS 14.2 or later. If you need cross-platform clients, a Finder mount, or a workflow that can be fully scripted, one of the other approaches above is likely a better fit. The Free tier covers basic personal SSH use; creating an account includes a seven-day Pro trial for testing the complete file workflow.

Sources: Apple Terminal User Guide, Apple's supported Finder server types, and the macOS sftp(1) manual.

Fixing macOS "No route to host" when an SSH app never asks for Local Network access

Nexus Shell — Wed, 05 Aug 2026 15:43:46 +0000

While testing an SSH app on newer macOS versions, I hit a confusing failure:

Connecting to public hosts worked.
Connecting to a private IP or a .local host returned No route to host.
macOS never showed the Local Network permission prompt.
The app did not appear under System Settings > Privacy & Security > Local Network.

The app already had NSLocalNetworkUsageDescription in its Info.plist. That string explains the permission, but it does not itself trigger the TCC check.

Why the prompt can be missed

The SSH connection in this app is handled by a spawned system ssh process. In some macOS environments, relying on traffic from that child process did not reliably make the parent app appear in the Local Network privacy list.

The practical fix was to let the app process itself briefly touch the local endpoint before starting the normal SSH flow.

import Network

func triggerLocalNetworkPermission(host: String, port: UInt16) {
    guard let nwPort = NWEndpoint.Port(rawValue: port) else { return }

    let connection = NWConnection(
        host: NWEndpoint.Host(host),
        port: nwPort,
        using: .tcp
    )

    connection.stateUpdateHandler = { state in
        switch state {
        case .ready, .failed:
            connection.cancel()
        default:
            break
        }
    }

    connection.start(queue: .global(qos: .utility))

    DispatchQueue.global(qos: .utility).asyncAfter(deadline: .now() + 3) {
        connection.cancel()
    }
}

This connection is only a permission trigger. Its result should not decide whether SSH is allowed to continue; the real connection still owns success, authentication, host-key verification, and error handling.

Only probe local destinations

Do not create an extra connection for every host. I limit the trigger to destinations that can be identified locally:

RFC 1918 IPv4 ranges: 10/8, 172.16/12, 192.168/16
IPv4 link-local: 169.254/16
mDNS names ending in .local
IPv6 link-local and unique-local addresses

I also cache the host in memory so it is touched only once per app launch.

A few implementation details that matter

Keep NSLocalNetworkUsageDescription; the in-process connection complements it rather than replacing it.
Start the trigger before every real connection path converges, so terminal, file, and monitoring flows behave consistently.
Cancel quickly. If the permission sheet is waiting for user input, the connection can remain in preparing or waiting, so a timeout is still needed.
Avoid claiming that every No route to host error is a permission issue. Routing, VPNs, firewalls, and offline servers can produce the same message.

This came from a real fix in Nexus Shell v1.6.7, the native macOS SSH app I develop. The same pattern may help other macOS apps that delegate local-network work to child processes.