Docs / Connect to Hosts

Multi-hop & jump hosts

When a server has no public address, you reach it by hopping through a bastion — and NetShell chains those hops for you, verifying every host and authenticating at each step, from your iPhone, iPad or Mac.

What a jump host is

A jump host (also called a bastion) is a gateway server that sits on the edge of a private network. Internal machines — databases, app servers, build agents — accept SSH only from the bastion, never from the open internet. To reach one of them you first connect to the bastion, then open a second SSH connection from the bastion onward to the target. NetShell automates this: you describe the path, and it builds the encrypted chain hop by hop without you typing a single intermediate command.

This is the standard way to expose one hardened, monitored entry point instead of opening SSH on every internal host. Your credentials and traffic ride inside the SSH session the whole way — the bastion forwards the encrypted stream, it does not see your terminal in the clear.

Single jump host

The common case is one hop: your device connects to the bastion, and the bastion forwards you to a target behind it. The logical path looks like this:

your device  ->  bastion.example.com  ->  db.internal:22

You only ever address the bastion publicly. The internal target's address (db.internal) is resolved from the bastion's own network, so it can be a private hostname or a 10.x / 192.168.x address that means nothing on the public internet. NetShell opens the channel to the bastion, then negotiates a fresh SSH session through it to the target.

Multi-hop chains

Some networks are nested: an outer bastion lets you into a DMZ, a second bastion lets you into a restricted segment, and only from there can you reach the final host. NetShell supports a full chain — you add each hop in order and the app dials them in sequence:

your device
   ->  edge-bastion.example.com
   ->  inner-bastion.dmz
   ->  app-server.restricted:22

Each link is its own authenticated, encrypted SSH session layered inside the previous one. The final terminal you type into is the last host in the chain; everything before it is plumbing that NetShell manages for you.

Hop-by-hop authentication

Every hop authenticates independently — they do not have to share credentials. One hop can use a password while the next uses an SSH key; a third can use a different key entirely. NetShell pulls each hop's credentials from the same vault as any other connection:

• Keys and passphrases live in the hardware-backed iOS Keychain, protected by Face ID, and are presented to the right hop at the right moment.
• Per-hop usernames are kept distinct, so admin@bastion and deploy@app-server coexist in one chain.
• No agent forwarding needed — because the vault is on the device, NetShell answers each hop's key challenge directly instead of forwarding an agent through the bastion, so a private key is never exposed to an intermediate host.

Host verification at every hop

NetShell verifies the host key of each server in the chain at handshake time, and it fails closed. If any hop — the bastion, an intermediate, or the final target — presents an unknown or changed key, the chain stops at that link and your credentials are never sent onward. On the first connection to a new host you approve its key (trust-on-first-use); after that, a key that doesn't match the one you trusted is flagged rather than waved through.

This matters more in a chain than in a single connection: a man-in-the-middle planted at one hop can't silently relay you to the real target, because the substituted key won't match what you trusted. See Host verification for how trust-on-first-use and key changes are handled. Known-hosts keys stay device-local and are never synced.

Set up a jump-host chain

1. Add the final target as a connection — the host you actually want a terminal on.
2. Open its settings and find the Jump host (proxy) option.
3. Select the bastion that sits in front of it. For a deeper network, add another hop in front of that one to build the chain in order.
4. Set each hop's username and its credential — a key from the vault or a password — independently.
5. Save and connect. NetShell dials the bastion(s) first, verifies each host key, then drops you into the terminal on the final host.

Group related bastions and targets with groups & tags so a whole environment stays organised, and use snippets to run setup commands the moment the chain comes up.

Tunnels through the chain

Once the chain is established you can layer port forwarding on top of it — forward a database or an internal dashboard from a host that is only reachable past the final hop, and it surfaces on 127.0.0.1 on your device. SFTP works the same way: browse files on the target through the SFTP browser over the same multi-hop session, with no separate login.

Troubleshooting

• Chain stops at a hop. That hop's host key is unknown or changed and NetShell failed closed — review and approve it, or investigate why the key moved before continuing.
• Auth fails on one link. Check that the username and credential are set for that specific hop, not just the final host. Each hop authenticates separately.
• Target unreachable past the bastion. Confirm the internal address resolves and is reachable from the bastion's network, not from your device. Test it in a terminal on the bastion first.
• Bastion connects but the next hop times out. The bastion may not permit outbound SSH to the target, or a firewall blocks it — verify the path on the bastion itself.
• App relocked mid-setup. NetShell auto-relocks behind Face ID after idle; unlock and reconnect.