Chapter 22: Linux Operations for Agent Deployment

Ali built a competitor-analysis agent in Chapters 20 and 21. It scrapes pricing data, stores results in a database, and generates daily summaries. He runs it on his laptop. It works: when his laptop is open.

Sunday night. His biggest client has a board meeting Monday morning. The agent was supposed to generate a weekend pricing report. Ali opens his laptop and checks the dashboard. The agent has not run since Friday. Three days of missing data. Board meeting in twelve hours.

His friend Dev has a cloud server. "I'll give you SSH access," Dev texts. "Get your agent running there and it won't depend on your laptop anymore."

Ali opens a terminal. Types an SSH command. A blinking cursor on a black screen. No desktop. No icons. No file explorer.

This chapter is how Ali, and you: go from that blinking cursor to a production agent that runs 24/7, survives reboots, and recovers from failures. You will not memorize Linux commands. You will direct Claude Code to execute them, read what comes back, and understand what it means.

Chapter Thesis

Your agent's code might be perfect. If you can't deploy it to a server, keep it running, and fix it when it breaks, it's a side project, not a product. Linux operations is the bridge between "it works on my laptop" and "it runs in production."

📚 Teaching Aid

🖥️ Fullscreen

What You'll Learn

By the end of this chapter, Ali's competitor-tracker agent runs as a production systemd service that:

• Starts automatically when the server boots
• Restarts automatically if it crashes
• Logs all activity for monitoring
• Runs under a dedicated non-root user
• Accepts connections only via SSH keys
• Can be diagnosed systematically when problems occur

This is a real deployment, not a toy example.

Prerequisites

Before starting this chapter, you should have completed:

• Chapter 18: Seven Principles of Agent Work: Especially Principle 1 (Bash is the Key) and Principle 5 (Persisting State in Files)
• Chapters 19–21: You've built agent workflows for file processing, Python, and SQL

No prior Linux experience is required. Lesson 1 starts from a blinking cursor.

Windows Users

If you're on Windows, you need WSL2 (Windows Subsystem for Linux). Run wsl --install in PowerShell as Administrator, then restart your computer. All commands in this chapter work in WSL2 Ubuntu.

Lessons Overview

Lesson	Title	Duration	Focus
Lesson 1	Where Your Agent Lives	30 min	SSH, filesystem, server orientation
Lesson 2	Reading What Your Agent Does	30 min	Command output, permissions, vocabulary
Lesson 3	Setting Up Your Agent's Home	30 min	Directory structure, .env, logs
Lesson 4	Making Your Agent Unkillable	35 min	systemd services, restart policies
Lesson 5	Locking the Door	30 min	Users, permissions, SSH keys, security
Lesson 6	When Things Go Wrong	35 min	LNPS triage, log analysis, debugging
Lesson 7	Capstone: Zero to Production	45 min	Deployment spec, full integration
Exercises	Linux Operations Exercises	60 min	Hands-on practice across all lessons
Quiz	Chapter Quiz	20 min	50-question conceptual assessment

Total: ~5.25 hours (including exercises and quiz)

The Teaching Pattern

Every lesson in this chapter follows the same flow:

1. Story beat: Ali hits a real problem
2. Direct Claude Code: You tell the agent what to do in plain English
3. Read the output: Understand what came back and why
4. Build the mental model: Connect the output to the concept

You will not type Linux commands from memory. You will direct an agent, watch what it does, and learn to understand the results.

Seven Principles (Compact)

Principle	Chapter 22 Application
P1 Bash is the Key	Every SSH command, systemd control, and diagnostic tool runs in bash — it is the interface
P2 Code as Universal Interface	systemd service files are declarative code that specifies exactly how an agent runs
P3 Verification as Core Step	Check service status, log output, and health endpoints before declaring a deployment done
P4 Small Reversible Decomposition	Deploy in layers: SSH access, then directory structure, then service, then security, then monitoring
P5 Persisting State in Files	Logs, service unit files, and .env configs persist agent state and configuration on disk
P6 Constraints and Safety	Least-privilege user, SSH keys only, and firewall rules limit what the agent can access
P7 Observability	journalctl, systemd status, and the LNPS triage pattern give full visibility into agent behavior

How This Chapter Teaches

Every lesson in Chapter 22 follows the PRIMM-AI+ cycle: a five-stage structure that builds genuine understanding instead of copy-paste habit. Here is how each stage maps to Linux work:

1. Predict [AI-FREE]: Before directing the agent to run any command, write down what output you expect to see. For example: what will systemctl status show for a running service? What permissions will ls -la display on a .env file? Commit your prediction on paper, with a confidence score from 1 to 5, before you touch the keyboard.

2. Run: Direct the agent to execute the command using Claude Code or OpenCode. You provide the intent in plain English; the agent writes and runs the Linux command. Every Run stage uses the tool-tabs format so you work in whichever tool you prefer.

3. Investigate: Before asking the agent to explain anything, write your own one-sentence explanation of what the output shows. Identify every column, field, and symbol you do not recognise. Then ask the agent about the specific parts you cannot explain yourself.

4. Modify: Change one flag, parameter, or configuration value. Predict how the output will differ, direct the agent to make the change, and compare the actual result to your prediction. The gap between prediction and result is where learning happens.

5. Make [Mastery Gate]: Complete a related but different Linux task entirely on your own, without re-reading the lesson. Passing means you can specify the goal in plain English, direct the agent, and verify the result meets the spec.

Quick Reference: Linux Terms in Plain English

New to Linux? These 12 terms appear throughout the chapter. Each definition is two sentences maximum.

Term	Plain English
Shell	The program that reads your commands and tells the OS to run them. On Linux servers, this is almost always bash.
Terminal	The window application that shows your shell. Terminal is the glass, shell is the voice on the other end.
Directory	What Windows calls a "folder." On Linux, we say "directory": same concept, different word.
Root	Two meanings:/ is the top of the filesystem tree, and root is the superuser account with unlimited power. Context tells you which.
Daemon	A service that runs in the background, started at boot, not attached to any terminal. Your agents become daemons in Lesson 4.
Port	A numbered channel for network communication. Your agent listens on a specific port (e.g., 8080) for incoming requests.
Process	Any running program. Your agent is a process with an ID number (PID).
Pipe	The | character. Takes the output of one command and feeds it as input to the next.
Redirect	Sending output to a file (>) instead of the screen. >> appends; > overwrites.
Absolute path	A file address starting from /. Works regardless of where you are (e.g., /var/log/agent.log).
sudo	"Run this as root." Grants temporary admin power for one command. Use sparingly; misuse causes real damage.
Environment variable	A named value available to all processes in a session. Used for secrets, configuration, and API keys.

Let's Begin

Ali is staring at a blinking cursor on Dev's server. Twelve hours until the board meeting. The agent needs to be running by morning.

Start with Lesson 1: Where Your Agent Lives →