Cross-platform Vox — runbook

This page ties together how Vox is meant to run on servers, generated apps, and mobile-adjacent clients. It complements deployment compose SSOT, mobile / edge AI SSOT, and mens SSOT.

Lane S — Server script / worker

• Entry: vox run --mode script on a path to a .vox file with a fn main()-style script surface.
• Binary: vox-cli must be built with feature script-execution (see CLI scope policy).
• Mens registry (optional): build with Cargo feature populi (links vox-populi). When VOX_MESH_ENABLED is set, vox run publishes to the local mens registry and may HTTP-join the control plane (same env as MCP). Implementation: mesh_publish_best_effort_for_run calls publish_local_registry_best_effort and populi_http_join_best_effort.
• Compose: examples/mens-compose.yml uses vox run --mode script for the worker service with a shared volume and mens control plane.

Lane A — App / generated server

• Entry: vox run in app mode (default auto-detection or RunMode::App): compiler pipeline + generated server under target/generated (see Vox full-stack web UI SSOT).
• Deploy: vox deploy / vox-container and Compose emission — deployment compose SSOT.

Lane M — Mobile native

• No vox binary on stock iOS/Android for full language stack or Ollama; see mobile / edge AI SSOT.
• Mens: native apps act as HTTP clients: register via POST /v1/populi/join with a NodeRecord, using the same VOX_MESH_* / control URL conventions as servers.
• Inference: set VOX_INFERENCE_PROFILE (e.g. mobile_litert, cloud_openai_compatible) so MCP-compatible tooling does not assume desktop Ollama on loopback.

Lane R — Remote mobile workspace client

• Entry: phone browser or mobile shell connects to a remote Vox host over authenticated network APIs.
• Role: planning/chat, bounded edits, validation, and orchestrator monitoring happen remotely; the phone is a client, not the toolchain host.
• Host requirement: the remote host owns repo checkout, Cargo/git/tooling, .vox/cache, and long-lived MCP/orchestrator processes.
• Non-goal: Lane R does not imply on-device parity with vox CLI or full server-script runtime semantics.

WASM clarification

WASI / Wasmtime (vox run --isolation wasm on a workstation) is not the same as in-browser WebGPU + WASM. Browser tiers are optional and policy-gated; see mobile / edge AI SSOT (browser row).

Docker image / feature matrix

Images are operator-defined tags unless your registry publishes blessed names. The table below is the documentation convention aligned with the repo Dockerfile and examples/mens-compose.yml.

• Sidecar: VOX_MESH_MESH_SIDECAR=1 + infra/containers/entrypoints/vox-entrypoint.sh can run vox populi serve beside vox mcp in one container; see Dockerfile comments and deployment compose SSOT.
• CI smoke tags: default vox:ci-smoke; mens/features matrix vox:ci-mens and vox:ci-mens-worker (same image, two names) — .github/workflows/ci.yml.

Env-over-features

Prefer runtime environment when behavior is already gated in-tree:

• Mens: VOX_MESH_ENABLED, VOX_ORCHESTRATOR_MESH_CONTROL_URL, VOX_MESH_HTTP_JOIN, VOX_MESH_TOKEN, etc. — mens SSOT.
• Inference / routing: VOX_INFERENCE_PROFILE — mobile / edge AI SSOT, environment variables SSOT.

Rebuild with different VOX_CLI_FEATURES only when you need code paths that are not linked in the default binary (e.g. mens, script-execution).

Related

• Deployment compose SSOT
• Mens SSOT
• Mobile / edge AI SSOT
• Vox full-stack web UI SSOT