docs/PREPARE_USB_FROM_ZERO.md

Prepare a JackAILocal USB drive from zero

Real product behavior

JackAILocal must be prepared before delivery or before offline use. The customer must not download models when the drive is inserted. Models are copied or downloaded during manufacturing, then read locally from the drive.

Normal customer flow:

insert the USB/SSD drive into Windows
open the drive
double-click START-HERE.cmd
JackAILocal starts locally
browser opens http://127.0.0.1:4891

Recommended hardware

Serious product minimum:

USB 3.2 SSD or external NVMe
128 GB minimum
256 GB recommended
separate SSD or dedicated image for Linux boot mode

Avoid cheap low-speed USB sticks. They increase first-load time and support cost.

Factory prerequisites

On the factory/build computer:

Windows 10/11
PowerShell 5+
Rust toolchain if building jackailocald.exe locally
Ollama Windows binary
llama.cpp llama-server.exe binary
Internet access only during preparation/model download

Prepare the backend cache

Recommended cache layout:

C:\\JackAILocalBackendCache\\
├── ollama.exe
└── llama-server.exe

Keep fixed, audited backend versions in the cache. Do not use floating versions for shipped drives.

Prepare the drive

powershell -ExecutionPolicy Bypass -File .\\factory\\powershell\\Prepare-JackAILocalUSB.ps1 `
  -TargetDrive "E:\\" `
  -BackendCache "C:\\JackAILocalBackendCache" `
  -ModelSet balanced

Options:

-ModelSet lite
-ModelSet balanced
-ModelSet full
-SkipModels
-SkipRustBuild
-UseSystemOllamaAsSource

Offline acceptance test

1. Disconnect the network or enable airplane mode.
2. Insert the prepared drive.
3. Run START-HERE.cmd.
4. Confirm that the UI opens.
5. Send a short chat prompt.
6. Open Models and confirm the catalog loads.
7. Open Support and prepare a report.
8. Confirm that no model download is attempted during normal use.

Expected customer-ready state

Required files:

START-HERE.cmd
bin\\jackailocald.exe
backends\\ollama\\windows\\ollama.exe
models\\ollama\\...
webui\\index.html
config\\model-catalog.json
manifest\\sha256-manifest.json

Do not ship a drive with placeholder backend files unless it is clearly labeled as a developer kit.

Claims to avoid

Do not claim:

automatic execution when inserted
zero trace on the Windows host
perfect GPU compatibility on every PC
unbreakable anti-copy protection

Safe claim:

Insert the drive, open it, double-click START-HERE, and use local AI without installation after the drive has been prepared.