Machine Build Manual

Volume 2
The Build

Deployment, step by step. Preflight, bootstrap, the model engine, personas, secure transfer, the directive queue and health.

INSURED · BONDED · VERIFIED · EST. 2007
Volumes: 1 — The Foundation2 — The Build3 — The Voice

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:

  1. Fixed addresses. Reserve a static lease per role on your router. Confirm each node actually received it.
  2. Reachability. Ping every other node. You want zero loss. One flaky link will present itself later as a mysterious timeout in an unrelated script.
  3. Outbound access. Confirm HTTPS on 443 and SSH/SFTP on 22 leave your network. Test from each node, not just one.
  4. 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

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:

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:

The loop on every node:

  1. Fetch remote_commands.json.
  2. Take the oldest entry for my role with status pending.
  3. Mark it in_progress and save, so a second process cannot run it too.
  4. Execute it with a timeout.
  5. Append the result with the exit code and output.
  6. 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)

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:

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

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.