Troubleshoot the MLX compute agent on your Mac

Check the installed agent version first

For an AI agent, read the operating guide before changing the Mac. Start with the installed copy when it exists:

node "$HOME/.proxies-compute/compute-agent.js" --status

The published agent is 0.3.3. A newly downloaded script's status command reports that script's version; it does not prove the background service was upgraded. Compare the installed path with agentVersion in the farmer Compute dashboard. Do not run the script without a flag while its service is active: that starts a second foreground agent. Agent source

A loaded launchd service, a listening local port and a model ready in the dashboard are different observations. Check the matching device and any occupying rental before restarting, reinstalling or replacing credentials. Active rentals, cancelled grace and outage-paused terms still reserve the Mac. Coordinate necessary maintenance through farmer support first.

Diagnose credentials without exposing them

Agent 0.3.3 supports a safe supplier-access check:

node "$HOME/.proxies-compute/compute-agent.js" --doctor

If the installed copy does not support this flag, download and inspect the current script in a separate working directory, then run node compute-agent.js --doctor without installing it. The check reads authenticated supplier pricing and prints the selected credential source, status and result code. It never prints the key.

An API_KEY environment variable overrides the saved configuration. Check the saved key separately without printing either secret:

env -u API_KEY node compute-agent.js --doctor

For an authorized credential replacement on a free Mac, create a Compute supplier key in farmer API keys and run the current script:

node compute-agent.js --configure-key
env -u API_KEY node compute-agent.js --doctor

The owner enters the new key at a hidden terminal prompt. --configure-key validates before saving, preserves identity/model files and does not restart a running service. A rejected key leaves the prior configuration unchanged. It prints the precise launchctl kickstart command for this user's service; execute it only when an interruption is safe and intended. Never delete state.json to force registration or paste config.json, state.json, environment variables or keys into a support chat.

Diagnose architecture and Python runtime errors

The documented minimums are Apple Silicon with 24 GB memory, macOS 14, native arm64 Node.js 18 and native arm64 Python 3.10. These read-only commands identify the executables in use:

node -p 'process.arch + " " + process.version'
python3 -c 'import platform, sys; print(platform.machine(), sys.version.split()[0])'
sw_vers -productVersion

Use a supported Node release that meets the checks. Intel/Rosetta processes fail the architecture requirement. Node.js release schedule

The private runtime is ~/.proxies-compute/runtime-0.31.3. A global terminal reporting mlx_lm.server: command not found does not establish that the agent's private environment is broken. Inspect its installed packages directly:

~/.proxies-compute/runtime-0.31.3/bin/python3 -m pip show mlx-lm mlx transformers

The supported pins are MLX LM 0.31.3, MLX 0.31.2 and Transformers 5.4.0. Keep those packages in the agent's environment; an unrelated global pip installation is not a repair for it. Python environment behavior

Check free disk and the pinned model download

Installation requires at least 26 GB free. Model downloads also require the selected approximate weight size plus 10 GB on the cache volume. HF_HOME or HF_HUB_CACHE can place it on a different disk. Larger models need more headroom. Agent disk checks

A repository directory can exist while its requested revision is incomplete. The agent checks the snapshot's configuration and weight files before serving it. Compare the expected immutable hash with the catalog revision. Hub download documentation

Preserve the first redacted error and check connectivity to that repository. Allow advancing downloads to finish. Do not delete the entire shared cache as a routine fix; other applications may use it.

Check the local model endpoint

The default server listens only on loopback port 8734. Substitute a configured MLX_PORT if different:

curl --fail --show-error --max-time 5 http://127.0.0.1:8734/v1/models

A successful response means a local server answered. Its served model must match the assigned snapshot; another process on that port is not readiness evidence. The agent refuses to kill an unrelated process using the port. Do not start another model server there. A refused connection is a runtime observation, not proof that the account key is wrong.

Match the dashboard state to the next check

Admission requires a valid passing measurement no more than 24 hours old. Missing, invalid or expired measurements are automatically refreshed for eligible free ready unapproved nodes, with at least an hour between attempts. admission.automaticBenchmark means eligible, not queued. Already approved free nodes use a seven-day maintenance interval; expiration of the 24-hour admission window alone does not revoke approval. A larger model can require remeasurement. No automatic benchmark interrupts an occupied or admin-blocked node.

Generic verified is not Compute approval. Listing intent alone is not marketplace capacity. Admin approval checks the exact measured model's current readiness, the valid measurement and current countersigned agreement. Admission reference

Collect useful evidence for support

Inspect a small relevant excerpt from ~/Library/Logs/proxies-compute.log locally. Runtime errors can contain customer text. Redact credentials, personal paths, customer prompts and unrelated data before sending a farmer support ticket. Include observation time, matching device ID, agent/macOS version, chip/RAM, model state, safe doctor code, admission/pending state and whether a rental is affected.

The generation deadline is 175 seconds with a 60-second gap-without-output limit; the API's default request deadline is 180 seconds. These are recovery limits, not latency or throughput promises. Use the benchmark worksheet to record prompt/output size and concurrency for workload timeouts.

Report each observed gate and its next action to the owner. If admin review is pending, keep the Mac ready and state that review is pending. After approval, review the admin-set price/share, enable List for rent and confirm the actual state. Do not report onboarding, paid demand or payout as complete merely because the local service runs.