Ground School
Servers from absolute zero

You need this volume for exactly four moments in the field manual:

Two promises hold throughout: the checkpoint rule (yellow-striped boxes tell you what success looks like — never continue past a failed one), and the no-shame rule: every explanation here assumes you've never done this, because the whole point of owning a server is that nobody was born knowing this.

The terminal is just a text conversation with a computer: you type an instruction, press Enter, it answers. That's the entire interface. No icons, no menus — which is exactly why it works identically on a €4 server with no screen.

agent@hq:~/agent$
│     │  │        └─ $ = normal user   (# would mean root, the all-powerful admin)
│     │  └── the folder you're standing in (~ = your home folder)
│     └───── the machine's name  ← glance here to know WHICH computer you're on
└─────────── who you're logged in as

That middle piece is your seatbelt: if it says hq you're on the server; if it says your laptop's name you're in the cockpit.

• Tab completes. Type cd ag then Tab → it finishes agent/. Nobody types full paths. Double-Tab lists options.
• ↑ recalls. Arrow-up cycles through previous commands. Re-run without retyping.
• Ctrl+C aborts. Command stuck or wrong? This cancels it. It is not “copy” inside a terminal.
• Pasting is special. In most terminals: Ctrl+Shift+V (Windows Terminal & Linux), plain right-click (PowerShell), Cmd+V (Mac). Never hand-type tokens or keys — one wrong character costs an hour.

mkdir groundschool
cd groundschool
nano hello.txt        # type anything → Ctrl+X → Y → Enter to save & exit
cat hello.txt         # your words come back
cd ..
rm -r groundschool    # clean up (-r = folder and contents)

SSH (“secure shell”) turns your cockpit terminal into the server's terminal. You type ssh agent@65.108.1.2, and from that moment every command runs over there, encrypted, until you type exit. That's it — a remote-control cable made of maths.

An SSH key is two files that only work together: a private key (stays on your laptop forever, like a physical house key) and a public key (a lock you can hand out freely — servers install the lock, your key opens it). One command mints the pair. Works identically on Mac, Linux and Windows PowerShell:

ssh-keygen -t ed25519
# "Enter file in which to save…"  → just press Enter (default location is correct)
# "Enter passphrase…"             → Enter twice for none (fine for starting out),
#                                    or set one — it's a password ON the key itself

You now own two files in a hidden .ssh folder inside your home folder:

# Mac / Linux:
cat ~/.ssh/id_ed25519.pub

# Windows PowerShell:
type $env:USERPROFILE\.ssh\id_ed25519.pub

The output is one long line starting ssh-ed25519 AAAA…. Select it with the mouse, copy it. That single line is what Hetzner's “SSH key” box wants in GS 03. Pasting the private file instead is the classic mistake — if what you copied doesn't start with ssh-ed25519, you grabbed the wrong one.

1. The fingerprint question — “The authenticity of host … can't be established. Are you sure you want to continue connecting?” Normal on the very first connection to any new server: your laptop has simply never met this machine. Type yes. (Seeing it again later for the same IP means the server was reinstalled — or, rarely, something fishy. After a reinstall, run the ssh-keygen -R YOUR_IP command the error itself suggests, then reconnect.)
2. Invisible passwords. When a terminal asks for a password, nothing appears as you type — no dots, no stars. It is receiving it. Type it blind, press Enter.
3. The prompt changes. Success looks like the prompt swapping to root@hq:~# or agent@hq:~$. You're now typing on the server.

exit                    # polite goodbye — back to your laptop's prompt

# session frozen (wifi blipped, laptop slept)? the secret escape sequence:
#   press Enter, then type   ~   then   .     (tilde, dot — nothing to paste)

Decoding the three classic SSH errors

This is FM · Part 2 · Route A in slow motion — every field on every screen, including the two moments that confuse everyone (the identity check, and the forced password change).

1. Go to hetzner.com/cloud → Sign up. Real name and address (it's a German company; they invoice properly — handy for your Categoria B paperwork, incidentally).
2. Confirm the email they send.
3. Add a payment method — card or PayPal.
4. The identity check: brand-new accounts are sometimes asked to verify — a small card authorisation, PayPal confirmation, or occasionally a photo of ID. This is normal fraud-prevention, not a scam; approval is usually minutes to a few hours. If your account sits in “pending”, that's this. Wait it out.

Open console.hetzner.com → you'll see a default project (a folder for servers — the default is fine) → big red Add Server button. The form, top to bottom:

Press Create & Buy now. Thirty seconds later: green dot, and an IPv4 address like 65.108.x.x. Copy it — that number is “YOUR_SERVER_IP” everywhere in both books.

ssh root@YOUR_SERVER_IP       # fingerprint question → yes

• If you added an SSH key: you land straight at root@hq:~#. Done.
• If you skipped the key: Hetzner emailed a root password. Paste it (invisible!). The server then forces a change: it asks for the current password again, then a new one twice — and often drops the connection right after. That's by design; just ssh root@YOUR_SERVER_IP again with your new password.

Three Hetzner facts worth knowing

• Billing is hourly up to the monthly cap. Delete the server → billing stops. Powered-off still bills (the hardware and IP stay reserved) — “off” is not “free”.
• The lockout parachute: in the console, your server page has a >_ Console button — a terminal in the browser that works even when SSH doesn't. If you ever firewall yourself out, this is the way back in.
• Snapshots (server page → Snapshots) are a cheap one-click full backup — a few cents/month. Take one after finishing the field manual; restoring it recreates your whole setup.

This turns a forgotten laptop into FM · Part 2 · Option C: a real 24/7 Linux server. It works because the agent only makes outbound calls — a machine behind your home router needs zero network configuration.

Unsure of the specs? They usually appear on the BIOS screen in S3 — or just try; the installer runs fine on anything that meets the minimum.

1. Download Ubuntu Server 24.04 LTS from ubuntu.com/download/server (~3GB file ending .iso). Server, not Desktop — no graphical interface means every scrap of the old machine's RAM goes to your agent.
2. Get a USB-writing tool: Rufus (rufus.ie, Windows) or balenaEtcher (etcher.balena.io, Mac/Windows/Linux).
3. Insert the USB stick → open the tool → select the .iso → select the stick → Start/Flash. Accept the defaults (Rufus may ask about “ISO mode” — keep the recommended option). Five minutes.

Plug the stick into the old laptop, power it on, and immediately tap the boot-menu key repeatedly — it's a tiny window. A menu appears; choose the USB entry (often named after the stick's brand, or “UEFI: …”).

Missed the window and it booted the old system? Just restart and hammer earlier. If the USB never appears: enter BIOS instead, find Boot Order, put USB first, save-and-exit (F10 usually). On some machines you must also disable “Secure Boot” — Ubuntu normally handles it, so only touch that if the stick refuses to boot.

A text-based installer appears — no mouse; arrows move, Space ticks boxes, Enter confirms, Tab jumps to Done. In order:

1. Try or Install Ubuntu Server → Enter.
2. Language → English (fewer surprises when googling errors).
3. Keyboard → pick your physical layout (Portuguese if that's the hardware).
4. Type of installation → Ubuntu Server (the default, not “minimized”).
5. Network — the one screen that varies:
   • Ethernet cable plugged in? It self-configures — you'll see an IP appear. Done.
   • Wifi only: select the wlan… device → Edit → choose your network, type the password → wait for an IP to appear next to it. If no wifi device is listed, the card needs drivers Ubuntu lacks — borrow an ethernet cable for install day; wifi can be sorted after.
6. Proxy → leave blank.
7. Mirror → default; let its test finish.
8. Storage → Use an entire disk (leave the LVM default as-is) → Done → the summary appears → Done → a red Confirm destructive action box: this is the point of no return for the old system → Continue.
9. Profile → Your name: anything · Server's name: hq · Username: agent · password twice. Using agent here means you skip the user-creation step later — the field manual's user already exists.
10. Upgrade to Ubuntu Pro → Skip for now.
11. SSH configuration → ☑ Install OpenSSH server — THE checkbox of the whole install. Arrow onto it and press Space until an X appears (Enter does not tick it — this snags everyone). Miss it and the laptop is unreachable remotely. Leave “Import SSH identity” as No.
12. Featured server snaps → tick nothing → Done.
13. Wait through the install log (10–20 min on old hardware; “downloading security updates” can sit a while — let it). → Reboot Now → pull the USB stick out when it asks.

The laptop boots to a black screen with a login. Log in on the laptop itself this one time (agent + your password — invisible typing, remember), then ask it for its address:

hostname -I
# prints something like:  192.168.1.47   ← its address on YOUR home network

Now, from your main computer, take remote control — and never touch the laptop's keyboard again:

ssh agent@192.168.1.47        # your number from above · fingerprint → yes

One home-network truth: 192.168.x.x addresses only work from inside your house. That's fine — the agent talks outward to Telegram, so it works from anywhere in the world regardless. It's only your ssh maintenance that's house-bound; GS 05 fixes that too.

A fresh laptop install still thinks it's a laptop: close the lid and it naps, killing your agent. Four fixes turn it into an appliance you can shut, shelve, and forget.

sudo nano /etc/systemd/logind.conf

Find these two lines, remove the leading #, and set both to ignore:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore

sudo systemctl restart systemd-logind   # applies it (your ssh session survives)

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

“mask” = bolts the door shut so nothing — power settings, stray packages — can ever suspend it. With the lid shut the screen is off anyway, which is all the power-saving you need.

• BIOS trick: reboot into BIOS (GS 04's table) → find “Restore on AC Power Loss” / “Power On After Power Failure” (usually under Power/Advanced) → set to Power On. Electricity returns → laptop boots itself → the field manual's FM · Part 9 systemd service starts the agent → nobody touched anything. Not every BIOS has it; a working battery covers short blips regardless.
• Placement: plugged in always, somewhere ventilated (not a drawer, not a sofa), ethernet if the router is near — wifi is fine, cable is calmer.

Home routers hand out addresses by lease; after a router reboot the laptop can come back as .53 instead of .47. The agent doesn't care — only your ssh does. Fix it at the router: open its admin page (address on the router's sticker), find DHCP → Address Reservation (name varies), and pin the laptop (“hq”) to its current address. Two minutes, once.

Want to ssh in from a café when something needs a restart? Tailscale gives your devices a tiny private network across the internet — no ports opened, free for personal use:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up            # prints a login link — open it, sign in, approve
tailscale ip -4              # its permanent private address, like 100.84.x.x

Install the Tailscale app on your main computer (and phone), sign into the same account, and ssh agent@100.84.x.x works from anywhere on earth. Entirely optional — the bot never needs it; it's purely for your own maintenance access.

Six concepts the field manual uses without ceremony. Read once; things stop feeling like incantations.

① The map — where things live

② sudo — the admin prefix

Normal users can't modify the system; sudo in front of a command runs that one command as administrator, after asking your own password (invisible, as always). Files in your home folder never need it; anything touching /etc, installing software, or managing services does. If a command fails with “Permission denied” on a system path, the answer is usually just: same command, sudo in front.

③ apt — the app store

sudo apt update            # refresh the catalogue (prices haven't changed — all free)
sudo apt upgrade -y        # install updates for everything (-y = stop asking, yes)
sudo apt install -y curl   # install a thing by name

④ venv — why Python lives in a bubble

Modern Ubuntu refuses system-wide pip install (that's the externally-managed-environment error) to stop projects trampling each other. A venv is a private bubble of Python inside your project folder. Two things to remember:

cd ~/agent
source venv/bin/activate     # step INTO the bubble → prompt gains a (venv) prefix
pip install whatever         # installs affect only this project
deactivate                   # step out

And the trick that makes FM · Part 9 work: the service file runs venv/bin/python directly — using the bubble's Python by full path needs no “activation”. Activation is for humans; paths are for robots.

⑤ chmod 600 — who may read a file

Every file has permissions. chmod 600 .env means “owner may read and write; everyone else, nothing”. The manual applies it to .env because that file holds your tokens — on a multi-user system it's the difference between a config file and a leak.

⑥ Reading an error without panic

• Read the last line first. Python tracebacks are a story told backwards — the final SomethingError: message line is the actual problem; everything above is the route it took to get there.
• Logs: journalctl -u agent -f follows live (Ctrl+C stops following); without -f it opens a scrollable pager — G jumps to the end, /text searches, q quits.
• The exact error text is a key, not an insult. Paste it verbatim into a search — or into your own bot once it's alive.

The unstick ritual (in order, every time)

1. Read the last line of the output, out loud if needed. It usually names the problem in plain-ish English.
2. Retreat to the last passed checkpoint. Whatever broke lives between there and here — usually one command, often one character.
3. Check the caption. Was that command meant for the cockpit or the server? (This is the #1 cause.)
4. Search or ask with the exact text. Paste the verbatim error into a search engine, into Claude, or — once it's running — into your own bot. Never paraphrase an error.
5. Still stuck after 20 minutes? Walk away for ten. This is a real technique, not a platitude.

Disaster table

Why nothing here is ever truly lost

Your agent's entire identity is one folder: ~/agent — the code, the .env secrets, the memory/ brain, every project. The field manual already put it under git. Add one habit and total destruction becomes a 30-minute inconvenience — run this from your cockpit every week or two:

scp -r agent@YOUR_SERVER_IP:~/agent/memory  ~/agent-backup/
scp    agent@YOUR_SERVER_IP:~/agent/.env     ~/agent-backup/
# memory = the brain · .env = the keys · agent.py lives in this guide anyway

Worst case, ever: new server (GS 03 or GS 04) → field manual Parts 3–5 → copy those two things back → the agent wakes with its memory intact, asking what's next. On Hetzner, a snapshot shortcuts even that.