Networks
The same server is rarely reached the same way twice. At home, your NAS is 192.168.1.10 on the LAN. From a coffee shop, the only way in is through a bastion host. On the train, you are on cellular and the whole thing has to go over a VPN first. The address changes, the route changes, sometimes even the username or key changes — but it is still the same box you think of as “the NAS.”
Networks are ZestSSH’s answer to that. A Network is a named environment — “Home,” “Office,” “On the road” — that ZestSSH recognizes automatically and uses to decide how to reach each host. You define a host once, then teach it how it should be reached from each place you connect from. ZestSSH figures out where you are and quietly applies the right settings.
Think of it like your phone’s ringer profile. You don’t manually silence your phone every time you walk into a meeting — you set up the rule once, and the phone detects the situation and switches modes for you. Networks do the same for your SSH connections.
The problem Networks solve
Section titled “The problem Networks solve”Without Networks, a host has exactly one address, one port, one route. That forces one of two bad habits:
- Duplicate connections. You save “NAS (home)” pointing at
192.168.1.10and “NAS (remote)” pointing atnas.example.comthrough a jump host. Now you have two entries for one machine, two sets of credentials to keep in sync, and a moment of “which one do I tap?” every single time. - Constant editing. You keep one connection and re-edit its address every time you move between home and away. Tedious, and easy to get wrong.
Networks collapse all of that back into a single host. The host holds a base configuration — the sensible default. Each Network you define can then override just the parts that differ when you are on it. Everything you don’t override is inherited from the base, so a Network profile stays small: usually just “swap the address” or “add a jump host.”
How it works, end to end
Section titled “How it works, end to end”Three moving parts cooperate every time you connect. It helps to keep them straight:
| Stage | What happens | Where it lives |
|---|---|---|
| Detect | ZestSSH reads the device’s current state — IP addresses, connection type, Wi-Fi name — and finds the first Network profile that matches. | network_detector.dart |
| Match | Your Networks are checked top to bottom in priority order. The first one with a matching trigger wins. If nothing matches, the built-in Default network catches everything. | Your Networks list |
| Resolve | When you connect to a host, the resolver takes the base host config and layers the matching Network’s per-host overrides on top, producing the effective address, port, username, key, and jump route. | connection_resolver.dart |
In plain terms: ZestSSH asks “where am I?”, picks the profile that fits, and applies that profile’s overrides at the moment you connect. You never pick the network by hand (unless you want to — see below). You just tap the host, and it connects the right way for wherever you are.
A walk-through
Section titled “A walk-through”Say you have a host called NAS with a base address of nas.example.com reached through a jump host, and one custom Network called Home that triggers on the subnet 192.168.1.0/24.
- At home: your laptop has a
192.168.1.xaddress, so the Home network matches. NAS’s Home override says “address192.168.1.10, no jump host.” ZestSSH connects straight to the NAS on the LAN — fast, direct. - Anywhere else: no custom network matches, so Default wins. NAS has no override for Default, so it inherits the base config and connects through the jump host as usual.
One host. Two very different connection paths. Zero manual switching.
Key concepts
Section titled “Key concepts”| Concept | What it is |
|---|---|
| Network | A named environment (Home, Office, VPN) with a color, an icon, and one or more triggers. |
| Trigger | A condition that makes a Network match — a Wi-Fi name, an IP subnet, cellular, or a connection type. See Triggers & Matching. |
| Priority / order | Networks are evaluated top to bottom; the first match wins. You drag to reorder. |
| Default network | The built-in catch-all. Always matches, always last, can’t be deleted. It represents “none of my named networks fit — just use the base config.” |
| Base config | The host’s own address, port, identity, and jump route. Everything a Network doesn’t override falls through to this. |
| Override | The per-host, per-network changes layered on top of the base. See Per-Host Overrides. |
| Effective connection | The final resolved result after the matching network’s overrides are applied to the base. This is what actually connects. |
Where to find it in the app
Section titled “Where to find it in the app”The Networks list is where you define and order your environments:
- Desktop: the Networks entry in the left sidebar. The list sits on the left; tapping a network opens its editor beside the list so you can switch between networks freely while editing.
- Mobile (Android / iOS): Settings -> Networks. This is the route that always works, including on a fresh install. Once you have at least one custom network, the network banner appears at the top of the home screen and tapping it opens the same screen, but that banner is a shortcut you gain later, not the way in.
The current-network banner (mobile) sits at the top of the home screen on every tab once at least one custom network exists. It shows which profile is active right now, why it matched, and a chip to force a different one manually. It stays hidden until you have at least one custom network — with only the Default there is nothing to switch between.
Per-host overrides live inside each connection’s editor, in a section also called Networks. That is where you say “on Home, reach this host at this address instead.” See Per-Host Overrides.
Do you need Networks?
Section titled “Do you need Networks?”Networks are optional. If you always reach your servers the same way — one address, one route, from anywhere — you never have to touch this feature. Out of the box there is a single Default network and every host just uses its base config, exactly as it did before Networks existed.
You’ll want Networks when any of these are true:
- You reach the same machine by its LAN address at home and its public address (or a jump host) when away.
- You have a VPN (WireGuard, Tailscale/Headscale, corporate) that changes which hosts are reachable and how.
- Some hosts should be hidden or blocked on certain networks — for example, a home lab box you never want to try to reach over cellular.
- You want port forwards that only auto-start on trusted networks.
Common misconceptions
Section titled “Common misconceptions”“A Network stores my servers.” No. A Network is an environment, not a list of hosts. Your hosts live where they always have. A Network just changes how existing hosts are reached when it’s active.
“I have to pick my network every time.” No. Detection is automatic. Manual selection exists as an override for edge cases (see Triggers & Matching), but the normal flow is hands-off.
“Deleting a Network deletes its hosts.” No. Deleting a Network only removes that network and the per-host overrides that pointed at it. The hosts themselves, and their base configs, are untouched.
Next steps
Section titled “Next steps”- Triggers & Matching — how a Network is detected: Wi-Fi name, subnet (CIDR), cellular, priority order, and the manual “force this network” override.
- Per-Host Overrides — what a Network can change for a host: address, port, username, key, jump route, per-network port forwards, and hiding a host.
- Port Forwarding — the forwards that Networks can turn on or off per environment.
- Jump Hosts — the routes a Network can add, swap, or remove per environment.