Transport and connections

Every provider that talks to a remote machine goes through one shared layer, nxd-transport. It is core infrastructure, not a provider: nothing in NXD opens its own SSH connection or spawns its own unbounded subprocess.

That consolidation is the point. Host key verification, connection reuse, timeouts, and output sanitization are decided once and enforced everywhere, rather than reimplemented per provider with slightly different rules.

Host keys are pinned, always

Every connection verifies the target’s Ed25519 host key against the identity record NXD manages for that host.

There is no interactive prompt, no trust-on-first-use, and no fallback to an unverified shell. A host whose key does not match the reviewed identity is a refusal, not a warning — the same key material that provisioned the machine is the key material used to reach it.

Connections are reused

SSH connections are multiplexed by default: ControlMaster=yes with ControlPersist=10m. The first connection to a host establishes a master, and every subsequent command in that operation reuses it.

Without this, each remote command pays a full TCP handshake plus an SSH handshake. A deployment that runs twenty commands against a host pays that cost twenty times, which on a distant or slow link dominates the actual work.

Reuse and verification are the same decision. Before the transport was shared, twelve non-test modules across four providers invoked SSH and exactly one multiplexed — which also meant host key handling varied between them.

Jump hosts

Targets behind a bastion are reached with SSH proxy-jump (-J), configured per target rather than assumed from ambient SSH config.

Reachability probing is proxy-aware. A target on an isolated subnet that is only routable through its jump host is probed through that jump host, so an unreachable-looking target is genuinely unreachable rather than an artifact of probing from the wrong network position.

Subprocesses are bounded

Local and remote command execution runs through a common process runner that provides:

• Streaming output, so long operations report progress instead of blocking until completion.
• Line-level sanitization, so secret values cannot reach logs or the terminal.
• Timeouts and cancellation, so a hung remote command fails the action rather than the whole run.

What this means in practice

You do not configure the transport directly. It is worth knowing about for three reasons:

1. A host key mismatch is a hard failure. If you rebuild a machine outside NXD and its host key changes, the reviewed identity must be updated — the transport will not silently accept the new key.
2. Jump hosts belong in your configuration, not in ~/.ssh/config. NXD does not inherit ambient SSH configuration, so routing is visible in the repository.
3. Slow first connection, fast subsequent ones is expected. The master connection is established once per operation.

For the design rationale and the measurements behind the consolidation, see docs/architecture-design/nxd-transport.md in the repository.