| # JackAILocal System Behavior |
|
|
| ## Layers |
|
|
| 1. The Gradio Builder accepts a real hardware profile, recommends compatible models, and exports manifests or builder packages. |
| 2. Platform builders prepare a local folder, USB drive, or external SSD and validate the resulting payload. |
| 3. `jackailocald` serves the WebUI and routes requests only to reachable local AI engines. |
|
|
| ## Runtime |
|
|
| The Rust runtime serves static WebUI files and these primary APIs: |
|
|
| ```text |
| GET /api/status |
| GET /api/features |
| GET /api/models |
| POST /v1/chat/completions |
| GET /api/threads |
| POST /api/threads |
| POST /api/threads/:id/messages |
| POST /api/vision/analyze |
| GET /api/voice/status |
| POST /api/voice/transcribe |
| POST /api/voice/synthesize |
| POST /api/packs/export |
| POST /api/packs/import |
| POST /api/agent/recommend |
| GET /api/phone |
| POST /api/phone |
| POST /api/runtime/restart |
| ``` |
|
|
| Chat and SCOUT use installed Ollama models. An OpenAI-compatible `llama.cpp` server can be used as an explicit local chat fallback. Voice uses whisper.cpp and Piper binaries and models stored in the package. |
|
|
| `POST /api/agent/recommend` adds a local LLM-in-the-loop for client configuration and model selection review. It uses only installed local models, enforces the <=32B catalog policy, prefers Gemma 4 12B (`gemma4:12b`) when present, and returns an explicit error when a requested agent model is unavailable. |
|
|
| The runtime reports a feature as available only when the required local engine and model are available. |
|
|
| ## Storage |
|
|
| ```text |
| workspace/threads/ conversation JSON files |
| workspace/documents/ user notes |
| workspace/settings/ local settings and phone pairing token |
| workspace/exports/ encrypted packs and support ZIPs |
| workspace/voice/ temporary voice files |
| workspace/scout/ SCOUT workspace |
| models/ollama/ Ollama model store |
| models/whisper/ speech-to-text models |
| models/piper/ text-to-speech models |
| ``` |
|
|
| Threads are persistent and support filtering, rename, and individual deletion. |
|
|
| ## Phone Access |
|
|
| The default bind is `127.0.0.1:4891`. Phone Access must be enabled explicitly. After restart, the runtime binds to `0.0.0.0:4891`, generates a LAN URL and QR code, and requires `X-JackAILocal-Token` for non-loopback API requests. |
|
|
| ## Transfer Packs |
|
|
| Transfer packs use AES-256-GCM with PBKDF2-HMAC-SHA256. Passphrases are not stored. Imported settings are sanitized so a pack cannot silently enable Phone Access or transfer a pairing token. |
|
|
| ## Builders |
|
|
| Builders install selected Ollama models, install Voice assets, generate a SHA-256 manifest, and refuse success when required files are missing. The source package and target path must not overlap. |
|
|
| ## Offline Boundary |
|
|
| Normal use does not require internet after models and Voice assets are present. The runtime has no cloud inference fallback. A capability that cannot run locally returns an explicit unavailable or error response. |
|
|
