diff --git a/.github/workflows/v2-ci.yml b/.github/workflows/v2-ci.yml
index ed57da8313..bd34ef89c7 100644
--- a/.github/workflows/v2-ci.yml
+++ b/.github/workflows/v2-ci.yml
@@ -905,6 +905,7 @@ jobs:
node --check bin/lib/pane-classifier.js
bash -n bin/contributor-relay.sh
node bin/contributor-relay.test.js
+ node --test bin/mlx-backend.test.js
# bin/vibe-kanban-mirror.js (#10641): report-only hive → vibe-kanban
# mirror, exercised against a fake MCP stdio server.
diff --git a/Justfile b/Justfile
index 8b3825a7bf..583b09eba2 100644
--- a/Justfile
+++ b/Justfile
@@ -37,6 +37,53 @@ contributor_cpu_limit := "2"
default:
@just --list
+# Explicitly verifies streaming tool calls against an already-running local
+# MLX-LM server, then persists only Pi's mlx provider. Never downloads weights.
+[positional-arguments]
+contribute-mlx-setup model verify:
+ node bin/mlx-backend.js configure "$1" "$2"
+
+# Starts only an explicitly chosen, already-downloaded model on Mac loopback.
+[positional-arguments]
+contribute-mlx-serve model:
+ node bin/mlx-backend.js serve "$1"
+
+# Apple MLX is an inference engine for Pi, not a separate coding CLI.
+[positional-arguments]
+contribute-mlx mode="docker":
+ #!/usr/bin/env bash
+ set -euo pipefail
+ _MLX_REQUESTED_MODEL="${AGENT_MODEL:-}"
+ _MLX_REQUESTED_RUNTIME="${HIVE_CONTAINER_RUNTIME:-}"
+ if [[ -f "{{config_dir}}/contributor.env" ]]; then
+ source "{{config_dir}}/contributor.env"
+ fi
+ if [[ -n "$_MLX_REQUESTED_MODEL" ]]; then
+ AGENT_MODEL="$_MLX_REQUESTED_MODEL"
+ fi
+ if [[ -n "$_MLX_REQUESTED_RUNTIME" ]]; then
+ HIVE_CONTAINER_RUNTIME="$_MLX_REQUESTED_RUNTIME"
+ fi
+ if [[ "${AGENT_MODEL:-}" != mlx/* ]]; then
+ echo "ERROR: Select your verified MLX model first: export AGENT_MODEL=mlx/"
+ echo " Setup: just contribute-mlx-setup --verify-tools"
+ exit 1
+ fi
+ case "$1" in
+ docker)
+ if [[ "${HIVE_CONTAINER_RUNTIME:-docker}" != "docker" ]]; then
+ echo "ERROR: Apple MLX requires Docker Desktop 4.34+ host networking, not Podman machine."
+ exit 1
+ fi
+ export HIVE_CONTAINER_RUNTIME=docker
+ ;;
+ local) ;;
+ *) echo "ERROR: MLX mode must be docker or local; Kubernetes cannot reach Mac loopback."; exit 1 ;;
+ esac
+ export AGENT_MODEL
+ export HIVE_MLX_LAUNCH_MODEL="$AGENT_MODEL"
+ just --justfile "{{justfile_directory()}}/Justfile" contribute-hive pi "$1"
+
# Run the live run-level acceptance test (#8466 layer 2). Requires HIVE_URL and
# HIVE_TOKEN like the rest of src/test, plus HIVE_RUNS_E2E_KEY or
# HIVE_RUNS_E2E_REPO/HIVE_RUNS_E2E_ISSUE for the pinned run/spec issue.
@@ -178,6 +225,9 @@ contribute-check-backend backend="claude":
exit 1
fi
echo "HIVE_BACKEND_READINESS=${PI_READINESS}"
+ if [[ "${AGENT_MODEL}" == mlx/* ]]; then
+ node bin/mlx-backend.js check "${AGENT_MODEL}"
+ fi
echo " Credential presence is reported as configured_unverified, never as proof of authentication."
else
echo "ERROR: Pi CLI not found. Install: curl -fsSL https://pi.dev/install.sh | sh"
@@ -925,6 +975,7 @@ contribute-hive backend="" mode="docker": check-version
echo "Not set up yet. Run: just contribute-setup "
exit 1
fi
+ _MLX_LAUNCH_MODEL="${HIVE_MLX_LAUNCH_MODEL:-}"
set -a
source "{{config_dir}}/gh-auth.env"
source "{{config_dir}}/contributor.env"
@@ -957,6 +1008,16 @@ contribute-hive backend="" mode="docker": check-version
BACKEND="${AGENT_BACKEND:-claude}"
fi
export AGENT_BACKEND="$BACKEND"
+ # MLX-only launch override: preserve an explicit selection over saved profiles.
+ if [[ -n "${_MLX_LAUNCH_MODEL:-}" ]]; then
+ if [[ "$BACKEND" != "pi" || "$_MLX_LAUNCH_MODEL" != mlx/* ]]; then
+ echo "ERROR: MLX launcher requires the Pi backend and an mlx/ selection."
+ exit 1
+ fi
+ export AGENT_MODEL="$_MLX_LAUNCH_MODEL"
+ fi
+ unset HIVE_MLX_LAUNCH_MODEL _MLX_LAUNCH_MODEL
+ # End MLX-only launch override.
# Bob has no headless credential other than its API key — without it the
# agent would launch and sit at Bob's key prompt forever. Fail fast.
if [[ "$BACKEND" == "bob" && -z "${BOB_API_KEY:-}" && -z "${BOBSHELL_API_KEY:-}" ]]; then
@@ -972,6 +1033,9 @@ contribute-hive backend="" mode="docker": check-version
exit 1
fi
echo "HIVE_BACKEND_READINESS=${PI_READINESS}"
+ if [[ "${AGENT_MODEL}" == mlx/* ]]; then
+ node bin/mlx-backend.js check "${AGENT_MODEL}"
+ fi
# This recipe runs in its own shell, so narrowing the environment does not
# alter the contributor's login shell. It does ensure both local relay/CLI
# launches and the container path can see only the selected provider's
@@ -1276,6 +1340,9 @@ contribute-hive backend="" mode="docker": check-version
# Same canonical selection used by the container entrypoint and every
# relay restart. %q keeps model IDs with shell metacharacters one argv.
PERM_FLAG="${PERM_FLAG:+${PERM_FLAG} }--model $(printf %q "$AGENT_MODEL")"
+ if [[ "$AGENT_MODEL" == mlx/* ]]; then
+ PERM_FLAG+=" --extension $(printf %q "{{justfile_directory()}}/bin/mlx-pi-extension.js")"
+ fi
fi
# Create tmux session with the CLI.
@@ -1683,6 +1750,11 @@ contribute-hive backend="" mode="docker": check-version
fi
;;
pi)
+ if [[ "${AGENT_MODEL:-}" == mlx/* && "$(uname -s)" == "Darwin" && "$RUNTIME" != "docker" ]]; then
+ echo "ERROR: MLX container mode on macOS requires Docker Desktop 4.34+ with host networking enabled."
+ echo " Podman machine host networking reaches its Linux VM, not the Mac's loopback MLX server."
+ exit 1
+ fi
if [ -d "${HOME}/.pi" ]; then
stage_copy "${HOME}/.pi" ".pi"
# Keep only the selected provider's official auth/custom-provider
diff --git a/bin/README.md b/bin/README.md
index 256076be69..7c79a7607b 100644
--- a/bin/README.md
+++ b/bin/README.md
@@ -88,6 +88,8 @@ Most production scripts are installed under `/usr/local/bin` by `bin/hive-deploy
| `contributor-quota-control.js` | Contributor runtime | Out-of-band contributor quota override command (#6953). The relay usually runs detached (background, container, K8s pod), so #6833's scoped overrides cannot depend on its stdin; this writes `continue-once` / `continue-until-reset` / `disable-session` / `pause-until-reset` / `resume` overrides into the same per-pool directory (`lib/quota-pool-store.js`) the relay reads on every guard evaluation. Stores only the relay's own published hold state — never a provider credential, raw account identifier, or billing figure. |
| `lib/quota-pool-store.js` | Contributor runtime | Shared per-pool quota-override store used by both `contributor-relay.js` (guard evaluation) and `contributor-quota-control.js` (override writes), so the attached banner and the out-of-band command share exactly one mechanism with no second code path to drift (#6953). |
| `pi-backend.js` | Contributor runtime | Pi contributor adapter contract (#5039). `AGENT_MODEL` is the one contributor-owned selection input; the adapter derives the provider's official credential variable names from it so only the selected provider's keys are handed to the container. |
+| `mlx-backend.js` | Optional local inference | Apple Silicon runtime/config checks, explicit tool-call verification and offline loopback server launch for Pi's `mlx` provider. Use `just contribute-mlx-serve`, `just contribute-mlx-setup --verify-tools`, then `just contribute-mlx`; see [MLX setup](../src/docs/contributor-relay.md#apple-mlx-local-inference). No automatic installation or model downloads. |
+| `mlx-pi-extension.js` | Optional local inference | Delegates streaming/tools to Pi's maintained OpenAI adapter with a loopback-only, redirect-rejecting transport; required for the private `hive-mlx` API. |
| `omp-backend.js` | Contributor runtime | omp (Oh My Pi) contributor adapter (#7678). Container mode stages the host's omp sign-in — `~/.omp/agent/config.yml` plus the `agent.db` SQLite store whose `auth_credentials` rows hold every provider's OAuth record or API key; omp has no `auth.json` — into the ephemeral CLI staging dir and, like `pi-backend.js --stage`, keeps only the selected provider's rows (`AGENT_MODEL=provider/model`, else `config.yml`'s `modelRoles`). `--describe` is what `just contribute-setup omp` prints so a missing host sign-in is caught before a container opens on omp's setup wizard. `--stage` and `--describe` refuse/flag a row omp has marked `disabled_cause` (a revoked OAuth refresh), and `--sync-back` writes a credential the container refreshed back over the host row it was staged from — only the selected provider's existing row, only when strictly newer — so a single-use refresh token consumed in the container does not strand the host; `just contribute-hive omp` runs it every `HIVE_OMP_CREDENTIAL_SYNC_SECONDS` (default 300) while the container runs and once more at exit (#7922). |
## Model, token, and experiment helpers
diff --git a/bin/contributor-agent.sh b/bin/contributor-agent.sh
index db443734bf..d8de168717 100755
--- a/bin/contributor-agent.sh
+++ b/bin/contributor-agent.sh
@@ -618,6 +618,9 @@ if [[ "${HIVE_CONTRIBUTOR_AGENT_TEST_LINK_KNOWLEDGE:-}" == "1" ]]; then
fi
validate_pi_selection() {
+ if [[ "${AGENT_MODEL:-}" == mlx/* ]]; then
+ node "${SCRIPT_DIR}/mlx-backend.js" check "${AGENT_MODEL}" --endpoint-only >&2 || return
+ fi
node "${SCRIPT_DIR}/pi-backend.js" "${AGENT_MODEL:-}"
}
@@ -1149,6 +1152,9 @@ if [[ -n "${AGENT_MODEL:-}" ]]; then
*) MODEL_FLAG="--model $AGENT_MODEL" ;;
esac
fi
+if [[ "$AGENT_BACKEND" == "pi" && "${AGENT_MODEL:-}" == mlx/* ]]; then
+ MODEL_FLAG+=" --extension $(printf %q "${SCRIPT_DIR}/mlx-pi-extension.js")"
+fi
REASONING_FLAG=""
if [[ "$AGENT_BACKEND" == "codex" && -n "${AGENT_REASONING_EFFORT:-}" ]]; then
REASONING_FLAG="-c 'model_reasoning_effort=\"${AGENT_REASONING_EFFORT}\"'"
diff --git a/bin/contributor-relay.js b/bin/contributor-relay.js
index 050826be0e..52b5741c8f 100755
--- a/bin/contributor-relay.js
+++ b/bin/contributor-relay.js
@@ -47,6 +47,7 @@ const {
redactPiCredentials,
piReadiness,
} = require('./pi-backend.js');
+const { checkRuntime: checkMlxRuntime } = require('./mlx-backend.js');
// Pure pane-classification (kubestellar/hive#6429): readiness/login/onboarding
// tables, the busy/idle/blocked/error state machine, the blocked-on-human
// reason breakdown, the modal-dismiss keystroke table, and the pane-tail/
@@ -3224,6 +3225,10 @@ function resolveBackendShell() {
// play — agy's effort is conditional on exactly that.
function modelFlagFor() {
if (BACKEND === 'pi' && !PI_SELECTION.valid) throw new Error(PI_SELECTION.error);
+ if (BACKEND === 'pi') checkMlxRuntime(MODEL, PI_ENV);
+ if (BACKEND === 'pi' && PI_SELECTION.provider === 'mlx') {
+ return `--model ${MODEL} --extension ${shellQuote(path.join(__dirname, 'mlx-pi-extension.js'))}`;
+ }
return MODEL && !NO_MODEL_FLAG_BACKENDS.includes(BACKEND) ? `--model ${MODEL}` : '';
}
@@ -3919,6 +3924,7 @@ function buildHeadlessArgv(prompt) {
const spec = HEADLESS_BACKENDS[BACKEND];
if (!spec) return null;
if (BACKEND === 'pi' && !PI_SELECTION.valid) throw new Error(PI_SELECTION.error);
+ if (BACKEND === 'pi') checkMlxRuntime(MODEL, PI_ENV);
const { cmd, perm } = resolveBackend();
const permArgs = perm ? perm.split(/\s+/).filter(Boolean) : [];
const modelArgs = MODEL && !NO_MODEL_FLAG_BACKENDS.includes(BACKEND) ? ['--model', MODEL] : [];
@@ -3937,7 +3943,9 @@ function buildHeadlessArgv(prompt) {
const claudeEffortArgs = BACKEND === 'claude' && effectiveReasoningEffort()
? ['--effort', effectiveReasoningEffort()]
: [];
- const flagArgs = [...permArgs, ...modelArgs, ...reasoningArgs, ...agyEffortArgs, ...museEffortArgs, ...claudeEffortArgs];
+ const mlxArgs = BACKEND === 'pi' && PI_SELECTION.provider === 'mlx'
+ ? ['--extension', path.join(__dirname, 'mlx-pi-extension.js')] : [];
+ const flagArgs = [...permArgs, ...modelArgs, ...mlxArgs, ...reasoningArgs, ...agyEffortArgs, ...museEffortArgs, ...claudeEffortArgs];
// Sub-command-first CLIs parse their options on the sub-command, not the
// root binary, so the one-shot token has to lead (see flagsAfterCommand).
const args = spec.flagsAfterCommand
@@ -9901,6 +9909,15 @@ if (process.env.HIVE_RELAY_TEST_MODE === '1') {
}
process.exit(1);
}
+ if (BACKEND === 'pi') {
+ try { checkMlxRuntime(MODEL, PI_ENV); } catch (error) {
+ console.error(`FATAL: ${error.message}`);
+ if (CONTRIBUTOR_MODE === MODE_HEADLESS) {
+ writeHeadlessStatus(HEADLESS_STATE_FAILED, { result: 'failed', reason: error.message });
+ }
+ process.exit(1);
+ }
+ }
// Warm the capability cache BEFORE the first hub connection. detectCapabilities()
// is called from the auth_challenge handler, and the hub bounds a handshake at
// 30s (wsAuthTimeout); doing the probes here keeps every one of them — backend
diff --git a/bin/contributor-relay.test.js b/bin/contributor-relay.test.js
index 7c90e9883b..e979b8dc92 100644
--- a/bin/contributor-relay.test.js
+++ b/bin/contributor-relay.test.js
@@ -34,7 +34,7 @@ const RELAY_PATH = path.join(__dirname, 'contributor-relay.js');
// bash and no WebSocket are ever touched.
// ---------------------------------------------------------------------------
-function loadRelay({ backend = 'copilot', backendBinary = null, backendPerm = '--allow-all', backendPermShell = null, model = '', reasoningEffort = '', cliStates = ['ready'], procAlive = true, mode = 'interactive', execFileResult = null, statusFile = null, paneText = null, env = null, cliVersion = null, attachedClients = false, attachedIdleMs = 0, clientActivityRaw = null, listClientsThrows = false, prMeta = null, sessionMissing = false, newSessionFails = false, gitStatus = '', ghIssueEditFailures = 0 } = {}) {
+function loadRelay({ backend = 'copilot', backendBinary = null, backendPerm = '--allow-all', backendPermShell = null, model = '', reasoningEffort = '', cliStates = ['ready'], procAlive = true, mode = 'interactive', execFileResult = null, statusFile = null, paneText = null, env = null, cliVersion = null, attachedClients = false, attachedIdleMs = 0, clientActivityRaw = null, listClientsThrows = false, prMeta = null, sessionMissing = false, newSessionFails = false, gitStatus = '', ghIssueEditFailures = 0, mlxPreflightError = null } = {}) {
const commands = [];
// #7924: how many `gh issue edit` calls fail before one succeeds — models a
// label the repository does not define (the first add fails, the relay
@@ -253,6 +253,11 @@ function loadRelay({ backend = 'copilot', backendBinary = null, backendPerm = '-
};
const stubs = {
+ './mlx-backend.js': {
+ checkRuntime(raw) {
+ if (raw.startsWith('mlx/') && mlxPreflightError) throw mlxPreflightError;
+ },
+ },
child_process: {
execSync: fakeExecSync,
execFile: fakeExecFile,
@@ -2334,6 +2339,51 @@ test('Pi revoke kills the child and rejects a raced stale completion', () => {
} finally { teardown(relay); }
});
+test('MLX uses the real Pi task argv, model receipts and cancellation contract', () => {
+ const model = 'mlx/mlx-community/tool-coder-4bit';
+ const relay = loadRelay({ backend: 'pi', backendPerm: '', mode: 'headless', model, cliVersion: 'pi 1.4.0' });
+ try {
+ assert.deepStrictEqual(relay.buildHeadlessArgv('edit and test').args,
+ ['--model', model, '--extension', path.join(__dirname, 'mlx-pi-extension.js'), '--print', '--mode', 'json', 'edit and test']);
+ const task = { task_id: 'mlx-1', task_gen: 17, kind: 'issue', repo: 'x/y', number: 1, title: 'MLX' };
+ relay.setCurrentTask(task);
+ relay.runHeadlessTask(task);
+ const complete = relay.__sent.find(m => m.type === 'task_complete');
+ assert.ok(complete);
+ assert.strictEqual(complete.cli_backend, 'pi');
+ assert.strictEqual(complete.provider, 'mlx');
+ assert.strictEqual(complete.model, model);
+ } finally { teardown(relay); }
+ const waiting = loadRelay({ backend: 'pi', mode: 'headless', model, cliVersion: 'pi 1.4.0', execFileResult: { defer: true } });
+ try {
+ const task = { task_id: 'mlx-cancel', task_gen: 18, kind: 'issue', repo: 'x/y', number: 2, title: 'cancel' };
+ waiting.setCurrentTask(task);
+ waiting.runHeadlessTask(task);
+ const child = waiting.getHeadlessChild();
+ waiting.handleMessage(JSON.stringify({ type: 'task_revoke', task_id: task.task_id, reason: 'operator stop' }));
+ assert.strictEqual(child.killed, true);
+ waiting.__completeDeferredExecFile(null, 'late success', '');
+ assert.ok(!waiting.__sent.some(m => m.type === 'task_complete'));
+ } finally { teardown(waiting); }
+});
+
+test('MLX endpoint failure refuses execution rather than falling back to a hosted Pi model', () => {
+ const relay = loadRelay({
+ backend: 'pi', mode: 'headless', model: 'mlx/mlx-community/tool-coder-4bit',
+ mlxPreflightError: new Error('MLX local endpoint request failed'),
+ });
+ try {
+ assert.throws(() => relay.buildHeadlessArgv('edit'), /local endpoint/);
+ assert.throws(() => relay.buildLaunchCommand(), /local endpoint/);
+ const task = { task_id: 'mlx-fail', task_gen: 19, kind: 'issue', repo: 'x/y', number: 3, title: 'fail' };
+ relay.setCurrentTask(task);
+ relay.runHeadlessTask(task);
+ assert.ok(relay.__sent.some(m => m.type === 'task_failed'));
+ assert.ok(!relay.__sent.some(m => m.type === 'task_complete'));
+ assert.ok(!relay.__execFileCalls.some(call => call.bin === 'pi'), 'failed MLX preflight must not start a coding agent');
+ } finally { teardown(relay); }
+});
+
// ---------------------------------------------------------------------------
// hivecommons/hive#7778 — a headless task must keep renewing the hub's progress
// lease while its child is alive.
diff --git a/bin/mlx-backend.js b/bin/mlx-backend.js
new file mode 100644
index 0000000000..c3f8f7e169
--- /dev/null
+++ b/bin/mlx-backend.js
@@ -0,0 +1,310 @@
+'use strict';
+
+// MLX-LM supplies inference; Pi supplies the coding tools and task lifecycle.
+// Only the explicit serve command starts a server; nothing installs packages
+// or downloads weights.
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { createHash } = require('crypto');
+const { parsePiModelSelection } = require('./pi-backend.js');
+
+const DEFAULT_ENDPOINT = 'http://127.0.0.1:8080/v1';
+const HTTP_TIMEOUT_MS = 10000;
+const PROBE_TIMEOUT_MS = 120000;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const PROBE_MAX_TOKENS = 256;
+const DEFAULT_CONTEXT = 8192;
+const DEFAULT_MAX_TOKENS = 2048;
+const DEFAULT_HTTP_PORT = '80';
+const PROBE_VALUE = 'hive_mlx_tool_check';
+const COMPAT = Object.freeze({
+ supportsStore: false,
+ supportsDeveloperRole: false,
+ supportsReasoningEffort: false,
+ maxTokensField: 'max_tokens',
+});
+
+function endpointURL(raw) {
+ let url;
+ try { url = new URL(raw); } catch (_) { throw new Error('MLX endpoint must be http://127.0.0.1:/v1'); }
+ // Literal loopback only: no DNS resolution, credentials, redirects or public
+ // listeners. Docker Desktop host networking keeps this exact host boundary.
+ if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname) ||
+ url.username || url.password || url.search || url.hash || !/^\/v1\/?$/.test(url.pathname)) {
+ throw new Error('MLX requires a literal loopback HTTP endpoint ending in /v1; never expose MLX-LM publicly');
+ }
+ return url.href.replace(/\/$/, '');
+}
+
+function validatePlatform(info) {
+ if (info.platform !== 'darwin' || info.arch !== 'arm64') {
+ throw new Error('Apple MLX requires a native arm64 process on an Apple Silicon Mac; Intel, Rosetta and Linux hosts are unsupported');
+ }
+ if (Number(String(info.macos).split('.')[0]) < 14 || !/^\d+\./.test(info.macos)) {
+ throw new Error('Apple MLX requires macOS 14 or newer');
+ }
+ if (info.pythonArch !== 'arm64' || info.pythonPlatform !== 'darwin') {
+ throw new Error('MLX Python must run natively on Apple Silicon, not under Rosetta; select it with HIVE_MLX_PYTHON');
+ }
+ const [major, minor] = info.pythonVersion || [];
+ if (!(major > 3 || (major === 3 && minor >= 10))) {
+ throw new Error('MLX requires native Python >=3.10; select your virtualenv Python with HIVE_MLX_PYTHON');
+ }
+ if (!info.mlx || !info.mlxLM) {
+ throw new Error('MLX/MLX-LM is missing in HIVE_MLX_PYTHON; install mlx-lm in your own virtualenv (no global pip install)');
+ }
+ return info;
+}
+
+function hostInfo(env = process.env) {
+ if (process.platform !== 'darwin' || process.arch !== 'arm64') {
+ throw new Error('Apple MLX requires a native arm64 process on an Apple Silicon Mac; Intel, Rosetta and Linux hosts are unsupported');
+ }
+ let python;
+ try {
+ // Metadata only: importing mlx can initialize the GPU.
+ python = JSON.parse(execFileSync(env.HIVE_MLX_PYTHON || 'python3', ['-c', [
+ 'import sys, platform, json, importlib.metadata as m',
+ 'def version(name):',
+ ' try: return m.version(name)',
+ ' except m.PackageNotFoundError: return None',
+ 'print(json.dumps(dict(pythonArch=platform.machine(), pythonPlatform=sys.platform, pythonVersion=list(sys.version_info[:2]), mlx=version("mlx"), mlxLM=version("mlx-lm"))))',
+ ].join('\n')], { encoding: 'utf8', timeout: HTTP_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] }));
+ } catch (_) {
+ throw new Error('Cannot inspect MLX Python; set HIVE_MLX_PYTHON to your native Python >=3.10 virtualenv executable');
+ }
+ return validatePlatform({
+ ...python,
+ platform: process.platform,
+ arch: process.arch,
+ macos: process.platform === 'darwin'
+ ? execFileSync('sw_vers', ['-productVersion'], { encoding: 'utf8', timeout: HTTP_TIMEOUT_MS }).trim() : '',
+ });
+}
+
+async function request(endpoint, route, body, timeout = HTTP_TIMEOUT_MS, fetcher = fetch) {
+ const url = endpointURL(endpoint);
+ try {
+ const response = await fetcher(`${url}/${route}`, {
+ method: body ? 'POST' : 'GET',
+ headers: body ? { 'Content-Type': 'application/json' } : {},
+ ...(body ? { body: JSON.stringify(body) } : {}),
+ signal: AbortSignal.timeout(timeout),
+ redirect: 'error',
+ });
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ const reader = response.body.getReader();
+ const chunks = [];
+ let size = 0;
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ size += value.length;
+ if (size > MAX_RESPONSE_BYTES) throw new Error('response exceeds safety limit');
+ chunks.push(Buffer.from(value));
+ }
+ } finally { await reader.cancel(); }
+ return Buffer.concat(chunks).toString('utf8');
+ } catch (error) {
+ throw new Error(`MLX local endpoint request failed (${error.name === 'TimeoutError' ? 'timed out' : error.message}); start your MLX-LM server and check Docker Desktop host networking if containerized`);
+ }
+}
+
+async function availableModels(endpoint, fetcher) {
+ const body = JSON.parse(await request(endpoint, 'models', null, HTTP_TIMEOUT_MS, fetcher));
+ if (!Array.isArray(body.data) || !body.data.every(model => typeof model.id === 'string')) {
+ throw new Error('MLX /v1/models returned an invalid model list');
+ }
+ return body.data.map(model => model.id);
+}
+
+function parseStream(text) {
+ const calls = new Map();
+ let content = '', fingerprint = '', finish = '', done = false;
+ for (const line of text.split(/\r?\n/)) {
+ if (!line.startsWith('data:')) continue;
+ const data = line.slice(5).trim();
+ if (data === '[DONE]') { done = true; continue; }
+ const chunk = JSON.parse(data);
+ if (chunk.error) throw new Error('MLX returned a streaming error');
+ fingerprint = chunk.system_fingerprint || fingerprint;
+ for (const choice of chunk.choices || []) {
+ finish = choice.finish_reason || finish;
+ content += choice.delta?.content || '';
+ for (const call of choice.delta?.tool_calls || []) {
+ if (!Number.isInteger(call.index)) throw new Error('MLX tool-call stream has no index');
+ const prior = calls.get(call.index) || { id: '', type: 'function', function: { name: '', arguments: '' } };
+ prior.id += call.id || '';
+ prior.function.name += call.function?.name || '';
+ prior.function.arguments += call.function?.arguments || '';
+ calls.set(call.index, prior);
+ }
+ }
+ }
+ if (!done) throw new Error('MLX stream ended without [DONE]');
+ return { calls: [...calls.values()], content, fingerprint, finish };
+}
+
+async function verifyTools(endpoint, model, fetcher) {
+ const tools = [{
+ type: 'function',
+ function: {
+ name: 'hive_mlx_check',
+ description: 'Echo a value to verify structured tool calling. Call this tool exactly once.',
+ parameters: { type: 'object', properties: { value: { type: 'string' } }, required: ['value'], additionalProperties: false },
+ },
+ }];
+ const messages = [{ role: 'user', content: `Call hive_mlx_check with value "${PROBE_VALUE}". Do not answer in prose.` }];
+ const complete = async () => parseStream(await request(endpoint, 'chat/completions', {
+ model, messages, tools, stream: true, max_tokens: PROBE_MAX_TOKENS, temperature: 0,
+ }, PROBE_TIMEOUT_MS, fetcher));
+ const first = await complete();
+ const call = first.calls[0];
+ if (first.finish !== 'tool_calls' || first.calls.length !== 1 || !call?.id ||
+ call.function.name !== 'hive_mlx_check' || JSON.parse(call.function.arguments).value !== PROBE_VALUE) {
+ throw new Error('Selected MLX model/runtime failed the streaming tool-call check; use a model with a supported MLX-LM tool parser/chat template');
+ }
+ messages.push({ role: 'assistant', content: first.content || null, tool_calls: first.calls });
+ messages.push({ role: 'tool', tool_call_id: call.id, content: PROBE_VALUE });
+ messages.push({ role: 'user', content: 'Return the tool result verbatim, without calling any more tools.' });
+ const second = await complete();
+ if (second.calls.length || second.finish !== 'stop' || second.content.trim() !== PROBE_VALUE) {
+ throw new Error('Selected MLX model/runtime failed the tool-result round trip');
+ }
+ return first.fingerprint;
+}
+
+function agentDir(env = process.env) {
+ return env.PI_CODING_AGENT_DIR || path.join(env.HOME, '.pi', 'agent');
+}
+
+function readJSON(file) {
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function digest(provider) {
+ return createHash('sha256').update(JSON.stringify(provider)).digest('hex');
+}
+
+function tokenBudget(raw, fallback) {
+ const value = Number(raw || fallback);
+ if (!Number.isSafeInteger(value) || value <= 0) throw new Error('MLX context/output token limits must be positive integers');
+ return value;
+}
+
+function serve(model, env = process.env, inspectHost = hostInfo, launch = execFileSync) {
+ const selection = parsePiModelSelection(`mlx/${model || ''}`);
+ if (!selection.valid || model === 'default_model') throw new Error('Choose an explicit, already-downloaded MLX model ID or absolute path');
+ inspectHost(env);
+ if (path.isAbsolute(model)) {
+ try {
+ if (!fs.statSync(model).isDirectory()) throw new Error('not a directory');
+ } catch (_) { throw new Error('MLX model directory is missing; download the model yourself before running contribute-mlx-serve'); }
+ }
+ const endpoint = new URL(endpointURL(env.HIVE_MLX_ENDPOINT || DEFAULT_ENDPOINT));
+ launch(env.HIVE_MLX_PYTHON || 'python3', [
+ '-m', 'mlx_lm.server', '--model', model,
+ '--host', endpoint.hostname.replace(/^\[|\]$/g, ''),
+ '--port', endpoint.port || DEFAULT_HTTP_PORT,
+ ], { env: { ...env, HF_HUB_OFFLINE: '1' }, stdio: 'inherit' });
+}
+
+async function configure(model, env = process.env, fetcher, inspectHost = hostInfo) {
+ if (typeof model !== 'string' || !model) throw new Error('An explicit MLX model ID or absolute path is required');
+ const selection = parsePiModelSelection(`mlx/${model}`);
+ if (!selection.valid || model === 'default_model') throw new Error('Choose an explicit MLX model ID or absolute path without whitespace, not default_model');
+ const info = inspectHost(env);
+ const endpoint = endpointURL(env.HIVE_MLX_ENDPOINT || DEFAULT_ENDPOINT);
+ if (!(await availableModels(endpoint, fetcher)).includes(model)) {
+ throw new Error('MLX model is not listed by /v1/models; download it yourself or start the server with its local absolute path first');
+ }
+ const contextWindow = tokenBudget(env.HIVE_MLX_CONTEXT_WINDOW, DEFAULT_CONTEXT);
+ const maxTokens = tokenBudget(env.HIVE_MLX_MAX_TOKENS, DEFAULT_MAX_TOKENS);
+ if (maxTokens >= contextWindow) throw new Error('HIVE_MLX_MAX_TOKENS must be smaller than HIVE_MLX_CONTEXT_WINDOW');
+ const dir = agentDir(env);
+ const file = path.join(dir, 'models.json');
+ const models = fs.existsSync(file) ? readJSON(file) : { providers: {} };
+ if (!models || typeof models !== 'object' || Array.isArray(models) ||
+ (models.providers !== undefined && (!models.providers || typeof models.providers !== 'object' || Array.isArray(models.providers)))) {
+ throw new Error('Refusing to overwrite malformed Pi models.json');
+ }
+ models.providers ||= {};
+ // Deliberately opt-in: the configure CLI requires --verify-tools. Only this
+ // explicit operation runs two bounded inference requests, never startup.
+ const fingerprint = await verifyTools(endpoint, model, fetcher);
+ if (!fingerprint.startsWith(`${info.mlxLM}-${info.mlx}-`)) {
+ throw new Error('Endpoint fingerprint does not match your MLX-LM/MLX environment; select the server virtualenv with HIVE_MLX_PYTHON');
+ }
+ const provider = {
+ baseUrl: endpoint, api: 'hive-mlx', apiKey: 'mlx-local', compat: COMPAT,
+ models: [{ id: model, name: model, reasoning: false, input: ['text'], contextWindow, maxTokens,
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+ };
+ models.providers.mlx = provider;
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+ // A stale receipt cannot authorize a half-written configuration.
+ fs.writeFileSync(file, `${JSON.stringify(models, null, 2)}\n`, { mode: 0o600 });
+ fs.chmodSync(file, 0o600);
+ fs.writeFileSync(path.join(dir, 'hive-mlx.json'), `${JSON.stringify({
+ platform: 'darwin', arch: 'arm64', model, providerDigest: digest(provider),
+ mlx: info.mlx, mlxLM: info.mlxLM, fingerprint, verifiedAt: new Date().toISOString(),
+ }, null, 2)}\n`, { mode: 0o600 });
+ fs.chmodSync(path.join(dir, 'hive-mlx.json'), 0o600);
+ return selection.canonical;
+}
+
+function configuration(selection, env = process.env) {
+ if (!selection.valid || selection.provider !== 'mlx') throw new Error('MLX selection must use mlx/');
+ let provider, receipt;
+ try {
+ provider = readJSON(path.join(agentDir(env), 'models.json')).providers.mlx;
+ receipt = readJSON(path.join(agentDir(env), 'hive-mlx.json'));
+ } catch (_) { throw new Error('MLX is not configured; run just contribute-mlx-setup --verify-tools on the Mac host first'); }
+ if (receipt.platform !== 'darwin' || receipt.arch !== 'arm64' || receipt.model !== selection.model ||
+ receipt.providerDigest !== digest(provider)) {
+ throw new Error('MLX configuration changed or lacks a matching tool-check receipt; rerun contribute-mlx-setup --verify-tools');
+ }
+ endpointURL(provider.baseUrl);
+ return provider;
+}
+
+async function check(raw, env = process.env, fetcher, inspectHost = hostInfo) {
+ const selection = parsePiModelSelection(raw);
+ const provider = configuration(selection, env);
+ if (inspectHost) inspectHost(env);
+ if (!(await availableModels(provider.baseUrl, fetcher)).includes(selection.model)) {
+ throw new Error('Configured MLX model is missing from /v1/models; restore it and rerun contribute-mlx-setup --verify-tools');
+ }
+}
+
+function checkRuntime(raw, env = process.env, run = execFileSync) {
+ if (!raw.startsWith('mlx/')) return;
+ try {
+ run(process.execPath, [__filename, 'check', raw, process.platform === 'darwin' ? '--host' : '--endpoint-only'], {
+ env, encoding: 'utf8', timeout: HTTP_TIMEOUT_MS * 2, stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ } catch (error) {
+ throw new Error(String(error.stderr || 'MLX preflight failed; check the local server and container host networking').trim());
+ }
+}
+
+module.exports = { endpointURL, validatePlatform, hostInfo, availableModels, parseStream, verifyTools, configure, configuration, check, checkRuntime, serve, DEFAULT_ENDPOINT };
+
+if (require.main === module) {
+ (async () => {
+ const [command, model, flag] = process.argv.slice(2);
+ if (command === 'configure' && flag === '--verify-tools') {
+ const selected = await configure(model);
+ console.log(`MLX streaming tool round trip verified. Select AGENT_BACKEND=pi AGENT_MODEL=${selected}`);
+ } else if (command === 'serve') {
+ serve(model);
+ } else if (command === 'check') {
+ await check(model, process.env, undefined, flag === '--endpoint-only' ? null : hostInfo);
+ console.log('MLX endpoint/model ready; coding execution is provided by Pi, not MLX-LM');
+ } else {
+ throw new Error('Usage: mlx-backend.js configure --verify-tools (explicitly runs two bounded inference requests), serve (foreground, offline, loopback), or check mlx/');
+ }
+ })().catch(error => { console.error(error.message); process.exitCode = 1; });
+}
diff --git a/bin/mlx-backend.test.js b/bin/mlx-backend.test.js
new file mode 100644
index 0000000000..9cc6f58ded
--- /dev/null
+++ b/bin/mlx-backend.test.js
@@ -0,0 +1,293 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const { randomUUID } = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const mlx = require('./mlx-backend.js');
+const pi = require('./pi-backend.js');
+const extension = require('./mlx-pi-extension.js');
+
+const MODEL = 'mlx-community/tool-coder-4bit';
+const FINGERPRINT = '0.31.0-0.31.0-macOS-test-arm64';
+const HOST = {
+ platform: 'darwin', arch: 'arm64', macos: '14.0',
+ pythonArch: 'arm64', pythonPlatform: 'darwin', pythonVersion: [3, 10],
+ mlx: '0.31.0', mlxLM: '0.31.0',
+};
+const CALL = { index: 0, id: 'check-1', type: 'function', function: { name: 'hive_mlx_check', arguments: '{"value":"hive_mlx_tool_check"}' } };
+
+function stream(delta, finish = 'stop', fingerprint = FINGERPRINT) {
+ return `data: ${JSON.stringify({ system_fingerprint: fingerprint, choices: [{ delta, finish_reason: finish }] })}\n\ndata: [DONE]\n\n`;
+}
+
+function fixture(t) {
+ const dir = path.join(__dirname, `.mlx-fixture-${randomUUID()}`);
+ fs.mkdirSync(dir);
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ return { HOME: dir, PI_CODING_AGENT_DIR: path.join(dir, '.pi', 'agent') };
+}
+
+function fakeServer(options = {}) {
+ const calls = [];
+ return {
+ calls,
+ fetch: async (url, init) => {
+ calls.push({ url, init });
+ assert.equal(init.redirect, 'error');
+ if (init.method === 'GET') {
+ return new Response(JSON.stringify({ data: (options.models || [MODEL]).map(id => ({ id })) }));
+ }
+ const request = JSON.parse(init.body);
+ assert.equal(request.model, options.model || MODEL);
+ assert.equal(request.stream, true);
+ assert.equal(request.max_tokens, 256);
+ assert.equal(request.tools[0].function.name, 'hive_mlx_check');
+ if (request.messages.length === 1) {
+ return new Response(options.prose
+ ? stream({ content: 'I would call the tool' })
+ : stream({ tool_calls: [CALL] }, 'tool_calls', options.fingerprint || FINGERPRINT));
+ }
+ assert.equal(request.messages[1].tool_calls[0].id, 'check-1');
+ assert.equal(request.messages[2].role, 'tool');
+ assert.equal(request.messages[2].tool_call_id, 'check-1');
+ assert.equal(request.messages[2].content, 'hive_mlx_tool_check');
+ return new Response(stream({ content: options.badRoundTrip ? 'no' : 'hive_mlx_tool_check' }));
+ },
+ };
+}
+
+test('Apple Silicon/native Python/macOS compatibility is explicit and optional', () => {
+ assert.equal(mlx.validatePlatform(HOST), HOST);
+ for (const [override, error] of [
+ [{ platform: 'linux' }, /Apple Silicon/],
+ [{ arch: 'x64' }, /Rosetta/],
+ [{ macos: '13.7' }, /macOS 14/],
+ [{ macos: '' }, /macOS 14/],
+ [{ pythonArch: 'x86_64' }, /natively/],
+ [{ pythonPlatform: 'linux' }, /natively/],
+ [{ pythonVersion: [3, 9] }, /Python >=3.10/],
+ [{ mlxLM: null }, /virtualenv/],
+ [{ mlx: null }, /virtualenv/],
+ ]) assert.throws(() => mlx.validatePlatform({ ...HOST, ...override }), error);
+ // Other Pi providers never inspect a Python environment or an endpoint.
+ assert.doesNotThrow(() => mlx.checkRuntime('anthropic/claude-sonnet-4-6', {}));
+ assert.equal(pi.parsePiModelSelection('openai/gpt-4o').canonical, 'openai/gpt-4o');
+ assert.equal(pi.parsePiModelSelection('openai//absolute').valid, false);
+ assert.equal(pi.parsePiModelSelection('mlx//Users/contributor/models/coder').valid, true);
+ assert.equal(pi.parsePiModelSelection('mlx//Users/a b/coder').valid, false);
+});
+
+test('endpoint is strictly loopback; credentials, DNS, paths and hosted fallbacks are refused', () => {
+ assert.equal(mlx.endpointURL('http://127.0.0.1:8080/v1/'), mlx.DEFAULT_ENDPOINT);
+ assert.equal(mlx.endpointURL('http://[::1]:8080/v1'), 'http://[::1]:8080/v1');
+ for (const endpoint of [
+ 'https://api.openai.com/v1', 'http://0.0.0.0:8080/v1',
+ 'http://localhost:8080/v1', 'http://host.docker.internal:8080/v1',
+ 'http://secret@127.0.0.1:8080/v1', 'http://127.0.0.1/v1?key=x',
+ 'http://127.0.0.1/v1#x', 'http://127.0.0.1/other', 'invalid',
+ ]) assert.throws(() => mlx.endpointURL(endpoint), /endpoint/);
+});
+
+test('explicit setup preserves other providers and persists verified Pi configuration', async t => {
+ const env = fixture(t);
+ fs.mkdirSync(env.PI_CODING_AGENT_DIR, { recursive: true });
+ const original = { providers: { anthropic: { apiKey: 'do-not-copy-me' } }, other: 'preserved' };
+ fs.writeFileSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json'), JSON.stringify(original));
+ const server = fakeServer();
+ assert.equal(await mlx.configure(MODEL, env, server.fetch, () => HOST), `mlx/${MODEL}`);
+ assert.equal(server.calls.length, 3);
+ const config = JSON.parse(fs.readFileSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json')));
+ assert.deepEqual(config.providers.anthropic, original.providers.anthropic);
+ assert.equal(config.other, 'preserved');
+ assert.equal(config.providers.mlx.api, 'hive-mlx');
+ assert.equal(config.providers.mlx.compat.maxTokensField, 'max_tokens');
+ assert.equal(config.providers.mlx.models[0].id, MODEL);
+ assert.equal(config.providers.mlx.models[0].contextWindow, 8192);
+ assert.equal(fs.statSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json')).mode & 0o777, 0o600);
+ assert.equal(pi.piCredentialConfiguration(pi.parsePiModelSelection(`mlx/${MODEL}`), env), 'configured_unverified');
+ await mlx.check(`mlx/${MODEL}`, env, server.fetch, null);
+ assert.equal(server.calls.length, 4, 'startup makes only a model-list request, never inference');
+ pi.narrowPiStage(path.join(env.HOME, '.pi'), pi.parsePiModelSelection(`mlx/${MODEL}`));
+ assert.deepEqual(Object.keys(JSON.parse(fs.readFileSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json'))).providers), ['mlx']);
+ await mlx.check(`mlx/${MODEL}`, env, server.fetch, null);
+});
+
+test('setup rejects missing models, prose-only models, broken tools and wrong runtime without writing config', async t => {
+ for (const [options, error] of [
+ [{ models: ['other'] }, /not listed/],
+ [{ prose: true }, /streaming tool-call/],
+ [{ badRoundTrip: true }, /tool-result/],
+ [{ fingerprint: 'not-mlx' }, /fingerprint/],
+ ]) {
+ const env = fixture(t);
+ await assert.rejects(mlx.configure(MODEL, env, fakeServer(options).fetch, () => HOST), error);
+ assert.equal(fs.existsSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json')), false);
+ }
+});
+
+test('startup fails closed for unconfigured, tampered, missing and unreachable models', async t => {
+ const env = fixture(t);
+ await assert.rejects(mlx.check(`mlx/${MODEL}`, env, fakeServer().fetch, null), /not configured/);
+ await mlx.configure(MODEL, env, fakeServer().fetch, () => HOST);
+ await assert.rejects(mlx.check(`mlx/${MODEL}`, env, fakeServer({ models: [] }).fetch, null), /missing/);
+ await assert.rejects(mlx.check(`mlx/${MODEL}`, env, async () => { throw new Error('connection refused'); }, null), /local endpoint request failed/);
+ const configFile = path.join(env.PI_CODING_AGENT_DIR, 'models.json');
+ const config = JSON.parse(fs.readFileSync(configFile));
+ config.providers.mlx.baseUrl = 'https://api.openai.com/v1';
+ fs.writeFileSync(configFile, JSON.stringify(config));
+ await assert.rejects(mlx.check(`mlx/${MODEL}`, env, fakeServer().fetch, null), /configuration changed/);
+});
+
+test('stream parser assembles fragmented tool arguments and rejects truncated/error streams', () => {
+ const fragments = [
+ { index: 0, id: 'check-1', function: { name: 'hive_mlx_check', arguments: '{"value":' } },
+ { index: 0, function: { arguments: '"hive_mlx_tool_check"}' } },
+ ].map(call => stream({ tool_calls: [call] }, 'tool_calls').replace('data: [DONE]\n\n', '')).join('');
+ const parsed = mlx.parseStream(`: keepalive\n\n${fragments}data: [DONE]\n\n`);
+ assert.equal(parsed.calls[0].function.arguments, CALL.function.arguments);
+ assert.throws(() => mlx.parseStream(fragments), /without \[DONE\]/);
+ assert.throws(() => mlx.parseStream('data: {"error":"bad"}\n\n'), /streaming error/);
+});
+
+test('HTTP seam handles actual local streaming responses and refuses redirects', async t => {
+ const server = http.createServer((req, res) => {
+ if (req.url === '/v1/models') {
+ res.writeHead(200, { 'Content-Type': 'application/json' });
+ res.end(JSON.stringify({ data: [{ id: MODEL }] }));
+ } else {
+ res.writeHead(302, { Location: 'https://api.openai.com/v1/models' });
+ res.end();
+ }
+ });
+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+ t.after(() => new Promise(resolve => server.close(resolve)));
+ const endpoint = `http://127.0.0.1:${server.address().port}/v1`;
+ assert.deepEqual(await mlx.availableModels(endpoint), [MODEL]);
+ await assert.rejects(mlx.verifyTools(endpoint, MODEL), /local endpoint request failed/);
+});
+
+test('model paths and token budgets are contributor owned and no default model is selected', async t => {
+ const env = fixture(t);
+ for (const model of ['', 'default_model', 'model;touch-elsewhere']) {
+ await assert.rejects(mlx.configure(model, env, fakeServer().fetch, () => HOST));
+ }
+ await assert.rejects(mlx.configure(MODEL, { ...env, HIVE_MLX_CONTEXT_WINDOW: 'bad' }, fakeServer().fetch, () => HOST), /positive integers/);
+ await assert.rejects(mlx.configure(MODEL, { ...env, HIVE_MLX_MAX_TOKENS: '8192' }, fakeServer().fetch, () => HOST), /smaller/);
+ const model = '/Users/contributor/models/coder';
+ const server = fakeServer({ model, models: [model] });
+ assert.equal(await mlx.configure(model, env, server.fetch, () => HOST), `mlx/${model}`);
+});
+
+test('runtime preflight is a bounded subprocess and reports failures without fallback', () => {
+ const env = { HOME: '/contributor' };
+ const calls = [];
+ mlx.checkRuntime(`mlx/${MODEL}`, env, (...args) => { calls.push(args); });
+ assert.equal(calls.length, 1);
+ assert.equal(calls[0][0], process.execPath);
+ assert.deepEqual(calls[0][1].slice(1), ['check', `mlx/${MODEL}`, process.platform === 'darwin' ? '--host' : '--endpoint-only']);
+ assert.equal(calls[0][2].env, env);
+ assert.equal(calls[0][2].timeout, 20000);
+ const error = Object.assign(new Error('failed'), { stderr: Buffer.from('MLX local endpoint unreachable') });
+ assert.throws(() => mlx.checkRuntime(`mlx/${MODEL}`, env, () => { throw error; }), /endpoint unreachable/);
+});
+
+test('real Pi provider delegate forces loopback-only fetch and preserves tools and cancellation', async t => {
+ const env = fixture(t);
+ env.AGENT_MODEL = `mlx/${MODEL}`;
+ await mlx.configure(MODEL, env, fakeServer().fetch, () => HOST);
+ const delegateCalls = [];
+ const fetchCalls = [];
+ let registered;
+ const streamResult = { marker: 'Pi stream and tool executor' };
+ extension.registerMlx({ registerProvider(name, config) {
+ assert.equal(name, 'mlx');
+ registered = config;
+ } }, { streamSimple(...args) { delegateCalls.push(args); return streamResult; } }, env,
+ async (...args) => { fetchCalls.push(args); return new Response('ok'); });
+ assert.equal(registered.api, 'hive-mlx');
+ const model = { provider: 'mlx', id: MODEL, baseUrl: mlx.DEFAULT_ENDPOINT, api: 'hive-mlx' };
+ const context = { messages: [{ role: 'toolResult', content: [{ type: 'text', text: 'edited file' }] }] };
+ const controller = new AbortController();
+ const options = { signal: controller.signal, onPayload() {}, fetch() { throw new Error('must not override guard'); } };
+ assert.equal(registered.streamSimple(model, context, options), streamResult);
+ const [effectiveModel, actualContext, actualOptions] = delegateCalls[0];
+ assert.equal(effectiveModel.api, 'openai-completions');
+ assert.equal(actualContext, context, 'Pi retains the full tool transcript');
+ assert.equal(actualOptions.signal, controller.signal);
+ assert.equal(actualOptions.onPayload, options.onPayload);
+ await actualOptions.fetch(`${mlx.DEFAULT_ENDPOINT}/chat/completions`, { redirect: 'follow', method: 'POST' });
+ assert.equal(fetchCalls[0][1].redirect, 'error');
+ assert.throws(() => actualOptions.fetch('https://api.openai.com/v1/chat/completions'), /loopback/);
+ assert.throws(() => registered.streamSimple({ ...model, id: 'another' }, context, options), /model changed/);
+});
+
+test('Pi inference transport rejects redirects after successful setup', async t => {
+ const server = http.createServer((req, res) => {
+ res.writeHead(307, { Location: 'https://api.openai.com/v1/chat/completions' });
+ res.end();
+ });
+
+ test('explicit serve recipe uses native Python, loopback and offline weights without changing RAM settings', t => {
+ const env = fixture(t);
+ const model = path.join(env.HOME, 'model');
+ fs.mkdirSync(model);
+ const calls = [];
+ mlx.serve(model, { ...env, HIVE_MLX_PYTHON: '/chosen/python', HIVE_MLX_ENDPOINT: 'http://127.0.0.1:8081/v1' },
+ () => HOST, (...args) => calls.push(args));
+ assert.equal(calls[0][0], '/chosen/python');
+ assert.deepEqual(calls[0][1], ['-m', 'mlx_lm.server', '--model', model, '--host', '127.0.0.1', '--port', '8081']);
+ assert.equal(calls[0][2].env.HF_HUB_OFFLINE, '1');
+ assert.equal(calls[0][2].stdio, 'inherit');
+ assert.throws(() => mlx.serve(path.join(model, 'missing'), env, () => HOST, () => assert.fail('must not launch')), /directory is missing/);
+ assert.throws(() => mlx.serve(model, { ...env, HIVE_MLX_ENDPOINT: 'http://0.0.0.0:8080/v1' }, () => HOST), /loopback/);
+ assert.throws(() => mlx.serve(model, env, () => { throw new Error('unsupported Rosetta Python'); }, () => assert.fail('must not launch')), /Rosetta/);
+ });
+
+ test('MLX just launcher remains a Pi wrapper with explicit model/runtime refusal', () => {
+ const recipes = fs.readFileSync(path.join(__dirname, '..', 'Justfile'), 'utf8');
+ const launcher = recipes.split('contribute-mlx mode="docker":')[1].split('\n\n')[0];
+ assert.match(launcher, /\$\{AGENT_MODEL:-\}" != mlx\/\*/);
+ assert.match(launcher, /contribute-hive pi "\$1"/);
+ assert.match(launcher, /export HIVE_CONTAINER_RUNTIME=docker/);
+ assert.match(launcher, /Kubernetes cannot reach Mac loopback/);
+ assert.match(recipes, /contribute-mlx-serve model:\n node bin\/mlx-backend\.js serve "\$1"/);
+ });
+
+ test('MLX launcher preserves explicit model across both saved-profile loads without changing generic Pi defaults', t => {
+ const env = fixture(t);
+ const config = path.join(env.HOME, 'contributor.env');
+ fs.writeFileSync(config, 'AGENT_MODEL=anthropic/saved-hosted-model\nHIVE_CONTAINER_RUNTIME=podman\n');
+ const recipes = fs.readFileSync(path.join(__dirname, '..', 'Justfile'), 'utf8');
+ const launcher = recipes.split('contribute-mlx mode="docker":')[1].split('\n\n')[0]
+ .replaceAll('{{config_dir}}', env.HOME)
+ .replace('{{justfile_directory()}}', path.join(__dirname, '..'));
+ const guard = recipes.split('# MLX-only launch override:')[1].split('# End MLX-only launch override.')[0];
+ const nested = guard.slice(guard.indexOf('\n'));
+ const script = `just() {
+ local _MLX_LAUNCH_MODEL="\${HIVE_MLX_LAUNCH_MODEL:-}"
+ source "${config}"
+ BACKEND=pi
+ ${nested}
+ printf '%s' "$AGENT_MODEL"
+ }\n${launcher}`;
+ const result = execFileSync('bash', ['-s', '--', 'docker'], {
+ input: script, encoding: 'utf8',
+ env: { ...process.env, ...env, AGENT_MODEL: `mlx/${MODEL}`, HIVE_CONTAINER_RUNTIME: 'docker' },
+ });
+ assert.equal(result, `mlx/${MODEL}`);
+ const ordinary = execFileSync('bash', ['-s'], {
+ input: `AGENT_MODEL=anthropic/saved-hosted-model; BACKEND=pi; _MLX_LAUNCH_MODEL='';\n${nested}\nprintf '%s' "$AGENT_MODEL"`,
+ encoding: 'utf8',
+ });
+ assert.equal(ordinary, 'anthropic/saved-hosted-model');
+ });
+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+ t.after(() => new Promise(resolve => server.close(resolve)));
+ const endpoint = `http://127.0.0.1:${server.address().port}/v1`;
+ const guarded = extension.localFetch(endpoint);
+ await assert.rejects(guarded(`${endpoint}/chat/completions`, { method: 'POST', body: 'private task' }));
+});
diff --git a/bin/mlx-pi-extension.js b/bin/mlx-pi-extension.js
new file mode 100644
index 0000000000..b2a99b480a
--- /dev/null
+++ b/bin/mlx-pi-extension.js
@@ -0,0 +1,48 @@
+'use strict';
+
+const { configuration, endpointURL } = require('./mlx-backend.js');
+const { parsePiModelSelection } = require('./pi-backend.js');
+
+function localFetch(endpoint, fetcher = globalThis.fetch) {
+ const allowed = `${endpointURL(endpoint)}/chat/completions`;
+ return (input, init) => {
+ const url = typeof input === 'string' || input instanceof URL ? String(input) : input.url;
+ if (url !== allowed) throw new Error('MLX inference request left its configured loopback endpoint');
+ // Apply this to Pi's REAL inference transport, not just the setup probe.
+ // In particular a 307/308 must never forward task prompts to another host.
+ return fetcher(input, { ...init, redirect: 'error' });
+ };
+}
+
+function registerMlx(pi, api, env = process.env, fetcher = globalThis.fetch) {
+ const selection = parsePiModelSelection(env.AGENT_MODEL || '');
+ const provider = configuration(selection, env);
+ const guardedFetch = localFetch(provider.baseUrl, fetcher);
+ pi.registerProvider('mlx', {
+ ...provider,
+ streamSimple(model, context, options) {
+ if (model.provider !== 'mlx' || model.id !== selection.model || model.baseUrl !== provider.baseUrl) {
+ throw new Error('MLX model changed; reconfigure and restart the contributor relay');
+ }
+ // Reuse Pi's maintained OpenAI message/tool conversion, stream decoder,
+ // usage accounting and AbortSignal handling. Do not build a new executor.
+ return api.streamSimple({ ...model, api: 'openai-completions' }, context, {
+ ...options, fetch: guardedFetch,
+ });
+ },
+ });
+}
+
+module.exports = function mlxExtension(pi) {
+ // Pi 1.4.0 resolves this through its extension compatibility entrypoint,
+ // including in standalone distributions. No global Pi dependency is needed
+ // by ClankeR's relay or its test runner.
+ const { openAICompletionsApi, PI_AI_VERSION } = require('@earendil-works/pi-ai');
+ const [major, minor] = String(PI_AI_VERSION || '').split('.').map(Number);
+ if (typeof openAICompletionsApi !== 'function' || !(major > 1 || (major === 1 && minor >= 4))) {
+ throw new Error('ClankeR MLX requires Pi >=1.4.0 with custom fetch transport support; update your Pi installation');
+ }
+ registerMlx(pi, openAICompletionsApi());
+};
+module.exports.localFetch = localFetch;
+module.exports.registerMlx = registerMlx;
diff --git a/bin/pi-backend.js b/bin/pi-backend.js
index a8741b383a..9966add909 100644
--- a/bin/pi-backend.js
+++ b/bin/pi-backend.js
@@ -66,7 +66,8 @@ function parsePiModelSelection(raw) {
// This token is also used by the interactive shell launcher. Restrict it to
// model-ID punctuation so a contributor preference can never become shell
// syntax while retaining paths (OpenRouter), tags (Ollama), and revisions.
- if (!/^[A-Za-z0-9][A-Za-z0-9._/+:@~-]*$/.test(model)) {
+ const modelPattern = provider === 'mlx' ? /^(?:[A-Za-z0-9]|\/)[A-Za-z0-9._/+:@~-]*$/ : /^[A-Za-z0-9][A-Za-z0-9._/+:@~-]*$/;
+ if (!modelPattern.test(model)) {
return { valid: false, state: 'invalid', error: 'invalid Pi model in AGENT_MODEL' };
}
return { valid: true, state: 'configured', provider, model, canonical: raw };
diff --git a/changelog.d/added-clanker-mlx.md b/changelog.d/added-clanker-mlx.md
new file mode 100644
index 0000000000..ea4e4f27f9
--- /dev/null
+++ b/changelog.d/added-clanker-mlx.md
@@ -0,0 +1 @@
+- ClankeR contributors can select Apple MLX on `/contribute` and use dedicated `just` setup/serve/launch recipes for user-managed MLX-LM inference through Pi on supported Apple Silicon Macs, with loopback-only configuration, explicit streaming tool-call verification, fail-closed checks, and public integration/setup documentation.
diff --git a/docs/backend-setup.md b/docs/backend-setup.md
index 43d1593305..8d56d018b6 100644
--- a/docs/backend-setup.md
+++ b/docs/backend-setup.md
@@ -12,6 +12,7 @@ Hive validates backend names in `src/pkg/config` and launches CLIs in `src/crux/
| `gemini` | `gemini` | Install Gemini CLI and configure its normal auth/API key. | Supported by the server-side manager; Hive launches `gemini` and passes `--model` when a model is configured. |
| `goose` | `goose` | Install [Goose](https://github.com/aaif-goose/goose) from its canonical upstream and configure provider/model (`GOOSE_PROVIDER`, `GOOSE_MODEL`, or `goose configure`). | Hive launches `goose run -s` and appends `--model` when set. |
| `pi` | `goose` in the Go manager; `pi` in contributor scripts | Contributor mode requires `AGENT_MODEL=provider/model` plus that provider's official credential variable or `~/.pi/agent/auth.json`. In the server-side manager, `backendBinary("pi")` maps to Goose. | Contributor Pi supports interactive and headless (`--print --mode json`) delivery. No generic Pi key/provider variable exists. |
+| `pi` + Apple MLX | `pi` in contributor scripts only | `/contribute` offers **Apple MLX**, mapped to Pi with `AGENT_MODEL=mlx/`. Run `just contribute-mlx-serve `, explicitly verify via `just contribute-mlx-setup --verify-tools`, register with `just contribute-setup pi`, then `just contribute-mlx`. | Apple Silicon, macOS 14+, native Python 3.10+, Pi 1.4.0+, tool-capable model and Docker Desktop host networking; MLX-LM runs on the Mac. Not a hosted agent backend or a standalone coding CLI. [Installation, RAM budget and troubleshooting](../src/docs/contributor-relay.md#apple-mlx-local-inference). |
| `pi` + Kiro | `goose` in the Go manager; `pi` in contributor scripts | Set `KIRO_API_KEY` and use the Pi Kiro provider model id shape, for example `AGENT_MODEL=kiro-api-key/claude-opus-5:high`. Hive forwards `KIRO_API_KEY` into contributor containers and the dashboard's `pi` model picker includes common `kiro-api-key/*` IDs as a non-authoritative fallback. | This is the supported Kiro path for now instead of a first-class `kiro-cli` backend: Kiro's stable unattended/trust/login CLI contract is not verified in Hive, while `pi` + `pi-kiro-api` is already the adopter-proven path. Quota headroom remains separate from the `anthropic` pool until the Kiro quota work in #8726 lands. |
| `bob` | `bob` | Provide `HIVE_BOB_API_KEY` or `/secrets/bob_api_key` for pods; contributor mode requires `BOB_API_KEY` (legacy `BOBSHELL_API_KEY` also accepted). | Hive uses API-key auth headlessly and accepts the Bob license at launch. |
| `codex` | `codex` | Install `@openai/codex` and run `codex login --device-auth` for subscription/OAuth auth. The CLI stores credentials in `CODEX_HOME/auth.json` (default `${HOME}/.codex/auth.json`); API-key mode can use `CODEX_API_KEY`/`OPENAI_API_KEY` or a populated auth file, but it is not required for subscription users. | Hive gives each agent its own `CODEX_HOME` and probes `auth.json` for OAuth tokens/API-key state (or API-key env presence). Contributor mode keeps `--ask-for-approval on-request`, grants the exact `HIVE_WORKSPACE_DIR` tree with `--add-dir`, and defaults `approvals_reviewer` to `auto_review` so an unattended task never waits on the contributor. The `--sandbox` value is resolved at launch rather than fixed (#6653): `workspace-write` wherever bubblewrap can actually create the user namespace it needs — local mode, and containers started with a relaxed seccomp profile — and `danger-full-access` only inside the contributor container when that namespace is denied, where the container is already the boundary and asking for a nested one failed every command. Override with `HIVE_CODEX_APPROVAL_POLICY`/`HIVE_CODEX_SANDBOX_MODE`/`HIVE_CODEX_APPROVALS_REVIEWER`, or set `HIVE_CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1` only when you intentionally want the old bypass posture. `AGENT_REASONING_EFFORT` is passed to Codex as `-c model_reasoning_effort="..."` on the contributor-relay path; server-launched agents use the per-agent `reasoning_effort` config field (`minimal`\|`low`\|`medium`\|`high`\|`xhigh`) the same way since #6163. |
diff --git a/docs/inference-backends.md b/docs/inference-backends.md
index c26b8369d0..4d5ef6030a 100644
--- a/docs/inference-backends.md
+++ b/docs/inference-backends.md
@@ -4,6 +4,20 @@ Hive can route agents through OpenAI-compatible model gateways instead of a subs
See [Gateway-path tier](../src/docs/backend-support-tiers.md#gateway-path-tier) for which dashboard/agent features (terminal access, model discovery, token metering, login) are guaranteed, best-effort, or not applicable on this path, and what a gateway smoke check must prove.
+## Apple MLX: local contributor inference, not a hosted gateway
+
+ClankeR offers **Apple MLX** on `/contribute`, using the actual Pi coding
+backend with an `mlx/` provider. MLX-LM runs natively on an Apple Silicon
+Mac (macOS 14+, native Python 3.10+); Pi supplies tools in the contributor
+container via Docker Desktop host networking. It is not a new `backend: mlx`
+for hosted agents or a Governor Model Gateway.
+
+Use the dedicated `just contribute-mlx-serve`, explicit
+`just contribute-mlx-setup --verify-tools`, and `just contribute-mlx`
+workflow. Models are user-managed, must support structured tools, and consume
+shared host RAM. See [installation and troubleshooting](../src/docs/contributor-relay.md#apple-mlx-local-inference)
+for prerequisites, Pi registration, loopback restrictions and verification limits.
+
## Looking for Copilot (or Claude, Codex, Gemini…)? It is not a Model Gateway
Subscription CLI backends — `copilot`, `claude`, `codex`, `gemini`, `goose`,
diff --git a/src/Dockerfile.contributor b/src/Dockerfile.contributor
index 9ee01e3e59..43e021b52d 100644
--- a/src/Dockerfile.contributor
+++ b/src/Dockerfile.contributor
@@ -536,6 +536,8 @@ COPY bin/contributor-relay.js /usr/local/bin/
COPY bin/contributor-relay.sh /usr/local/bin/
COPY bin/lib/ /usr/local/bin/lib/
COPY bin/pi-backend.js /usr/local/bin/
+COPY bin/mlx-backend.js /usr/local/bin/
+COPY bin/mlx-pi-extension.js /usr/local/bin/
# #7925: the relay runs this against the task checkout's .hive/tools before
# typing the prompt; it must sit beside contributor-relay.js.
COPY bin/repo-toolchain.sh /usr/local/bin/
diff --git a/src/docs/contributor-relay.md b/src/docs/contributor-relay.md
index b5486e9acd..302204b4c3 100644
--- a/src/docs/contributor-relay.md
+++ b/src/docs/contributor-relay.md
@@ -200,6 +200,170 @@ The first-task route ends above. The following sections cover custom launch sett
Operators can publish a short **Help & community** list with `contribute.help_links` (Governor → Hub and `/contribute` Management). Onboarding and Operations show it, and `auth_ok` sends it for the relay to print once. Use joinable community links: Discord `https://discord.com/channels//` URLs require existing server membership; `https://hivecommons.dev/discord` lets newcomers join.
+## Apple MLX local inference
+
+This optional **local contributor** route uses the existing **Pi coding agent**
+with a custom `mlx` provider. MLX is the inference framework; **MLX-LM is not a
+coding agent**. Pi owns file edits, shell/test tools, streamed tool execution
+and conversation history; ClankeR retains assignment, GitHub credentials,
+cancellation, progress and PR-result reporting. There is no hosted-provider
+fallback, no new hub backend, and no change to other Pi providers.
+The bundled `mlx-pi-extension.js` delegates to Pi's existing OpenAI-compatible
+stream implementation with a loopback-only, redirect-rejecting fetch transport.
+The private `hive-mlx` API name intentionally cannot run without this extension,
+so a missing/failed extension cannot silently bypass the transport boundary.
+
+### Supported machines and boundaries
+
+- **Apple Silicon Macs only**, macOS **14+**, native arm64 Node and **Python
+ 3.10+**. Intel Macs, Rosetta processes and Linux inference hosts are not
+ supported by this integration. See the [MLX installation requirements](https://ml-explore.github.io/mlx/build/html/install.html).
+- The protocol was checked against **MLX-LM v0.32.2**'s
+ [server implementation](https://github.com/ml-explore/mlx-lm/blob/v0.32.2/mlx_lm/server.py)
+ and Pi's [custom model configuration](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md).
+ The contributor image pins Pi 1.4.0; this route requires **Pi 1.4.0+** for its
+ guarded inference transport. Other MLX-LM versions must pass the same
+ streaming tool-call/result check; older text-only servers will fail it.
+- MLX-LM runs **natively on the Mac**, outside the Linux relay container.
+ The container does not install MLX or access the Apple GPU. Use **Docker
+ Desktop 4.34+** with **Settings → Resources → Network → Enable host
+ networking** enabled by you. See [Docker's host networking limitations](https://docs.docker.com/engine/network/drivers/host/#docker-desktop),
+ including incompatibility with Enhanced Container Isolation. This reuses Pi's
+ existing `--network host` exception and exposes host-local services to the
+ agent container; filesystem/config staging isolation remains unchanged.
+- **Podman machine and Kubernetes are not supported** for this Mac loopback
+ route: their `localhost` is not the Mac. Do not solve that by making MLX-LM
+ listen on `0.0.0.0`. Only literal loopback HTTP URLs ending in `/v1` are
+ accepted; endpoint redirects, credentials in URLs and hosted URLs are refused.
+- Host execution (`just contribute-hive pi local`) retains Pi's existing
+ refusal without `HIVE_PI_DANGEROUSLY_RUN_UNCONFINED=1`. Pi has **no host
+ sandbox** on that path; the container is the recommended coding boundary.
+
+### Explicit setup (source checkout)
+
+On your chosen hive's `/contribute` page, select **Apple MLX**, macOS and
+Containerized mode, then enter your already-downloaded model's exact ID or
+absolute path. The page generates these actual `just` commands; the public
+hub's `/contribute#apple-mlx` section links here too.
+
+Install `just`, `gh`, native Node **22.19+**, and Pi using
+[its official instructions](https://pi.dev), and prepare a **separate native
+Python virtualenv** yourself. These are instructions, not automatic setup:
+ClankeR never installs packages, downloads weights, automatically starts a
+server, or adjusts system memory limits.
+
+```bash
+npm install -g @earendil-works/pi-coding-agent@1.4.0
+python3 -m venv .venv-mlx
+.venv-mlx/bin/python -m pip install 'mlx-lm==0.32.2'
+export HIVE_MLX_PYTHON="$PWD/.venv-mlx/bin/python"
+export HIVE_MLX_ENDPOINT=http://127.0.0.1:8080/v1
+```
+
+Choose and download your model **yourself**, within your available RAM budget.
+Use a model whose tokenizer/chat template and MLX-LM parser support structured
+function calling and tool-result messages. **Not every MLX model can do coding
+tasks**, and passing the small protocol probe is not a coding-quality benchmark.
+Weights, KV cache, long prompts and generation all consume the Mac's **shared
+RAM**. The relay container's 4-GiB limit does **not** cap MLX on the host. Leave
+headroom for macOS and other workloads; do not increase wired-memory limits.
+The [MLX-LM README](https://github.com/ml-explore/mlx-lm#long-prompts-and-generations)
+discusses prompt/cache memory trade-offs.
+
+In a separate terminal, from the checkout, start the server explicitly with
+an **already downloaded** model directory (or fully cached Hub ID).
+`contribute-mlx-serve` validates the native runtime, forces Hugging Face
+offline, and runs MLX-LM in the foreground on the configured loopback endpoint:
+
+```bash
+HIVE_MLX_PYTHON="$PWD/.venv-mlx/bin/python" \
+ just contribute-mlx-serve /Users/YOU/models/tool-coder
+```
+
+Stop it with Ctrl-C when finished; stopping the relay does not unload this
+separately managed host server. A missing cached model fails rather than
+downloading. The equivalent direct command is
+`HF_HUB_OFFLINE=1 "$HIVE_MLX_PYTHON" -m mlx_lm.server --model /Users/YOU/models/tool-coder --host 127.0.0.1 --port 8080`.
+
+Use the **exact ID** returned by
+`curl --fail http://127.0.0.1:8080/v1/models`: for a local directory this is its
+resolved absolute path; a cached Hub model may instead be listed as
+`mlx-community/`. Paths containing whitespace are not supported by Pi's
+contributor model-token contract. Do not select MLX-LM's `default_model` alias:
+ClankeR must declare the actual chosen model to the hive's Model Filter.
+
+The following command **explicitly opts in to two bounded inference requests**
+(up to 256 output tokens and two minutes each). It checks a streamed function
+call and a tool-result round trip; its dummy tool never edits files or runs a
+shell command. Run it only when you have chosen to load the model:
+
+```bash
+just contribute-mlx-setup /Users/YOU/models/tool-coder --verify-tools
+export AGENT_MODEL=mlx//Users/YOU/models/tool-coder
+# Use the URL of the public hive you chose, not the hub directory itself.
+export HIVE_HUB=https://YOUR-CHOSEN-HIVE
+just contribute-check pi
+just contribute-setup pi
+just contribute-mlx
+```
+
+`just contribute-mlx` is the MLX-specific launch entrypoint. It requires an
+`mlx/...` selection and delegates to the existing `just contribute-hive pi`
+coding workflow using Docker; it cannot silently launch another Pi provider.
+An explicitly exported `AGENT_MODEL=mlx/...` wins over a saved model for this
+MLX launch only; otherwise the saved selection must already be `mlx/...`.
+Other Pi launch commands retain their existing profile precedence.
+`just contribute-mlx local` preserves the existing native Pi unconfined
+opt-in gate; it does not set that dangerous flag for you.
+
+For a Hub model ID, the corresponding selection is
+`AGENT_MODEL=mlx/mlx-community/`. Setup preserves unrelated providers
+but replaces Pi's `mlx` provider in `~/.pi/agent/models.json`, and writes a
+matching `hive-mlx.json` receipt there. No provider credentials are needed:
+Pi's `mlx-local` key is an inert availability marker, not a cloud key.
+`PI_CODING_AGENT_DIR` is supported for native/direct invocation; the Justfile
+container staging path uses the standard `~/.pi/agent` directory, so leave
+that override unset for the commands above.
+
+To persist the selection, add your `AGENT_MODEL=mlx/...` line to the existing
+private `~/.config/hive/contributor.env` **after** registration; do not replace
+its hub/token profiles. Keep `HIVE_MLX_PYTHON` pointing to the server's
+virtualenv on subsequent host launches. Optional setup variables
+`HIVE_MLX_CONTEXT_WINDOW` (default `8192`) and `HIVE_MLX_MAX_TOKENS` (default
+`2048`) set Pi's model metadata; choose limits your model/runtime actually
+supports, with output tokens smaller than context. They are not host RAM caps.
+The endpoint and budgets persist in Pi's provider configuration, not the hub.
+Use a contributor image containing this integration; an older pinned image
+does not acquire it just because the host checkout was updated.
+
+In the onboarding UI, choose **Apple MLX** and enter only the model ID/path;
+the generated commands add the `mlx/` provider prefix. Advanced users can
+still select **Pi** and supply the full `mlx/...` selection themselves.
+Registration reports backend `pi`, provider `mlx` and that exact model through
+the existing protocol. The hive may still reject it under its Model Filter or
+trust policy; MLX setup never changes those policies. Both existing interactive
+and headless Pi execution paths are retained.
+
+### Troubleshooting and verification limits
+
+Startup and task launches perform bounded **model-list checks only**, not
+inference probes. Missing runtime, unsupported platforms, missing models,
+changed provider configuration and unreachable endpoints fail explicitly;
+reconfigure with `--verify-tools` after changing the endpoint, model, tokenizer
+or runtime. A receipt records a successful probe, not proof that future weights
+or responses are unchanged. If it works on the host but not in the container,
+verify Docker Desktop host networking, not a bridge-container `localhost`.
+If Pi reports tool/parser errors or context exhaustion, use a supported
+tool-capable model, check its chat template and lower your chosen budgets.
+Task errors and cancellation use the normal Pi failure/revocation paths;
+ClankeR never substitutes a hosted model.
+
+CI exercises mocked streaming HTTP, model/config persistence, platform failures
+and the Pi task lifecycle without a GPU or weights. Actual Apple Silicon model
+inference and Docker Desktop connectivity were **not exercised** while
+implementing this integration; validate your chosen model on your own Mac
+before lending it to a hive.
+
## Docker Compose workflow
diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md
index 9bc216ec03..842849e5e5 100644
--- a/src/docs/env-vars.md
+++ b/src/docs/env-vars.md
@@ -498,6 +498,10 @@ With two or more providers configured, `/login` renders a provider picker; with
| `HIVE_COMMONS_NEEDIEST_REFRESH_MS` | No | `60000` | In `neediest`, milliseconds between `/api/contribute/status` refreshes per subscribed hub. `0` disables the interval. |
| `AGENT_BACKEND` | No | `claude` | Contributor/agent CLI backend selector. |
| `AGENT_MODEL` | No | backend default, or `GOOSE_MODEL` for Goose fallback | Contributor/agent model override. |
+| `HIVE_MLX_PYTHON` | For optional MLX when `python3` is not its native environment | `python3` | Native Apple Silicon Python 3.10+ virtualenv executable containing MLX/MLX-LM; metadata-only preflight never initializes the GPU. [MLX setup](contributor-relay.md#apple-mlx-local-inference). |
+| `HIVE_MLX_ENDPOINT` | No | `http://127.0.0.1:8080/v1` | Optional MLX setup/serve endpoint. Only literal loopback HTTP `/v1` URLs; no credentials, redirects or public hosts. Setup persists it in Pi's `mlx` provider. Docker Desktop host networking connects the relay container to the Mac. |
+| `HIVE_MLX_CONTEXT_WINDOW` | No | `8192` | Pi model context metadata at explicit MLX setup; positive integer. Not a host-RAM limit. |
+| `HIVE_MLX_MAX_TOKENS` | No | `2048` | Pi output metadata at explicit MLX setup; positive integer smaller than context. Not a host-RAM limit. |
| `CONTRIBUTOR_MODE` | No | `interactive` | Contributor relay mode: `interactive` uses tmux; `headless` uses one-shot CLI execution for supported backends. |
| `HIVE_SESSION` | No | backend name (`AGENT_BACKEND`) | Optional session label for running multiple relays concurrently under one GitHub account. The hub keys task leases, assignment cooldowns, failure streaks, and ownership fences on `ContributorID#session`, so distinctly labeled relays hold independent task slots; auth, trust tier, model admission, and rate-limit accounting stay per-account. Sanitized to `[A-Za-z0-9._-]`, max 32 bytes. Set to the empty string to opt out (bare per-account identity, the historical single-session behavior). See `src/docs/contributor-relay.md`, "Running multiple backends under one account". |
| `HIVE_AGENT_ROLE` | No | empty string | Optional contributor role claim sent during relay authentication (for example `scanner`, `quality`, or `outreach`) so the hub can apply role-aware policy. Whitespace is trimmed. |
diff --git a/src/docs/integrations.md b/src/docs/integrations.md
index db761f2718..ba3a237bac 100644
--- a/src/docs/integrations.md
+++ b/src/docs/integrations.md
@@ -41,6 +41,18 @@ container mode by default; local mode needs an explicit opt-in.
Omnigent Opt-in T3 backend-support-tiers.md
+## Local contributor inference
+
+| Integration | Status | Execution and limitations | Docs |
+| --- | --- | --- | --- |
+| Apple MLX / MLX-LM through Pi | **Opt-in** | ClankeR on Apple Silicon macOS 14+, native Python 3.10+, Pi 1.4.0+; user-managed tool-capable models. MLX-LM runs on the Mac; Pi executes tools inside the contributor container with Docker Desktop host networking. No cloud fallback. Live Apple GPU inference remains unverified. | [Install and use with just](contributor-relay.md#apple-mlx-local-inference) |
+
+Apple MLX is a first-class inference-engine choice on `/contribute`, mapped to
+the actual `pi` coding backend and `mlx/` provider selection. It is not
+a standalone coding CLI, hosted gateway, identity provider, or Apple endorsement.
+`KNOWN_BACKENDS` correctly continues to list coding executors, not inference
+frameworks.
+
## Work sources and trackers
The governor reads work through one provider contract. The adapters live in
diff --git a/src/pkg/dashboard/api_contribute_test.go b/src/pkg/dashboard/api_contribute_test.go
index 94f011339c..5870a24695 100644
--- a/src/pkg/dashboard/api_contribute_test.go
+++ b/src/pkg/dashboard/api_contribute_test.go
@@ -469,7 +469,7 @@ func TestContributeLitellmFlavorsMapToLitellmSetup(t *testing.T) {
for _, want := range []string{
// Flavor → real Justfile backend map, and its two consumers.
- `var SETUP_BACKEND={openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm'};`,
+ `var SETUP_BACKEND={openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm',mlx:'pi'};`,
`function setupBackend(v){return SETUP_BACKEND[v]||v;}`,
`var backend=setupBackend(cli);`,
`' 4. just contribute-setup '+setupBackend(v)+'\n'+`,
diff --git a/src/pkg/dashboard/contribute_landing.go b/src/pkg/dashboard/contribute_landing.go
index e810c5f254..65cbf735f4 100644
--- a/src/pkg/dashboard/contribute_landing.go
+++ b/src/pkg/dashboard/contribute_landing.go
@@ -311,6 +311,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;backgrou
h1{font-size:var(--fs-3xl);margin-bottom:var(--sp-4)}
.subtitle{color:var(--text-muted);font-size:1.1rem;margin-bottom:var(--sp-9)}
.subtitle-discord{font-size:var(--fs-md);margin-top:var(--sp-0);margin-bottom:var(--sp-9)}
+.mlx-note{display:none;margin-bottom:var(--sp-5);font-size:var(--fs-sm);color:var(--text-muted)}
.discord-link{color:var(--cc-accent);font-weight:600}
.stat-row{display:grid;grid-template-columns:repeat(auto-fit,minmax(80px,1fr));gap:10px;margin-bottom:var(--sp-8)}
.stat{background:var(--surface-2);border:var(--line-width) solid var(--line-subtle);border-radius:var(--r-lg);padding:var(--sp-5) var(--sp-4);text-align:center;box-shadow:var(--shadow-card)}
@@ -1610,13 +1611,14 @@ select.admin-act{min-width:0;max-width:100%%}
-Choose your CLI:
+Choose your CLI / inference engine:
Claude Code
OpenAI Codex
GitHub Copilot
Pi
+Apple MLX (Pi + local MLX-LM, Apple Silicon)
Oh My Pi
Goose
LiteLLM (Claude Code + your proxy)
@@ -1682,6 +1684,10 @@ select.admin-act{min-width:0;max-width:100%%}
Oh My Pi (omp) has no verified local sandbox. Container mode (the default) is the supported boundary and runs the pinned omp binary from the contributor image. Host mode launches the CLI directly on your machine and refuses to run unless you intentionally opt out with HIVE_OMP_DANGEROUSLY_RUN_UNCONFINED=1; use it only if you understand that trade-off.
+
+
Apple MLX local inference
+Choose
Apple MLX above for copy-pastable installation, model verification and
just contribute-mlx commands. Enter the exact already-downloaded model ID or absolute path (without an
mlx/ prefix) in the Model field. Requires
Apple Silicon , native arm64 Node ≥22.19 and Python ≥3.10, macOS ≥14, Pi ≥1.4.0, and a tool-capable model. Intel Macs and Rosetta are unsupported. MLX-LM runs on your Mac; Pi runs coding tools in the contributor container. Docker Desktop 4.34+ host networking must be enabled by you; Kubernetes and Podman machine cannot reach Mac loopback. Models consume shared host RAM outside the relay container's limit. No automatic weight downloads, public listener, cloud fallback or memory-setting changes. The explicit setup probe runs two bounded inference requests; coding quality and live Mac inference are not certified by that probe.
Setup, RAM budgeting and troubleshooting . Integration names identify compatibility, not Apple endorsement.
+
Contribute to multiple hives: after registering with each hive, set
HIVE_HUB to comma-separated WebSocket URLs and
HIVE_REGISTRATION_TOKEN to the matching comma-separated tokens in the same order. One relay shares one CLI/tmux session, works on one task at a time, keeps each hub connected with its own heartbeat, and rotates only when the active hub says no task is available. Added by
@hanthor in
#2846 .
@@ -1782,8 +1788,37 @@ function isHostOnly(c){return HOST_ONLY_BACKENDS.indexOf(c)>=0;}
// openrouter/vllm/llm-d/watsonx are UI flavors of the litellm backend: the
// Justfile only accepts 'litellm' (#6821), so every generated command must
// say litellm while the option keeps its flavor-specific env exports.
-var SETUP_BACKEND={openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm'};
+// MLX is likewise an inference-engine flavor, backed by the Pi coding CLI.
+var SETUP_BACKEND={openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm',mlx:'pi'};
function setupBackend(v){return SETUP_BACKEND[v]||v;}
+// MLX onboarding generator: pure so CI can execute the actual page logic.
+function mlxShellQuote(value){return "'"+String(value).replace(/'/g,"'\\''")+"'";}
+function mlxCommands(os,mode,runtime,model,hub,branch,prereq){
+ if(os!=='macos')return '# Apple MLX requires Apple Silicon and macOS 14+; Intel, Rosetta, Linux and Windows hosts are unsupported.\n# Select macOS only on a compatible Mac.';
+ if(mode!=='containerized')return '# Apple MLX onboarding uses Containerized mode with Docker Desktop 4.34+ host networking.\n# Kubernetes cannot reach Mac loopback. Native Pi has no sandbox; see the MLX docs for its separate explicit opt-in.';
+ if(runtime==='podman')return '# Podman machine localhost is its Linux VM, not the Mac.\n# Select Docker Desktop 4.34+ and enable host networking yourself; never expose MLX-LM on 0.0.0.0.';
+ var text=prereq+'\n# Apple Silicon, macOS 14+, native Python >=3.10 and Node >=22.19 required.\n'+
+ '# Install/enable Docker Desktop 4.34+ host networking yourself.\n'+
+ 'git clone -b '+mlxShellQuote(branch)+' https://github.com/hivecommons/hive && cd hive\n'+
+ 'npm install -g @earendil-works/pi-coding-agent@1.4.0\n'+
+ 'python3 -m venv .venv-mlx\n'+
+ '.venv-mlx/bin/python -m pip install mlx-lm==0.32.2\n'+
+ 'export HIVE_MLX_PYTHON="$PWD/.venv-mlx/bin/python"\n'+
+ 'export HIVE_MLX_ENDPOINT=http://127.0.0.1:8080/v1\n';
+ if(!model)return text+'# Download a tool-capable model yourself within your shared-RAM budget.\n# Enter its exact ID or absolute path in the Model field above to show the serve/setup/run commands.';
+ if(!/^(?:[A-Za-z0-9]|\/)[A-Za-z0-9._/+:@~-]*$/.test(model)||model==='default_model'||model.indexOf('mlx/')===0)return text+'# Enter an explicit MLX model ID or absolute path without whitespace or an mlx/ prefix, not default_model.';
+ return text+'# No model weights are downloaded by these recipes.\n'+
+ '# In ANOTHER terminal, from this checkout, start your already-downloaded model:\n'+
+ '# HIVE_MLX_PYTHON="$PWD/.venv-mlx/bin/python" just contribute-mlx-serve '+mlxShellQuote(model)+'\n'+
+ '# Wait for the loopback server, then explicitly opt in to two bounded tool-check requests:\n'+
+ 'just contribute-mlx-setup '+mlxShellQuote(model)+' --verify-tools\n'+
+ 'export AGENT_MODEL='+mlxShellQuote('mlx/'+model)+'\n'+
+ 'export HIVE_HUB='+mlxShellQuote(hub)+'\n'+
+ 'export HIVE_CONTAINER_RUNTIME=docker\n'+
+ 'just contribute-check pi\njust contribute-setup pi\njust contribute-mlx\n'+
+ '# To persist: add the AGENT_MODEL line to your existing private contributor.env after registration.\n';
+}
+// End MLX onboarding generator.
var modelRow=document.getElementById('model-row');
var modelInput=document.getElementById('model-input');
function updateCmds(){update();}
@@ -1808,7 +1843,16 @@ var agyNote=document.getElementById('agy-confinement-note');
if(agyNote)agyNote.style.display=(cli==='agy')?'block':'none';
var ompNote=document.getElementById('omp-confinement-note');
if(ompNote)ompNote.style.display=(cli==='omp')?'block':'none';
+var mlxNote=document.getElementById('pi-mlx-note');
+if(mlxNote)mlxNote.style.display=(cli==='pi'||cli==='mlx')?'block':'none';
modelRow.style.display=(modelFlag||cli==='goose')?'flex':'none';
+modelInput.placeholder=cli==='mlx'?'/Users/YOU/models/tool-coder or mlx-community/model':'e.g. claude-sonnet-4-6, gpt-4o';
+if(cli==='mlx'){
+ runtimeGroup.style.display=mode==='containerized'?'inline-flex':'none';
+ cmds.textContent=mlxCommands(os,mode,runtimeSel.value,model,hubURL,'{{HIVE_BRANCH}}',prereq);
+ if(typeof syncBranded==='function')syncBranded();
+ return;
+}
var modelLine='';
if(model){
if(cli==='goose'){modelLine='export GOOSE_MODEL='+model+'\n';}
@@ -1878,6 +1922,7 @@ claude:' ',
copilot:' ',
pi:' ',
+mlx:' ',
goose:' ',
litellm:' ',
openrouter:' ',
@@ -1900,6 +1945,7 @@ claude:{name:'Claude Code',tag:'Anthropic',peer:true,
codex:{name:'Codex',tag:'OpenAI',peer:true},
copilot:{name:'GitHub Copilot',tag:'GitHub',peer:true},
pi:{name:'Pi',tag:'pi.dev',peer:true},
+mlx:{name:'Apple MLX',tag:'local · Apple Silicon · Pi',peer:true},
goose:{name:'Goose',tag:'Block (Ollama)',peer:true},
litellm:{name:'LiteLLM',tag:'your proxy',peer:true},
openrouter:{name:'OpenRouter',tag:'your key',peer:true},
@@ -1946,6 +1992,7 @@ function buildTiles(){
}
function defaultPromptFor(v){
var c=CLIENTS[v]||{name:v};
+ if(v==='mlx')return 'Help me set up LOCAL ClankeR inference with Apple MLX-LM and the Pi coding runner. Use the Apple MLX section on /contribute and its exact just recipes: contribute-mlx-serve, contribute-mlx-setup --verify-tools, contribute-setup pi, contribute-mlx. Verify Apple Silicon, native Python >=3.10, macOS >=14, Pi >=1.4.0 and Docker Desktop host networking. Do not install packages, download weights, start inference, change memory settings or run the explicit tool probe without my consent. Never invent an mlx coding CLI or a hosted fallback. Hub: '+hubURL;
return 'Help me contribute to this hive using '+c.name+' on my machine.\n'+
'The hive hub is: '+hubURL+'\n\n'+
'Please walk me through, step by step, using the official setup:\n'+
@@ -2020,6 +2067,7 @@ if(pbCopy&&promptText){
});
}
buildTiles();
+if(window.location.hash==='#apple-mlx'){sel.value='mlx';}
update(); // initial paint: copy block + branded UI in sync from first load
// ── end #2548 ───────────────────────────────────────────────────────────────
})();
diff --git a/src/pkg/dashboard/contribute_mlx.test.js b/src/pkg/dashboard/contribute_mlx.test.js
new file mode 100644
index 0000000000..926609e826
--- /dev/null
+++ b/src/pkg/dashboard/contribute_mlx.test.js
@@ -0,0 +1,56 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const source = fs.readFileSync(path.join(__dirname, 'contribute_landing.go'), 'utf8');
+const generator = source.split('// MLX onboarding generator:')[1].split('// End MLX onboarding generator.')[0];
+const context = {};
+vm.runInNewContext(generator.slice(generator.indexOf('\n')), context);
+const commands = (os = 'macos', mode = 'containerized', runtime = '', model = '/Users/example/models/coder') =>
+ context.mlxCommands(os, mode, runtime, model, 'https://chosen.example', 'v5', 'brew install just gh');
+
+test('MLX picker generates the real Pi-backed just workflow and safe host/container boundary', () => {
+ const script = commands();
+ for (const wanted of [
+ 'python3 -m venv .venv-mlx', 'pip install mlx-lm==0.32.2',
+ 'just contribute-mlx-serve \'/Users/example/models/coder\'',
+ 'just contribute-mlx-setup \'/Users/example/models/coder\' --verify-tools',
+ 'export AGENT_MODEL=\'mlx//Users/example/models/coder\'',
+ 'export HIVE_HUB=\'https://chosen.example\'',
+ 'export HIVE_CONTAINER_RUNTIME=docker',
+ 'just contribute-setup pi', 'just contribute-mlx\n',
+ ]) assert.ok(script.includes(wanted), wanted);
+ assert.ok(!script.includes('just contribute-setup mlx'));
+ assert.ok(!script.includes('0.0.0.0'));
+ assert.ok(script.includes('# HIVE_MLX_PYTHON='), 'foreground model server is a separate, explicit terminal step');
+ assert.match(source, / {
+ for (const args of [
+ ['linux'], ['windows'], ['macos', 'kubernetes'], ['macos', 'host'],
+ ['macos', 'containerized', 'podman'],
+ ['macos', 'containerized', '', 'model;touch /file'],
+ ['macos', 'containerized', '', 'default_model'],
+ ['macos', 'containerized', '', 'mlx/provider/model'],
+ ['macos', 'containerized', '', ''],
+ ]) {
+ assert.ok(!commands(...args).includes('just contribute-mlx\n'), JSON.stringify(args));
+ }
+ assert.equal(context.mlxShellQuote("a'b"), "'a'\\''b'");
+ assert.ok(commands('macos', 'containerized', '', 'mlx-community/coder').includes("AGENT_MODEL='mlx/mlx-community/coder'"));
+});
+
+test('MLX is additive; existing backend defaults and generic command templates remain', () => {
+ assert.match(source, /var containerTpl='PREREQ\\ngit clone/);
+ assert.match(source, /var SETUP_BACKEND=\{openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm',mlx:'pi'\}/);
+ assert.match(source, /if\(cli==='mlx'\)\{[\s\S]*?return;\n\}\nvar modelLine=''/);
+ assert.match(source, / Local AI inference
`)
+ if start < 0 {
+ t.Fatal("public homepage missing local AI inference group")
+ }
+ group := strings.SplitN(body[start:], ``+"\n ", 2)[0]
+ for _, want := range []string{`href="/contribute#apple-mlx"`, "Apple MLX", "Apple Silicon", "Pi coding agent", "not Apple", "just"} {
+ if !strings.Contains(strings.ToLower(group), strings.ToLower(want)) {
+ t.Errorf("local inference integration missing %q", want)
+ }
+ }
+ signIn := strings.SplitN(strings.SplitN(body, `Sign-in
`, 2)[1], ``, 2)[0]
+ if strings.Contains(signIn, "Apple MLX") {
+ t.Error("Apple MLX must not be presented as Apple sign-in")
+ }
+}
+
func TestHubContributeLandingListsPublicContributorHives(t *testing.T) {
t.Setenv("HIVE_HUB_PUBLIC_URL", "https://hive.hivecommons.dev")
s := newHubServerForTest(t)
diff --git a/src/pkg/hub/server.go b/src/pkg/hub/server.go
index 33926d44b5..d4fe6103c9 100644
--- a/src/pkg/hub/server.go
+++ b/src/pkg/hub/server.go
@@ -4823,6 +4823,23 @@ func (s *HubServer) handleContributeLanding(w http.ResponseWriter, r *http.Reque
Public hives accepting contributions
%[2]s
+
+ Apple MLX: local ClankeR inference
+ Apple Silicon only: macOS 14+, native arm64 Python 3.10+ and Node 22.19+. Intel Macs and Rosetta are unsupported. MLX-LM runs on your Mac; Pi 1.4.0+ supplies the coding tools in the contributor container. This is optional local inference, not Apple sign-in, a hosted Hive backend or an Apple endorsement.
+ Choose a hive above and select Apple MLX on its contributor page for OS-aware installation and copyable commands. Install just, gh, Pi and MLX-LM in a native Python virtualenv as described in the setup guide. Docker Desktop 4.34+ requires you to enable host networking. Podman machine and Kubernetes cannot use this loopback-only Mac route.
+ # From your Hive source checkout, with HIVE_MLX_PYTHON pointing to your virtualenv:
+# Terminal 1: explicitly load your already-downloaded, tool-capable model:
+just contribute-mlx-serve /Users/YOU/models/tool-coder
+# Terminal 2: explicitly request two bounded tool-call verification turns:
+just contribute-mlx-setup /Users/YOU/models/tool-coder --verify-tools
+export AGENT_MODEL=mlx//Users/YOU/models/tool-coder
+export HIVE_HUB=https://YOUR-CHOSEN-HIVE
+just contribute-check pi
+just contribute-setup pi
+just contribute-mlx
+ Download model weights yourself within your shared-RAM budget; the relay container limit does not cap host inference memory. No automatic weight downloads, public listener, cloud fallback or memory-setting changes. Not every model supports tools; the protocol probe is not a coding-quality benchmark. Live Mac inference is not certified by mock CI.
+ Complete installation, model requirements and troubleshooting
+