Machine Build Manual — Volume 1: The Foundation
GOAL Investment Inc. · INSURED · BONDED · VERIFIED · EST. 2007
An educational build guide for a local-first machine fleet. This volume covers architecture, hardware selection, operating rules and the reasoning loop. Volumes 2 and 3 cover the build itself and the voice layer.
How to use this manual
This is a build guide, not a product manual for one company's equipment. Nothing in it depends on our hardware, our network, or our names. Where a value belongs to you, it appears as a placeholder in angle brackets, for example <COORD-IP>. Fill those in as you go, on paper or in a notebook you keep with the machine.
Your worksheet. Before you buy anything, copy this table and complete it. Every later chapter refers back to it.
| Role | Machine name (yours) | Address (yours) | Operating system | Job it owns |
|---|---|---|---|---|
| Coordinator | <COORD-NAME> |
<COORD-IP> |
<COORD-OS> |
Orchestration, model serving, master state |
| Operations | <OPS-NAME> |
<OPS-IP> |
<OPS-OS> |
Workflow execution, cross-platform checks |
| Media / Voice | <MEDIA-NAME> |
<MEDIA-IP> |
<MEDIA-OS> |
Audio, narration, external communication |
| Knowledge | <KNOW-NAME> |
<KNOW-IP> |
<KNOW-OS> |
Documentation, courses, verification |
Those four roles are the whole design. You can run them on four machines, on three, or on one strong machine with four isolated environments while you learn. The roles matter more than the count.
What this manual will not do. It will not publish anyone's network, credentials, or inventory. Anywhere this guide needs a credential, it tells you to store it in your own password manager and to reference it by name only. A manual that contains a working credential is a manual that has already leaked it.
Part 1 — What you are building
Most computer systems are passive. They sit still until a person clicks something or a request arrives. Your machine does exactly what it was told and nothing more.
This build is different. You are building a machine that is active:
- it wakes on a timer,
- it inspects its own condition,
- it looks for work it can do,
- it decides what to do about what it found,
- it does it with real tools,
- it proves the work happened,
- it records what it learned,
- and it goes back to sleep and does it again.
That loop, running unattended on your own hardware, is the entire foundation. Everything in Volumes 2 and 3 hangs off it.
Why local first
Four reasons, in order of how badly they will bite you:
- Cost control. A loop that runs every thirty seconds will bankrupt you on a metered cloud service. Local inference has a fixed cost: the hardware you already bought.
- Privacy. Your files, customer data, and medical or legal records should not cross someone else's network to be summarized. When the model runs on your desk, they do not.
- Resilience. When the internet drops, cloud-dependent machines stop being machines. A local fleet keeps working through an outage.
- Ownership. Weights on your disk cannot be repriced, deprecated, or switched off by a vendor.
The one rule that keeps this honest
A machine that reports success without proof is worse than a machine that reports failure. Every claim in this build has to be backed by evidence: a file that exists and is not zero bytes, a checksum that matches, a process return code, an HTTP status, a network response. Chapter 3 turns this into a written operating rule.
Part 2 — Eight operating rules
Write these down before you build anything. They are the constitution the machine is held to, and they are the reason an autonomous system stays useful instead of drifting.
- Revenue first. No engineering without a customer need or a cost that must be recovered. Building something impressive that nobody pays for is not progress.
- Evidence before assumption. Every report is backed by proof: a file check, a checksum, an exit code, a response code. A guess presented as a result is a fault.
- Recovery before reconstruction. Before writing a new tool, search for the one that already exists. If it half-works, repair it. Do not rebuild what you already own.
- One owner per domain. Every service, queue, folder and repository has exactly one machine or persona that owns it. Two owners means two versions of the truth and a race you will lose.
- Build once, reuse forever. Every script, module and checklist gets documented and published to a shared library the whole fleet can call.
- Cross-verification. A second node checks the work before it is committed. One node checking itself is not verification.
- No scan reading. Files, logs, and instructions are read completely. Skimming produces confident wrong answers, and confident wrong answers are the expensive kind.
- Full autonomy, with a hard boundary. The machine runs continuously and repairs itself. It asks for a human only when the next step requires hands in the physical world, a real decision, or money.
Rule 8 is the only one that needs an escape hatch, so give it one in writing: list what the machine may spend, which folders it may overwrite, and which actions require a signature.
Part 3 — Choosing and addressing the hardware
Assign roles, not brands
Plan the machine by what it does, then buy the cheapest hardware that does it well.
| Role | What it must do | Minimum you will regret going below |
|---|---|---|
| Coordinator | Serve local models, hold master state, run the loop | 32 GB RAM, fast NVMe, as many cores as you can afford |
| Operations | Run workflows, cross-verify, hold a warm backup model | 16 GB RAM, current silicon |
| Media / Voice | Synthesize and process audio, publish finished files | 16 GB RAM, generous disk |
| Knowledge | Store and index documentation, serve courses, run checks | 16 GB RAM, large storage |
What actually decides your speed
After building this four times, the order of importance is:
- Memory quantity. The model has to fit, with room left for the operating system. Running out produces swap, and swap turns a two second answer into a two minute one.
- Memory bandwidth. A fast memory path moves weights into the compute units quickly. This is the single most underrated spec on the box.
- Storage read speed. Model weights live on disk and are read at load time. A drive reading near 7,000 MB/s brings a cold model start from disk to memory in about a second; a spinning disk makes it a coffee break.
- Core count. Helps, but a high core count with thin memory bandwidth loses to a lower core count with wide memory.
- Accelerator. Any neural or graphics unit you have can take the heavy layers. If you have none, the machine will still run, just slower and with the fan on.
Addressing
Give the fleet fixed addresses. Dynamic addressing means a watchdog that hunts, and a watchdog that hunts is a watchdog that fails at the worst moment.
- Pick one private subnet for the whole build, for example
192.168.1.0/24. - Reserve a fixed address per role on your router so leases never move.
- Give the coordinator the lowest address and work upward.
- Record the address, name, and role in the worksheet from Chapter 0.
Then write the map somewhere your machine can read it, so a future you does not have to remember which box is which.
Naming
Name machines by role, not by hardware. Hardware gets replaced; roles do not. If you want the personas to feel alive later, name the personas and leave the machine names boring. You will thank yourself during an outage.
Part 4 — Performance tuning that pays for itself
Three settings produce most of the gain on current consumer hardware.
Thread allocation. Reserve a fixed number of worker threads for model inference and leave the rest for the operating system. Letting inference take every core produces thread contention: the model looks busy and answers slowly. On a sixteen core machine, sixteen dedicated workers is a good starting point; on smaller machines start lower and measure.
Hybrid offloading. If your chip has an integrated neural or graphics unit, offload the compute-heavy layers to it and leave the rest on the processor. This is a large win on sustained work such as code generation, and it costs you nothing but configuration.
Model residency. Keep the active model in memory rather than reloading it per request. With a fast drive and enough memory, a cold start of about a second is achievable; warm it is immediate. If memory is tight, unload the model deliberately between heavy batch jobs instead of letting the system swap.
Every one of these is a measurement, not a belief. Change one setting, run the same task, write down the time. A tuning guide that has not been measured is a rumor with numbers in it.
Part 5 — The seeking machine
The idea
Traditional software waits. A seeking machine looks.
The engine behind it is small: a state file, a log file, a local model endpoint, and a loop. In plain pseudocode:
load state
say hello
while true:
cycle += 1
inside = look at my own house # local disks, own data, own health
outside = look over the wall # network, remote queues, reachability
decision = ask the local model how inside and outside should meet
results = act on the decision with real tools
verify = prove the results and record them
save state
sleep
Nothing in that loop requires a cloud service. That is the point.
The inside loop: searching within the house
Point it at your own domain first. Sanity checks that catch most problems:
- Unprocessed data. Catalogs, spreadsheets, raw exports sitting in an inbox folder. The machine normalizes them.
- Broken tooling. Python files that no longer compile, missing environment variables, stale configuration. The machine opens a repair task.
- Stale documentation. A manual describing a version you no longer run. The machine queues an update.
The inside loop is where a fleet earns its keep, because these are the jobs nobody remembers to do.
The outside loop: searching outdoors
Then let it look outward: fetch the queue of pending instructions from your own endpoint, check that each node answers, report telemetry home. Keep this list short and deliberate. An outside loop with no boundaries becomes a crawler with no purpose.
Memory of its own condition
Store a state file and score it. Every verified success raises the awareness score; every unhandled failure lowers it and triggers a repair routine. The score is not decoration: it is how the machine knows the difference between "quiet" and "broken."
Part 6 — Local model infrastructure
The server
Run one local model server on the coordinator, bound to a local port, answering a standard API. Everything else in the fleet calls that port. Keeping one endpoint means one model matrix to maintain instead of four.
A model matrix, not a model
Standardize on a small set and give each a job:
| Class | Size | Use it for |
|---|---|---|
| Small and fast | ~3 B parameters, ~2 GB | Classification, status parsing, quick triage, light conversation |
| Reasoning | ~7 B parameters, ~5 GB | Code generation, architecture analysis, multi-step planning |
| Embedding | ~0.3 GB | Turning documents into vectors for search |
Small models fail at planning; large models are wasted on triage. Match the model to the job and your hardware will feel twice as capable.
Persona files
A persona is a small configuration file that pins a model to an identity: a system prompt, the rules from Part 2, the chain of command, and a temperature. Two personas can share one base model file. That is how you get distinct roles without paying for two large models.
Write the persona as data, not code. It should be readable by the person who has to change it at 2 a.m.
Context and temperature
Set context wide enough to swallow a whole document, not a fragment: 8,192 tokens is a practical floor if you want the machine to read a full manual rather than a paragraph of it. Keep temperature moderately low for operational work, where you want precision, and higher only for drafting prose.
Retrieval over a local store
For anything larger than a few documents, do retrieval rather than stuffing context:
- Chunk your documents.
- Embed each chunk with the embedding model.
- Store chunk text and vector in a local database table.
- At question time, embed the question, compare vectors, and prepend the closest chunks to the prompt.
That is a retrieval pipeline, and it is the difference between a machine that knows your files and one that invents plausible answers about them.
Part 7 — The ten-phase operations cycle
No task skips a phase. That discipline is the whole safety story.
- Gate. Check the incoming request against the rules and confirm the machine has authority to do it. Assign priority.
- Observe. Gather raw facts: disk space, load, active sockets, remote listings, queued files. No interpretation yet.
- Orient. Feed the observations through retrieval and local inference to build a picture of the situation.
- Plan. Break the goal into ordered concrete steps: commands, scripts, file changes.
- Protect. Check the plan against limits before running it: overwrite risk, disk space, spending ceiling, and how you would undo it.
- Execute. Run it. Capture standard output, standard error, and the exit code.
- Verify. Prove it, do not assume it: does the file exist, is it non-zero, does the checksum match, what did the endpoint return.
- Reflect. Grade the run. Was it slow, did it fail the same way twice, what should change next time.
- Record. Write the state and the audit row. If it is not recorded, it did not happen.
- Continue. Flush working memory, recalibrate the score, set the timer, loop.
Phases 5 and 7 are where beginners lose money. Protect is cheap; a bad overwrite is not. Verify is cheap; a false report is not.
Part 8 — Memory subsystems
Three layers, each with a different lifetime:
- Volatile working memory. In-process, used during a cycle, discarded in phase ten.
- Structured persistent memory. JSON and relational tables holding configuration, task state, and event history.
- Semantic vector memory. Embedded document chunks for fuzzy retrieval.
Two tables carry the weight. An audit table proves what happened:
CREATE TABLE IF NOT EXISTS audit_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
ts DATETIME DEFAULT CURRENT_TIMESTAMP,
node_id TEXT NOT NULL,
cycle INTEGER NOT NULL,
phase_name TEXT NOT NULL,
command TEXT,
exit_code INTEGER,
stdout TEXT,
stderr TEXT,
verification TEXT CHECK (verification IN ('verified','failed','pending'))
);
A vector table makes documents searchable:
CREATE TABLE IF NOT EXISTS vector_store (
id INTEGER PRIMARY KEY AUTOINCREMENT,
document TEXT NOT NULL,
chunk_index INTEGER NOT NULL,
chunk_text TEXT NOT NULL,
embedding BLOB NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
Define the valid state transitions in writing, and refuse every transition that is not on the list. A machine that cannot enter an undefined state cannot corrupt its own state.
Part 9 — Failover and self-healing
Design for the failure, not the demo.
No single owner of the loop. If the coordinator goes down for maintenance, the operations node picks up polling and model serving. Prove this by taking the coordinator offline on purpose, on a quiet afternoon.
Local caching. When the wide area network drops, all nodes keep running their cycles from local model endpoints and cached instructions. Test this by unplugging the router for an hour and reading the logs.
Watchdogs. A small scheduled task that runs every minute and checks that the services are alive. If a service stops answering, restart it. If memory utilization crosses roughly 85 percent, unload the model to free it. If the disk crosses 90 percent, clear caches. Keep a log, or the watchdog becomes another silent failure.
Duplicate processes. This is the one that will embarrass you. Every long-running service needs a single-instance lock file containing its process ID, checked at startup and removed at exit. Without it, a restart leaves two processes answering the same requests, and eventually two voices talking over each other.
Part 10 — Security and privacy
The rules that keep a build from becoming an incident:
- Credentials live in a vault or encrypted environment variables, never in code, never in a manual, never in a chat log. Reference them by name.
- Transfer encrypted. Use SFTP or HTTPS, never plain FTP. If a host offers plain FTP, treat the data as public.
- Keep secrets out of audio and documents. Anything you narrate, print, or publish can be downloaded. Grep your final product for addresses, usernames, and personal names before it ships.
- Separate identity from system. The persona that talks to customers should not be the identity that owns the infrastructure.
- Log the action, not the secret. Audit rows record the command and the result, never the password.
- Least privilege. A node that only reads a folder does not get write access to the rest of the machine.
Before you move to Volume 2
You are ready when all of the following are true:
- [ ] The worksheet is filled in: four roles, names, addresses, operating systems.
- [ ] Every machine has a fixed address and can reach the others.
- [ ] One local model server answers on the coordinator.
- [ ] The eight operating rules are written down where the machine can read them.
- [ ] You know what the machine may spend, overwrite, and publish.
- [ ] A watchdog exists and has been seen to restart something.
- [ ] Your state file and audit table exist and have at least one honest row in them.
Volume 2 covers the build itself: prerequisites, the directory blueprint, network validation, bootstrap scripts, the command queue, and deployment. Volume 3 covers the voice layer: audio production, narration, and publishing finished media.
One Fix.
GOAL INVESTMENT INC.