Concepts

Embedded intent inference

JoyMux ships a self-contained local understanding layer. A normal install must not require Ollama, llama.cpp, ONNX Runtime, Python, Node.js, model servers, or manual model downloads before basic natural-language understanding works.

Architecture rule

JoyMux production startup must not depend on Ollama.

Ollama and OpenAI-compatible local endpoints may exist as development-only backends. They are never the production default and must not appear in normal onboarding.

Boundary

User request
    ↓
JoyMux embedded inference runtime
    ↓
Typed ActionIntent
    ↓
Deterministic policy and security checks
    ↓
Execution instruction compiler (guidance text only)
    ↓
JoyMesh handoff / external harness connects
    ↓
Execution events and result (when a harness attaches)
    ↓
JoyMux monitor and checkpoint

The embedded model is not a coding harness. It does not install software, execute shell commands, select unsafe commands, grant permissions, choose a coding harness, or own JoyMesh routing. JoyMux never selects an AI reasoning harness; JoyMesh / external clients attach.

Backends

Kind	Role
`embedded`	Production default. In-process specialised constrained model and/or private `joymux-inference` helper.
`fake`	Deterministic tests.
`ollama_dev`	Optional development only.
`openai_compatible_dev`	Optional development only.

Private helper protocol

When packaged as a helper process, JoyMux owns lifecycle:

ships with JoyMux;
stdin/stdout JSON, one request/response;
no public port;
no daemon setup;
shuts down with the parent invocation;
unknown fields rejected;
operations limited to extract_action_intent, summarize_monitor_facts, ping.

Model assets

Managed under $JOYMUX_DATA_DIR/models:

current/ active model blob + manifest
previous/ last-known-good for rollback
model-record.json runtime/model versions and checksums

Install is atomic (temp + rename). Checksum mismatches mark the model corrupted and allow rollback. Optional GGUF neural weights in the 100M–600M class may be bundled or first-run downloaded with disclosure, approval, checksum verification, and resume support. Offline use keeps the specialised/last-known-good path.

Readiness

ready, loading, model_missing, model_corrupted, runtime_unavailable, unsupported_platform, fallback_only.

The UI/CLI may open immediately. Deterministic parsing covers obvious requests while the model loads.

CLI

joymux ask "Install OpenClaw for me."
joymux model status|verify|repair|info
joymux doctor

Normal users are not required to run model or doctor commands during successful onboarding.