Hostbound Documentation

What is Hostbound?

Hostbound is a browser game that teaches intro-networking students one of the most counterintuitive facts about working over the network: once you ssh into a machine, your commands run there, and the network that machine is on decides who you can reach next. You are not "on the Internet"; you are standing on whatever subnet your current host happens to share an interface with.

Each run drops you onto a randomly placed host inside a procedurally generated network. Hidden somewhere is the golden machine. You explore the network using the same four commands real operators reach for first - ip a, ping, nmap, ssh - reading each host's recon notes, narrowing in, and finally claim-ing the gold. Fewer hops and fewer wrong claims is a better score.

Open Hostbound at ../index.html to start a fresh game, or pick a guide below for a structured walkthrough.

What students actually do

• Read where they are. ip a shows every connected interface, the IP, and the network number. That list is the entirety of who they can reach this turn.
• Scan a subnet. nmap -sn 10.4.2.0/29 ping-sweeps one connected network and reveals its live hosts. nmap -sV <host> version-scans a single host for ports and services.
• Hop to a peer. ssh <address> moves them to a host that shares a directly-connected subnet. In IPv6 worlds, bare ssh hostname works too.
• Pick up the recon note. Every host has a <word>.txt file in its home (visible to ls / cat / nano) carrying the exact hop distance to the golden machine plus a true octet of the golden IP. Triangulate.
• Claim the gold. claim when they think they have arrived. A wrong claim does not end the game - it just counts.

What the game models, and what it deliberately does not

• Same-LAN reachability only. There is no routing in the current version - that is the lesson. To cross subnets you must ssh to a multi-homed host (a bridge) and step from one of its NICs to another.
• Fog of war. The map starts empty and fills only with what you have discovered via ip a, ping, nmap, and ssh.
• Variable subnet sizes across the full IPv4 range (not just /24s, not just RFC1918). Reading masks correctly is part of the gameplay.
• Three address modes: pure IPv4 (HB1- codes), pure IPv6 with ULA /64s (HB2-), and dual-stack worlds with a mix of v4-only, v6-only, and true dual-stack LANs (HB3-). Crossing a family boundary requires hopping a dual-stack bridge.
• Five difficulty levels - Casual / Normal / Hard / Brutal / Extreme - which dial the par hop count, the number of branches, loops, and 3+-NIC routers in the topology.
• Optional hard modes for advanced labs: Firewalls (some hosts and subnets drop ping/ssh and you have to find a parallel path), Hidden Host Mode (no breadcrumb / no map outside your current LAN), and Cybersecurity Mode (you need to carry a matching exploit tool to ssh a vulnerable host; collect loot, sell intel at a hidden broker on The Darkweb, buy more tools).

Sharing a network

Every world is identified by a short code shown in the bottom bar - for example HB1-7DEMOFW0 or HB3-2CX5Z4M0. The code carries the address family, the difficulty, the Firewall and Hidden-Host bits, the Cybersecurity bit, and the topology seed - so a student pasting just the code reproduces the sender's exact playable world. Send a link, or just the bare code in chat; it works either way. Custom sandbox codes (HB4-) let instructors dial specific topology parameters directly.

Who uses Hostbound

• Students open the page, play the daily network or whatever code an instructor handed out, and learn the same-LAN reachability rule the hard way - by hitting it. The Student Guide walks every command, the map, the codes, and the optional hard modes.
• Faculty use Hostbound as an in-class demo, a homework assignment, or a graded challenge. The Faculty Guide covers teaching uses, the code-sharing workflow, custom sandbox worlds, the daily seed, the cipher ladder on the win screen, run-report exports, and the Admin tools (reveal path, reveal network, jump to host, show firewalls).
• Maintainers work in README.md and the Maintainer Guide: the single-file constraint, the deterministic generator, the code format, the lattice embedder, the persistence rules, the verification harness, and the deploy.

Under the hood

Hostbound is one HTML file - embedded CSS, embedded vanilla JS, embedded Canvas map. There is no build step, no framework, and no external resources (no CDN, no fonts, no libraries). It runs by double-clicking index.html on file:// and is also served as a static file at its.ohio.edu/tools/hostbound.

Only three things persist across reloads: the high-visibility flag, the theme (light / dark / auto), and - once an instructor unlocks it - the sticky Admin passphrase (Admin ▸ Clear Local Settings wipes all three). Game progress is never persisted - reopening a code restarts that same world fresh. Every shareable piece of state (family, difficulty, Firewalls, Hidden Host Mode, Cybersecurity, topology seed) rides inside the code itself; there is no out-of-band knowledge required.