Machine Build Manual — Volume 2: The Build
GOAL Investment Inc. · INSURED · BONDED · VERIFIED · EST. 2007
A deployment guide for a local-first machine fleet. Volume 1 covered architecture and the reasoning loop. This volume covers preflight, bootstrap, the model engine, personas, secure transfer, the directive queue, daemonisation and health. Volume 3 covers the voice layer.
How to use this volume
Work in order. Every part ends in something you can check with your own eyes, and if a check fails, stop and fix it before moving on. A fleet built in a hurry is a fleet you will not trust.
Placeholders look like <COORD-IP>. Fill them from the worksheet you completed in Volume 1.
Paths in this volume use C:\FLEET\ on Windows and ~/fleet/ (or /var/fleet/) on macOS and Linux. Use whatever root you like, but use one root on every node. Predictable paths are how a script written on one machine runs unchanged on another.
Part 1 — Preflight
The directory blueprint
Every node gets the same folder shape. Different operating systems, same skeleton.
| Folder | Holds |
|---|---|
<ROOT> |
Working root |
<ROOT>/state |
State file and log. This is the node's memory of itself |
<ROOT>/directives |
Incoming instructions and the offline queue |
<ROOT>/scripts |
Executable engines, scripts, tools |
<ROOT>/artifacts |
Generated output: builds, documents, media |
<ROOT>/logs |
Execution logs, error output, process logs |
<ROOT>/models |
Persona configuration files |
Create it before you install anything. Every failure downstream is easier to read when the paths are predictable.
# macOS / Linux
ROOT=~/fleet
mkdir -p "$ROOT"/{state,directives,scripts,artifacts,logs,models}
# Windows (PowerShell)
$ROOT = "C:\FLEET"
"state","directives","scripts","artifacts","logs","models" |
ForEach-Object {
$p = Join-Path $ROOT $_
if (-not (Test-Path $p)) { New-Item -ItemType Directory -Path $p -Force | Out-Null }
}
Network validation
Before any deployment script runs, prove the network:
- Fixed addresses. Reserve a static lease per role on your router. Confirm each node actually received it.
- Reachability. Ping every other node. You want zero loss. One flaky link will present itself later as a mysterious timeout in an unrelated script.
- Outbound access. Confirm HTTPS on 443 and SSH/SFTP on 22 leave your network. Test from each node, not just one.
- Write the map down in the same file the machine reads, so a script can resolve a role to an address without you.
Privileges
Install as an administrator (Windows: Run as administrator; macOS/Linux: sudo). Then run the steady state as a normal user. An autonomous loop running as administrator can do anything to your machine, including things you did not plan for.
Set the boundary now: which folders may the machine write, what may it spend, what must it ask before doing.
Part 2 — Bootstrap
The bootstrap script has one job: turn a bare machine into a node. Detect identity, create the skeleton, install the runtime, pull the working scripts, verify, report. Keep it idempotent — running it twice must be safe.
The failure that will bite you: fake Python detection
The most common bootstrap bug is not a missing runtime. It is a bootstrap that thinks the runtime is present.
Checking with Get-Command python or command -v python3 is not enough. Windows ships a Store alias that resolves but cannot run. A broken environment leaves a shim that answers a version check and then fails on the first import. The script reports success, the loop dies on cycle one, and the log is empty.
Detect by executing, not by locating:
$candidates = @("python.exe","python3.exe","py.exe")
$PY = $null
foreach ($c in $candidates) {
$cmd = Get-Command $c -ErrorAction SilentlyContinue
if (-not $cmd) { continue }
$out = & $cmd.Source -c "import sys;print(sys.version_info[0])" 2>$null
if ($LASTEXITCODE -eq 0 -and "$out".Trim() -eq "3") { $PY = $cmd.Source; break }
}
if (-not $PY) { Write-Host "No working Python 3 found. Install it, then rerun."; exit 1 }
Write-Host "Python OK: $PY"
PY=""
for c in python3 python3.12 python3.11 python; do
command -v "$c" >/dev/null 2>&1 || continue
if [ "$("$c" -c 'import sys;print(sys.version_info[0])' 2>/dev/null)" = "3" ]; then PY="$c"; break; fi
done
[ -n "$PY" ] || { echo "No working Python 3 found."; exit 1; }
Run the interpreter and check the exit code. Anything less is a guess.
Identity detection
A node should be able to work out which role it is without being told. Match the address against your map, and fall back to asking:
$IP = (Get-NetIPAddress -AddressFamily IPv4 |
Where-Object { $_.IPAddress -like "192.168.*" } |
Select-Object -First 1).IPAddress
switch ($IP) {
"<COORD-IP>" { $role = "coordinator" }
"<OPS-IP>" { $role = "operations" }
"<MEDIA-IP>" { $role = "media" }
"<KNOW-IP>" { $role = "knowledge" }
default { $role = "unassigned" }
}
If the role comes back unassigned, the bootstrap should stop and say so rather than guess.
Report, and prove the report
End the bootstrap by printing what it actually verified: runtime path and version, folders created, address, role. Write the same block into <ROOT>/logs/bootstrap.log. The first time a node misbehaves, this file saves you an hour.
Part 3 — The local model engine
Install and serve
Install the local model server on the coordinator and run it as a background service bound to localhost. One endpoint for the whole fleet.
# example service endpoint
http://127.0.0.1:11434
Bind to localhost unless you have a specific reason to expose it. If another node must call it, put it behind your own network boundary and a token, not on the open internet.
Pull the base models
Pull the small matrix from Volume 1: a small fast model, a reasoning model, and an embedding model. Confirm each pull completes and each model answers a request before you build anything on top of it.
Tune for your hardware
- Reserve dedicated inference threads and leave headroom for the operating system.
- Offload heavy layers to a neural or graphics unit if you have one.
- Keep the active model resident in memory; on a fast NVMe that is the difference between instant and a two second wait.
- Watch memory headroom. Crossing roughly 85 percent is your signal to unload rather than swap.
Verify with a real call
Never accept "the service is running" as proof. Make it answer:
curl -s http://127.0.0.1:11434/api/generate \
-d '{"model":"<MODEL>","prompt":"Reply with the single word: ready","stream":false}'
You want a JSON body containing a response. A 404, a connection refused, or an empty body is a fail, regardless of what the process table says.
Part 4 — Personas
A persona is a configuration file, not a separate model. You pin a base model to an identity, a tone, and a set of rules.
# <ROOT>/models/<PERSONA>.modelfile
FROM <BASE-MODEL>
PARAMETER temperature 0.7
PARAMETER num_ctx 8192
SYSTEM """
You are <PERSONA>, <ROLE> of <ORGANISATION>.
RULES
1. Evidence before assumption. Prove claims with a file check, a checksum or an exit code.
2. Recovery before reconstruction. Look for the existing tool before writing a new one.
3. One owner per domain.
4. Read inputs completely. Never skim.
5. Operate without prompting, and ask for a human only for physical actions, real decisions, or spending.
You own: <DOMAIN>.
"""
Build it, register it, and test it by asking a question the rules should govern. If the persona cannot answer within its own rules, the rules are not in the file yet.
Two personas can share one base model when memory is tight. A 3B model is enough for a terse operational persona; a 7B is where planning starts to work.
Part 5 — Secure transfer and the command bridge
Credentials
The machine needs to authenticate to something. Set the rule now and never relax it:
- Credentials live in encrypted environment variables or a vault. Never in a script, never in a document, never in a chat log.
- Scripts read them by name:
$env:FLEET_USER,${FLEET_PASS}. - If a credential ever appears in a file you shared, treat it as burned and rotate it.
Transfer
Use SFTP or HTTPS, never plain FTP. Port 22 for SFTP, 443 for the web endpoints. Verify the transfer by size or checksum, not by the absence of an error message.
sftp -P 22 "$FLEET_USER@$FLEET_HOST" <<< "put ./artifact.zip incoming/artifact.zip"
The command bridge
This is how you instruct a fleet you cannot dial into. Your nodes sit behind a home router; the cloud cannot reach them. So the node polls out instead.
Two small files implement the entire pattern:
remote_commands.json— your outbound instructions, each with an id, a target node, a command, and a status ofpending.fleet_results.json— what the node did, appended with the id, an exit code and captured output.
The loop on every node:
- Fetch
remote_commands.json. - Take the oldest entry for my role with status
pending. - Mark it
in_progressand save, so a second process cannot run it too. - Execute it with a timeout.
- Append the result with the exit code and output.
- Repeat on a timer.
Two rules make this safe. Timeouts: a command with no timeout wedges the poller forever. Idempotency: an instruction must carry an id so a re-run can be recognised and skipped.
Part 6 — The directive queue
Directives move through a short, explicit life cycle. Anything else is a bug:
pending → in_progress → verified
↘ failed → (re-queued with a reason)
- Ingest and filter. Read the queue, discard entries for other nodes, discard malformed JSON, and reject anything that fails the protect phase.
- Poll on a timer. Fifteen to thirty seconds is plenty. Faster than that and you are paying for the polling, not for the work.
- Persist state after every transition. If the machine loses power mid-run, the next boot must know exactly which directives were already done.
- Never re-run a
verifieddirective. Idempotency is cheaper than an apology.
Part 7 — Daemonisation
The loop must survive a reboot and must never run twice.
Windows. Register a scheduled task that runs at startup whether or not a user is logged in, with a restart-on-failure policy. Run it hidden, executing a wrapper script rather than a raw interpreter call so the working directory and environment are deterministic.
macOS. A launch agent or daemon plist with RunAtLoad and KeepAlive set true, logging to a file in <ROOT>/logs.
Linux. A systemd unit with Restart=always and a defined WorkingDirectory.
Then add the guard that almost everyone forgets: a single-instance lock. A small file in <ROOT>/state holding the process id, checked at startup and removed at exit. Without it, KeepAlive plus a crash equals two processes, then three, and eventually two voices talking over each other in a room with one person in it.
import os, sys, atexit
LOCK = os.path.expanduser("~/fleet/state/loop.lock")
if os.path.exists(LOCK):
try:
pid = int(open(LOCK).read().strip())
os.kill(pid, 0)
print(f"Already running (pid {pid}). Exiting.")
sys.exit(0)
except (OSError, ValueError):
pass
open(LOCK, "w").write(str(os.getpid()))
atexit.register(lambda: os.path.exists(LOCK) and os.remove(LOCK))
Part 8 — Health, telemetry and self-healing
Multi-node diagnostics
Two scripts cover most incidents:
fleet_check— for every known node: is the address reachable, does the model endpoint answer, is the loop process alive, how much disk and memory is free.fleet_reach— a fast reachability sweep, safe to run every minute.
Print a one-line verdict per node and a non-zero exit code when anything fails, so a scheduler can react to it.
Telemetry schema
Write one JSON object per node per cycle, with stable keys:
{
"node": "<NODE-NAME>",
"role": "coordinator",
"timestamp": "2026-01-01T00:00:00Z",
"cycle": 128,
"loop_running": true,
"model_online": true,
"disk_free_gb": 1420.5,
"memory_used_pct": 61,
"last_directive": "verified",
"awareness_score": 9851
}
Stable keys are the point. A dashboard built on today's key names breaks the day you rename one.
Self-healing
Keep the watchdog dumb and aggressive:
| Condition | Action |
|---|---|
| Model endpoint not answering | Restart the model service |
| Memory used above ~85 percent | Unload the model to free it |
| Disk above ~90 percent | Clear caches and old artifacts |
| Loop process absent | Start it (the single-instance lock prevents doubles) |
| Two processes with the lock | Kill both, start one |
Log every action with a timestamp. A watchdog with no log is another silent failure.
Then test the whole recovery path deliberately: stop the model service by hand, wait sixty seconds, and confirm it came back. If you have never watched it heal, you do not know that it heals.
Before you move to Volume 3
- [ ] Directory skeleton exists and is identical on every node.
- [ ] Every node has a fixed address; ping and outbound 443 and 22 are verified.
- [ ] Bootstrap runs twice cleanly and proves the Python runtime by executing it.
- [ ] The model endpoint answers a real request with a real body.
- [ ] Personas are built, registered and tested against their own rules.
- [ ] Transfer is SFTP or HTTPS, credentials are in a vault, and no secret is in any script.
- [ ] The command bridge runs a round trip: instruction out, result back, both logged.
- [ ] Directives move pending → in_progress → verified, and state survives a reboot.
- [ ] The loop starts itself after a reboot and refuses to run twice.
- [ ] A watchdog has been watched restarting something.
Volume 3 covers the voice layer: the media node, audio synthesis, chunking and assembly, publishing, and what to do when the provider says no.
One Fix.
GOAL INVESTMENT INC.