Add permanent build agent setup instructions to setup guide

Document how to add dedicated build agents via SSH, configure labels
for routing jobs, and disable builds on the controller for scaling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

1 files changed, 79 insertions, 0 deletions

diff --git a/doc/setup-guide.md b/doc/setup-guide.md
index 43c2b20..ac277d6 100644
--- a/doc/setup-guide.md
+++ b/doc/setup-guide.md
@@ -287,6 +287,85 @@ docker restart jenkins
 The cleanup script will run automatically and clear the stuck state. No
 manual deletion of build directories is needed.
 
+### 6.6 Adding a permanent build agent (optional)
+
+By default, Jenkins runs all builds on the controller node using Docker
+containers (DooD). This works well for a single-user server. If you need
+to scale (heavy builds making the UI unresponsive, builds on different
+OS/architectures, or running many builds in parallel), you can add
+dedicated build agents.
+
+A **build agent** is a separate machine that Jenkins connects to and
+delegates builds to. The controller handles scheduling and the UI, while
+agents do the actual work.
+
+#### Prerequisites on the agent machine
+
+The agent machine needs:
+- Java (same major version as the controller)
+- SSH access from Jenkins
+- A dedicated directory for Jenkins workspace (e.g., `/home/jenkins`)
+- Docker (if you want to use Docker agents on the remote machine)
+
+```bash
+# On the agent machine
+apt-get update && apt-get install -y default-jdk
+useradd -m -d /home/jenkins jenkins
+```
+
+#### Configure the agent in Jenkins
+
+1. Go to **Manage Jenkins** > **Nodes** > **New Node**
+2. Enter a name (e.g., `build-agent-1`), select **Permanent Agent**, click **Create**
+3. Configure:
+   - **Remote root directory**: `/home/jenkins`
+   - **Labels**: space-separated tags to route jobs (e.g., `linux x86_64 docker`)
+   - **Usage**: "Use this node as much as possible" (or "Only build jobs
+     with label expressions matching this node" if you want explicit routing)
+   - **Launch method**: "Launch agents via SSH"
+   - **Host**: the agent machine's IP or hostname
+   - **Credentials**: add SSH credentials for the `jenkins` user on the agent
+   - **Host Key Verification Strategy**: "Non verifying" for initial setup
+     (switch to "Known hosts" for production)
+4. Click **Save** — Jenkins will connect to the agent via SSH
+
+#### Routing builds to agents
+
+Use the `label` directive in your Jenkinsfile to target specific agents:
+
+```groovy
+pipeline {
+    agent { label 'linux' }
+    stages {
+        stage('Build') {
+            steps {
+                sh 'make'
+            }
+        }
+    }
+}
+```
+
+You can combine labels with logical operators:
+
+```groovy
+// Run on a node that has BOTH labels
+agent { label 'linux && docker' }
+
+// Run on a node that has EITHER label
+agent { label 'linux || macos' }
+```
+
+#### Disabling builds on the controller
+
+Once agents are set up, you can stop running builds on the controller:
+
+1. Go to **Manage Jenkins** > **Nodes** > **Built-In Node** > **Configure**
+2. Set **Number of executors** to `0`
+3. Click **Save**
+
+Now all builds will be routed to agents only.
+
 
 ## 7. Gerrit (Code Review)