DEV Community: Javier Cañete Arroyo

REA: a reverse engineering MCP for coding agents, tested with Ghidra and Electron

Javier Cañete Arroyo — Wed, 21 Oct 2026 09:11:38 +0000

REA (Reverse Engineer Anything) is a Model Context Protocol (MCP) server and command-line interface (CLI) that gives your coding agent reverse engineering tools: decompile binaries with Ghidra, Hopper or IDA, rebuild Electron apps, read .NET assemblies and observe websites. It installs from the rea-agents npm package, is MIT-licensed and is maintained by the morluto GitHub account. I tested it on 18 October 2026 in an arm64 Docker container with rea-agents 6.7.0, Node.js 24.21.0 and Ghidra 12.1.4. Here is what worked, what it weighs and what to check before you let it touch your agents’ configuration. The Spanish version is also available.

Key takeaways

rea-agents 6.7.0 exposes 207 MCP tools and 6 prompts, and its CLI has 153 commands. The tool list is 3,158,352 bytes of JSON; the compact profile cuts it to 219,211.
Static analysis of the Hyper 3.4.1 Electron app (a 14 MB app.asar) walked 2236 files, found 18 inter-process communication (IPC) channels and 6 native add-ons, and produced a 253 MB JSON evidence file.
With Ghidra 12.1.4 it decompiled a stripped C binary and recovered the validation logic with its constants: 31, 9973 and 4242.
On Linux arm64, the official Ghidra ZIP ships no native decompiler: you build it with gradlew buildNatives.
rea setup rewrites your agents’ configuration with backups, and rea uninstall reverts it. Try it against a fake HOME first.
The npm package is published from GitHub Actions with SLSA provenance, and npm audit signatures verifies it.

What REA is and what it analyzes

REA is a tool layer, not a model. Its setup can configure 24 clients, among them Claude Code, Codex, Cursor and Gemini CLI. Your agent calls REA over MCP, and REA runs the analysis on your machine and returns results with their evidence and limits. If the protocol is new to you, start with the MCP guide for 2026.

According to the project README, it covers these target types:

Native binaries: pseudocode, assembly, strings, symbols and references, with Hopper, Ghidra or IDA as the engine
JavaScript and Electron: modules, imports, source maps, IPC channels and native add-ons, with no external engine
.NET assemblies: metadata and Common Intermediate Language (CIL) instructions, without loading the assembly
Websites: structure, scripts and observed traffic, with a Chrome-family browser
Android APKs: classes and methods decompiled with JADX, plus 15 other families (Go, Rust, WASM, SQLite, firmware, network captures)

Static JavaScript and .NET analysis reads the files without running them. Runtime capture does run the target with your permissions, and the documentation flags it in each guide.

Who maintains it and how much traction it has

The morluto/rea repository was created on 14 April 2026 and belongs to a personal GitHub account. The rea-agents package appeared on npm on 12 July 2026 and has 33 versions; 6.7.0 shipped on 18 October at 08:12 UTC. It was earlier published as @morluto/rea, whose version 0.2.1 described itself as automation "for Hopper Disassembler".

The popularity figures are unusual. The GitHub API returned 314,700 stars, 79,773 forks and 1213 open issues on 18 October 2026 at 11:28 UTC. The npm downloads API reported 307,234 downloads of rea-agents for the week of 10 to 16 October and 346,782 for the previous 30 days. I am not interpreting them: they are what the two APIs returned that day.

How to install it without touching your real configuration

Install it inside a container with its own HOME, because setup and update rewrite agent configuration files. You need Node.js 22.19 or later, 24.11 or later, or 26. On Linux, REA also requires the procps ps to check who owns each process it launches, and the node:24-slim image lacks it:

docker run -d --name rea-lab -e HOME=/home/lab -w /home/lab \
  node:24-slim sleep infinity
docker exec rea-lab bash -c 'apt-get update -qq && \
  apt-get install -y -qq procps curl jq'
docker exec rea-lab npm install --global rea-agents@6.7.0
docker exec rea-lab rea --version

The command prints 6.7.0. The installed package takes 222 MB with its 158 dependencies, because it bundles Playwright, a terminal emulator and the MCP SDKs. rea doctor lists what is missing: in a clean container every native engine (Hopper, Ghidra, IDA, JADX, Kuna) shows up as missing_analysis_engine, and JavaScript analysis works regardless.

How to analyze an Electron app without running it

analyze-javascript-application reads an app.asar (the archive Electron packs the app’s code into) or an extracted folder and rebuilds its module graph. I tested it with Hyper 3.4.1, Vercel’s MIT-licensed terminal, downloading its arm64 .deb inside the container:

cd /home/lab && mkdir targets && cd targets
curl -sSLO https://github.com/vercel/hyper/releases/download/\
v3.4.1/hyper_3.4.1_arm64.deb
dpkg-deb -x hyper_3.4.1_arm64.deb hyper
rea analyze-javascript-application \
  /home/lab/targets/hyper/opt/Hyper/resources/app.asar \
  --format json > /home/lab/hyper.json

The command exited with code 0 after 4 minutes, with a system load average below 3 during the measurement. The result is a 253 MB JSON file: a graph with 10,552 nodes and 14,909 relationships, of which 4853 are imports and 15 are IPC sends. Among the findings:

18 IPC channel nodes and 5 handlers, such as electron-store-get-data in the main process
14 IPC operations with a dynamic channel name that REA leaves unresolved instead of guessing
6 native add-ons, including node-pty/bin/linux-x64-107/node-pty.node and three win32 binaries of native-reg inside a Linux arm64 package

The result is also honest about its gaps. 1994 files, nearly all in node_modules, carry a resource_constraint mark because their expanded relationships did not fit the memory limit. The evidence states it instead of dropping them.

How to summarize a 253 MB evidence file

An agent cannot read 253 MB of context, so REA projects views over the saved evidence. The CLI guide suggests wrapping it with jq and asking for the summary view:

jq -c '{source: {kind: "inline", evidence: .},
        view: {kind: "summary"}}' hyper.json > hyper-view.json
rea inspect-analysis-view hyper-view.json --format json \
  > hyper-summary.json

The summary is 22,843 bytes: one window, 22 IPC operations, 7 literal channels and no preload script. That is the piece you would hand to the agent.

Which Electron fuses are enabled

inspect-electron-fuses reads the "fuses" Electron writes into the executable, without launching it. In the 147 MB hyper binary, RunAsNode, EnableNodeOptionsEnvironmentVariable and EnableNodeCliInspectArguments were enabled, and EnableEmbeddedAsarIntegrityValidation and OnlyLoadAppFromAsar were disabled. That is useful when auditing an app: with RunAsNode on, the executable agrees to run as a plain Node.js.

How to decompile a native binary with Ghidra on Linux arm64

REA accepts Ghidra 12.1.x with a Java Development Kit (JDK) 21 or later. On arm64 there is a prior step the documentation warns about: the official Ghidra 12.1.4 ZIP (570 MB) ships the native decompiler for linux_x86_64 and win_x86_64, but not for linux_arm_64. I built it with the Gradle wrapper the distribution includes, after installing gcc, g++, make, bison and flex and a Temurin JDK 21:

export JAVA_HOME=/opt/jdk21 PATH=/opt/jdk21/bin:$PATH
cd /opt/ghidra_12.1.4_PUBLIC/support/gradle
./gradlew buildNatives
export GHIDRA_INSTALL_DIR=/opt/ghidra_12.1.4_PUBLIC
rea doctor | grep -A3 ghidra-native_decompiler

The build ended with BUILD SUCCESSFUL and rea doctor turned green: "decompile reports elf arm64, which matches linux/arm64". As a target I compiled a 17-line C program that validates a key with a checksum, and stripped its symbols with strip. The resulting binary is 67,616 bytes. Then I asked REA to find a string and follow its references:

rea trace licencia.stripped "clave valida" --provider ghidra \
  --format json | jq -c '.normalized_result.references[0]'
rea decompile licencia.stripped 0x1007d4 --provider ghidra \
  --format json

trace found the string at 0x1008c8, referenced from 0x100880 inside the 192-byte function FUN_001007d4. decompile returned this pseudocode:

    iVar4 = 7;
    for (; __s != pbVar1; __s = __s + 1) {
      iVar4 = (int)(iVar4 * 0x1f + (uint)*__s) % 0x26f5;
    }
    if (iVar4 == 0x1092) {
      puts("clave valida");
      uVar3 = 0;
    }

The constants match my source code: 0x1f is 31, 0x26f5 is 9973 and 0x1092 is 4242, with the helper function already inlined into main by the compiler. Each CLI command is a new process that imports the binary into a temporary Ghidra project and deletes it on close. To chain queries, use --snapshot or the MCP server, which keeps the session open.

Which tools the MCP server exposes

You start the server with rea mcp and it speaks MCP over standard input and output. I queried it with a 25-line Node.js client that sends initialize and pages through tools/list. It answered as rea 6.7.0, protocol 2025-06-18, with 207 tools and 6 prompts: investigate_feature, compare_application_versions, verify_reconstruction, trace_crash, audit_residual_unknowns and prepare_bounded_process_capture.

The tools fall into families:

Native session: open_binary, close_binary, procedure_pseudo_code, procedure_callers, xrefs, search_strings, batch_decompile, get_call_graph
High-level workflows: binary_overview, analyze_function, trace_feature, trace_call_path
JavaScript and Electron: analyze_javascript_application, trace_application_feature, inspect_electron_fuses, capture_electron_scenario
Web: inspect_web_page, analyze_web_bundle, capture_browser_scenario
Android and debugging: 26 adb tools, plus Frida, GDB and Rizin sessions

The catalog is heavy, and that costs context in every agent session. The MCP contracts documentation records that kimi-cli rejected requests with the full catalog and offers two variables: REA_MCP_INPUT_SCHEMA_PROFILE=compact and REA_MCP_OUTPUT_SCHEMA_PROFILE=off. With both, the same tools/list went from 3.16 MB to 0.22 MB:

Size of the REA 6.7.0 tools/list response bytes · lower is better

Full (default)3158352Compact input, output off219211Show the data table

Schema profile	bytes
Full (default)	3158352
Compact input, output off	219211

207 tools in both cases. Measured on 18 October 2026 with rea-agents 6.7.0 in arm64 Docker, serializing the tools array to JSON.

What rea setup changes in your agents’ configuration

rea setup registers the MCP server in the agents you pick and installs an investigation skill. I ran it in the container against a fake HOME with a minimal ~/.claude.json and ~/.codex/config.toml. First with --dry-run, which only returns the plan:

export HOME=/home/fake
rea setup --client claude_code --client codex --dry-run --format json
rea setup --client claude_code --client codex --yes --format json

The plan announced four actions, and the run did exactly that:

~/.claude.json: adds "rea": {"command": "/usr/local/bin/rea", "args": ["mcp"]} under mcpServers, keeps the existing entry and reformats the file with indentation
~/.codex/config.toml: adds a [mcp_servers.rea] table with startup_timeout_sec = 30 and tool_timeout_sec = 450
Backups: leaves .claude.json.rea.backup and config.toml.rea.backup next to each file
Skill: copies reverse-engineer-anything (88 KB, 7 files) into ~/.agents/skills/ and ~/.claude/skills/

rea uninstall with no options removed both registrations and the skill, and also left a .recovery copy of the previous state. If you use Claude Code every day, first check which MCP servers your editor already registers, because setup adds one with 207 tools.

How to verify the package is the official one

The README warns about copies: "A similar repository name or copied README does not establish that a download is official". There are three official sources: the morluto/rea repository, the rea.tools site and the rea-agents npm package. The package is published from GitHub Actions with an OIDC trusted publisher and an SLSA (Supply-chain Levels for Software Artifacts) provenance attestation, and npm checks both:

mkdir verify && cd verify && npm init -y
npm install --ignore-scripts rea-agents@6.7.0
npm audit signatures

The output was "174 packages have verified registry signatures" and "36 packages have verified attestations". The rea-agents@6.7.0 attestation points at the .github/workflows/release.yml workflow of the https://github.com/morluto/rea repository, branch release/6.7.0. Also pin the exact version in your agent’s MCP registration instead of @latest: it is the defence against supply chain attacks that arrive with an update. The package declares no postinstall scripts.

The project itself states the limit of its isolation. Its security policy reads: "This is not a sandbox and does not protect against malicious processes already running as the same operating-system user." Opening an untrusted binary hands its analysis to Ghidra or Hopper with your permissions, so do it in a container or a virtual machine, as with any agent that has tool access.

What EU law allows for reverse engineering

Decompiling a program is not illegal in itself in the European Union, but it comes with conditions. Directive 2009/24/EC sets two exceptions that need no permission from the rightholder:

Article 5(3): whoever has the right to use a copy may "observe, study or test the functioning of the program in order to determine the ideas and principles" while loading, running or storing it
Article 6: they may reproduce and translate the code when it is "indispensable to obtain the information necessary to achieve the interoperability of an independently created" program, limited to the parts needed

Article 6(2) forbids using what you obtain for another purpose or to build a program that copies the original’s expression. Article 8 makes licence clauses contrary to those exceptions void. In Spain, the Intellectual Property Act carries them in Article 100, sections 3, 5 and 6. With an end-user licence agreement (EULA) that forbids decompiling, interoperability is still covered in the EU; every other use depends on what the licence says.

REA takes that line in its DISCLAIMER.md: the project will not help bypass copy protection (DRM), licence checks or anti-cheat systems, and it requires legitimate licences for IDA Pro, Hopper or JEB.

How it compares with GhidraMCP, IDA Pro MCP and radare2-mcp

REA is not the first bridge between a disassembler and an agent; what changes is the scope. The other three projects connect a single engine, while REA orchestrates six engines under a common evidence contract:

Project	Engine	What it covers	Licence
REA	Ghidra, Hopper, IDA, Kuna, JADX, Rizin	Native, Electron, .NET, Android, web, network captures	MIT
GhidraMCP	Ghidra with a plugin	Native binaries inside Ghidra	Apache 2.0
IDA Pro MCP	IDA Pro 8.3 or later	Native binaries; its author now recommends the official Hex-Rays server	MIT
radare2-mcp	radare2, written in C	Native binaries, with a read-only mode	MIT

If you only decompile binaries and already live in IDA or Ghidra, a single-engine bridge adds less surface. REA pays off when the question crosses layers, such as following a feature of an Electron app from the renderer down to a native add-on.

Frequently asked questions

Does REA upload my binaries to a server?

No. The analysis runs on your machine, according to the README. What does leave it is whatever REA returns to your agent, which sends it to its model provider under that provider’s own data policy.

Do I need Hopper, Ghidra or IDA?

Only for native binaries. JavaScript, Electron and .NET analysis worked in my test with no engine at all. For Ghidra on Linux arm64, plan on building the native decompiler.

Is it legal to use REA on a commercial app?

It depends on the use and your jurisdiction. In the EU you may study how it works and decompile what interoperability needs even if the licence says otherwise; copying its code or bypassing a protection is not covered.

Conclusion

REA delivers on the two parts I tested. It rebuilt the structure of a real Electron app without running it and, with Ghidra, returned the exact constants of a stripped binary. In exchange it weighs 222 MB, adds 207 tools to your agent’s context and ships a new version almost every day. If you want to try it, do it as here: in a container, with the version pinned, npm audit signatures before installing and a --dry-run before letting setup touch your configuration.

Sources: [1] morluto/rea repository on GitHub, [2] REA installation and setup, [3] REA MCP contracts, [4] REA security policy, [5] rea-agents on npm, [6] Case studies on rea.tools, [7] Directive 2009/24/EC on EUR-Lex, [8] Spanish Intellectual Property Act on BOE, [9] Ghidra 12.1.4 on GitHub.

Originally published on jacar.es.

What Obscura is, the Rust headless browser for AI agents

Javier Cañete Arroyo — Sun, 18 Oct 2026 20:52:39 +0000

Obscura landed on GitHub in April 2026 and has collected 24,624 stars in five months. Cloudflare’s engineering team credits it as the starting point for their own agent browser, and the project already advertises a managed version. Here is what it actually does, what the numbers looked like when I ran it on my own machine, and where it genuinely replaces headless Chrome.

Key takeaways

Obscura is a headless browser engine written in Rust under an Apache-2.0 licence. It runs JavaScript on V8 and speaks the Chrome DevTools Protocol.
Playwright and Puppeteer connect without a single code change: point connectOverCDP at the port obscura serve opens.
Its reproducible advantage is memory. In my tests it used about 38 MB per session against 532 MB for headless Chromium on the same page.
The speed advantage depends on the page: obvious on static HTML, absent on a real site where network latency dominates.
Since version 0.2.0 (August 2026) it renders and captures without Chromium, but it does not match Chromium yet, and I hit that on the first page I gave it.

What Obscura is and what problem it solves

Obscura is a browser engine with no graphical interface, written from scratch in Rust. It is not a Chromium fork or a WebKit patch. It embeds V8 to run the page’s JavaScript, builds its own DOM, and exposes the Chrome DevTools Protocol so existing automation tools treat it as if it were Chrome. The official documentation defines it this way: "Obscura is an open-source headless browser engine written in Rust. It runs JavaScript via V8, speaks the Chrome DevTools Protocol, and works as a drop-in replacement for headless Chrome with Puppeteer and Playwright".

The problem it attacks is cost, not capability. Headless Chrome automates a page perfectly well, but it was designed for one person looking at one tab.

When a swarm of agents opens thousands of concurrent sessions, every process drags along a compositor, a rendering stack and dozens of subsystems no agent ever touches. You pay for that in gigabytes of memory and in seconds of startup. Obscura’s proposal is to keep only the part that matters for reading data: run the JavaScript, build the DOM, hand it back.

The Cloudflare connection is the strongest signal that the idea holds up. In the Kitesurf announcement, describing their agent browser built on Workers, the team writes: "We got the initial inspiration from obscura, a headless engine written in Rust for AI automation that has ‘no Chrome, no Node.js, no dependencies’". Cloudflare ported Obscura to Workers as a first proof of concept in May 2026 and built the product from there. Kitesurf is still a Cloudflare service in free beta; Obscura is the engine you can download today.

How it works inside

The binary bundles three pieces. The first is V8, the same JavaScript engine Chrome uses, embedded directly in the Rust process. The second is its own implementation of the DOM and the web APIs a modern page needs: fetch, XHR, observers, Shadow DOM, custom elements, WebCrypto and the rest. The third is the CDP server, which translates Puppeteer or Playwright calls into operations on that DOM.

Since version 0.2.0, released on 8 August 2026 with 449 accumulated commits, there is a fourth piece. It is a layout and paint engine also written in Rust, which allows screenshots, screencasting and PDF export without starting Chromium. Version 0.2.1, from 23 August, added dedicated V8 realms for child iframes.

Installing it needs neither Node.js nor Chrome. The project publishes binaries for Linux, macOS and Windows, in variants with and without rendering and with and without stealth mode, plus an official image on Docker Hub with 45,789 pulls.

curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-linux.tar.gz
tar xzf obscura-aarch64-linux.tar.gz

./obscura fetch https://example.com --eval "document.title"
./obscura fetch https://example.com --dump markdown

./obscura serve --port 9222 --stealth

Stealth mode is a separate build variant. According to the project README it randomises the GPU, screen, canvas, audio and battery fingerprint on every session, leaves navigator.webdriver undefined and blocks 3,520 tracking domains. Those are the project’s own figures, not a third party’s.

It also ships an embedded Model Context Protocol server with fourteen browser tools an assistant can call directly. If you have built your own servers before, the complete MCP guide has the context for that protocol.

What happened when I ran it on my own machine

I downloaded the aarch64-linux variant of v0.2.1 and ran it in an ARM64 Linux container on 4 September 2026, measuring wall time and peak resident memory across the process tree. Facing it I put headless Chromium driven by Playwright, on the same URLs and the same network. Three passes per combination.

Page	Obscura v0.2.1	Headless Chromium
example.com	92 ms, 13 MB	237 ms, 510 MB
news.ycombinator.com	1,550 ms, 38 MB	1,430 ms, 532 MB

The honest reading of those numbers has two halves. The memory advantage is huge and it holds: roughly thirteen times less on the real page.

The speed advantage evaporates as soon as the page stops being a static 500-byte file. On Hacker News, Chromium was even slightly faster, because what dominates the median is the network, not the engine. Dropping --wait to zero changed nothing.

The project’s own benchmark repository reaches the same conclusion with more data. Over a corpus of 98 real public pages, Obscura rendered 94 and headless Chrome rendered 85. Median memory was 64.2 MB against 201.2 MB, but median latency was 5.2 seconds against Chrome’s 2.1 seconds. That is how the cards actually fall.

Playwright compatibility turned out to be literal. I started obscura serve --port 9333 and connected with chromium.connectOverCDP('ws://127.0.0.1:9333') without touching anything else: navigation, page.title() and page.evaluate() all answered in 100 milliseconds.

Then I tried the new rendering path on the front page of a Tailwind-based WordPress site. The capture took 587 milliseconds and produced a valid PNG, but with clear differences against Chromium.

The most concrete difference: the theme declares its navigation-bar labels as ::after pseudo-elements with content: attr(data-tooltip) and opacity: 0, visible only on hover. Obscura painted the pseudo-element but ignored the opacity, so the header came out covered in overlapping labels. The search panel also rendered open and the cookie notice was missing. This is exactly the class of gap the project declares in its release notes, found on the first page I fed it.

How it compares with headless Chrome and Lightpanda

There are four families of solutions and it is worth keeping them apart, because they solve different things. GitHub figures from 4 September 2026.

Option	Engine	Licence	Stars	What it solves
Obscura	Own, in Rust	Apache-2.0	24,624	Memory cost per session
Lightpanda	Own, in Zig	AGPL-3.0	34,414	The same, with more history
Headless Chrome with Playwright	Chromium	Apache-2.0	95,604	Full rendering fidelity
Steel Browser or Browserless	Wrapped Chromium	Apache-2.0 or custom	7,591 and 13,658	Running the infrastructure

Lightpanda is the direct rival: same premise of a new engine, written in Zig, two years older and with more stars. The difference that ends up deciding it is legal rather than technical.

Lightpanda uses AGPL-3.0, which propagates to any service that exposes it over the network. Obscura uses Apache-2.0, which does not. If you plan to embed it in a closed product, that line in the LICENSE file weighs more than any benchmark.

Steel Browser and Browserless do not compete with Obscura: they wrap Chromium with queues, sessions and an API. They solve operations, not cost per session. Browserless is also not open source, it is free only for non-commercial use.

Then there is the agent ecosystem that already drives a browser. If what you want is an agent that browses for you, Browser Use works one layer above; if what you want is clean web data, Firecrawl does the extraction for you. Obscura lives underneath all of them, as an engine replacement.

What it does not do well yet

The rendering path is less than a month old and does not reach Chromium parity. The v0.2.0 notes say so plainly: long-tail CSS, some web APIs, native media playback and GPU compositor effects may still differ. My test confirmed it on the first try. The PDF output is also raster-backed, so the text cannot be selected.

Conformance is not complete either. The benchmark repository publishes an 83.3% subtest pass rate on the Core tier of the Web Platform Tests (318,916 of 382,891) and 60.0% on the full suite. That 60% is not a hidden defect, it is the consequence of deliberately not implementing whole layers of the platform, and the project documents it.

The README figures age. It advertises a 70 MB binary, but the ARM64 build with rendering that I downloaded takes 100 MB unpacked, plus another 92 MB for the worker process. The Docker image went from 53.2 MB in 0.1.11 to 87.1 MB in 0.2.1. None of this is serious, but measure on your own platform before quoting the table.

The project is young and highly concentrated. It was created on 13 April 2026 and, of the twenty contributors the GitHub API lists, a single one accounts for 733 commits. Stealth mode reduces automation signals, but it does not prevent blocks based on IP reputation or behaviour patterns. And Obscura Cloud, the managed version, is still a waiting list rather than a product you can buy.

When it is worth it and when it is not

It is worth it when your bill is a memory bill. If you run hundreds or thousands of concurrent sessions extracting data, going from 500 MB to 38 MB per session changes machine sizing in a way no code optimisation can match. It is also worth it when you want to package a browser inside a small image with no Node.js and no Chrome, or when you need genuinely clean, reproducible sessions.

It is not worth it if your workload is a few dozen pages and already works. The per-page latency gain on real sites is zero or negative, and you would be swapping a mature engine for a five-month-old one. It is also not worth it if you depend on visual fidelity: visual regression testing, client-facing captures, anything where the pixel matters, all of that remains Chromium territory. And if your problem is getting blocked, the engine is not the lever; proxies and request pacing are.

My practical advice: run it alongside. Start obscura serve next to your current headless Chrome, point a percentage of traffic at it with connectOverCDP and compare results on your own target pages for a week. Migration costs one environment variable, so the experiment is cheap. If you are curious about the language underneath, Rust for backend work with Axum and Tokio has the context for why this class of project gets written that way.

Frequently asked questions

Does Obscura replace Playwright or Puppeteer?

No, it complements them. Playwright and Puppeteer are the libraries you write the automation script in; Obscura is the browser that script drives. You keep the same Playwright code and only change the connection target, from a Chromium launched by the library to an obscura serve listening over CDP.

Can I use Obscura in a closed commercial product?

Yes. The licence is Apache-2.0, which permits commercial use and integration into proprietary software with no obligation to publish your code. That is the most practical difference against Lightpanda, which uses AGPL-3.0 and requires releasing the source of any networked service that embeds it.

Is Obscura good enough for reliable screenshots?

Only with caution. Since v0.2.0 it does screenshots, screencasting and PDF without Chromium, and they work. But the paint engine is new and the project itself warns that it does not match Chromium: in my test it ignored an opacity rule on a pseudo-element and rendered the header wrong. For visual regression testing, stay on Chromium.

Conclusion

Obscura solves a specific problem and solves it well: the memory cost of giving every agent its own browser. Thirteen times less RAM per session is a figure that changes architecture decisions, and CDP compatibility makes trying it almost free. What you should not expect is the speed gain the home page advertises, because it does not appear on real pages. Nor rendering fidelity equal to Chromium, because the project itself warns that it is not there yet.

That Cloudflare started from this code to build Kitesurf says a good deal about the quality of the idea. Five months of life says a good deal about the risk. Measure it against your own pages before moving anything.

Sources: [1] Obscura, official GitHub repository, [2] Obscura, published release notes, [3] obscura-benchmark, measured conformance and performance, [4] Official Obscura documentation, [5] Cloudflare, introducing Kitesurf, [6] Official Obscura image on Docker Hub, [7] Official Obscura website, [8] wpt.fyi, Web Platform Test results by engine.

Spanish version: Qué es Obscura, el navegador headless en Rust para agentes de IA.

Originally published on jacar.es.

How to install and tune oMLX on M5 Max 128 GB

Javier Cañete Arroyo — Tue, 13 Oct 2026 18:35:56 +0000

oMLX is an LLM inference server built on MLX, the framework Apple shipped in December 2023 for Apple Silicon. It adds continuous batching, two-tier KV cache (RAM + SSD), and an OpenAI- and Anthropic-compatible API.

On a Mac M5 Max with 128 GB of unified memory you can hold three or four large models at once with TurboQuant 3.5-bit on KV cache. That is enough to feed chat, agent and IDE in parallel. This guide collects the configuration tested in May 2026 to get the most out of that combination.

Quick answers

Which oMLX version do I use and how do I install it? Version 0.6.4 (released 29 August 2026, Apache 2.0). The direct route: download the .dmg from GitHub Releases, open it and drag to Applications. Or install via brew tap jundot/omlx https://github.com/jundot/omlx and brew install jundot/omlx/omlx.

The first load of the panel at http://localhost:8000/admin prompts for the API key. The full Homebrew route, including the service that starts on its own, is in installing, updating and uninstalling oMLX with Homebrew.

What TurboQuant setting makes sense on 128 GB? 3.5-bit. vLLM’s independent analysis published 11 May 2026 shows 3.5-bit matches full-precision quality with about 4x less KV-cache memory. On M5 Max that turns 128k context from "blows past available RAM" into "fits alongside other loaded models."

How much faster is it with the advanced 0.6.4 settings? Between 1.19x and 1.88x when generating code, and between 1.07x and 1.47x with 15,000 tokens of context, measured through the API on 15 September 2026. The biggest gain came from Lightning MTP on Qwen3.8-27B oQ4e, from 21.1 to 39.7 tok/s, and it needs a build of the model that keeps the MTP head. The details are in the advanced settings.

Which models can I load concurrently on 128 GB?

Primary: unsloth/Qwen3.6-35B-A3B-MLX-8bit (37.7 GB, MoE with 3B active). Fast helper: Qwen3-14B-Instruct-mlx-4bit (8 GB). Vision: Qwen2.5-VL-32B-mlx-4bit (18 GB).

Embeddings: BGE-M3-mlx (1.2 GB). Reranker: ModernBERT-base-mlx (150 MB). Comfortable sum: ~65 GB with headroom.

How do I point Claude Code at the local endpoint? Since 0.5.0 the short way is omlx launch claude, which exports the variables for you. By hand: export ANTHROPIC_BASE_URL=http://127.0.0.1:8000, ANTHROPIC_AUTH_TOKEN=<your_api_key> and the three ANTHROPIC_DEFAULT_*_MODEL variables (Opus/Sonnet/Haiku).

Launch with claude --bare to drop the system prompt to ~1,795 tokens. The dashboard’s Claude Code with oMLX section assembles the full command for you.

Does this replace Claude Opus 4.7? Not one for one. Claude Code is tuned for Claude’s tool-use format; a non-Claude model behind the endpoint loses reliability in agentic loops. Use this for offline work, sensitive data that should not leave the Mac, or as a fallback when api.anthropic.com is rate-limiting you.

Install

The easiest path: download the .dmg from GitHub Releases, open it and drag the app to Applications. The server starts in the background with a menu-bar icon.

Or install via Homebrew:

brew tap jundot/omlx https://github.com/jundot/omlx
brew install jundot/omlx/omlx
omlx start
omlx serve --model-dir ~/models

The first hit to http://localhost:8000/admin prompts for the API key. By default oMLX ships with no API key set (empty field), which is fine for local testing. If the instance only listens on 127.0.0.1 this is safe; the moment you expose it to the LAN or plan to share the endpoint, go to Settings → Auth & Info and set a long random string. The section accepts multiple keys at once.

Server settings for 128 GB

Settings → Global Settings holds the full server configuration. The decisions that matter on a 128 GB machine:

Server → Host: Localhost only (127.0.0.1). If you open it to the LAN, put real auth in front first.
Server → Port: 8000 by default.
Resource Management → Memory Limit (Total): Auto. oMLX subtracts what macOS reserves; on 128 GB you end up around 110-114 GB for inference.
Resource Management → Memory Limit (Models Only): Auto. Keeps a percentage for activations, KV cache and auxiliary processes.
Resource Management → Hot Cache Limit: 10%. Intermediate RAM-tier KV cache. With TurboQuant enabled on the models that support it (see below), 10% is the value people running this setup in practice land on for 128 GB. With TurboQuant off and a single model loaded you can drop to Off, but you stop gaining.
Resource Management → Cold Cache Limit (SSD Cache): 10%. Around 80 GB of SSD for cold tokens without saturating it.
Resource Management → Max Concurrent Requests: 16. Comfortable for a single user with an agent, a chat session and an IDE pinging at once. Raise to 32 if you share with a small team.
Resource Management → Idle Timeout: None. Keeps models warm; the first token arrives in well under a second instead of seconds later.
Generation Defaults → Max Context Window: 256000 as the global default. The Qwen3.6 family holds up at long context, and with TurboQuant the effective RAM stretches enough to actually use it. Each model can be capped lower in Model Settings.
Generation Defaults → Max Tokens: 64000. Upper bound per response. Going higher only matters if you plan to generate full books in one shot.
Generation Defaults → Temperature: 1.0 for general use, 0.2-0.5 for code models.
Model Settings → Experimental Features → TurboQuant KV Cache: enable at 3.5-bit on the large dense models. vLLM’s independent study published 11 May 2026 of Google’s TurboQuant shows 3.5-bit matches full-precision quality with roughly 4x less KV-cache memory. On M5 Max that makes 128k context fit on models where FP16 does not. On 0.6.4 it cannot be combined with VLM MTP, and in these tests it did not speed up generation; if speed is what you are after, see the advanced settings.

Model stack for multi-LLM

With 128 GB you have room to load one large primary model, a fast helper, a VLM, embeddings and a reranker concurrently. Download them from Models → Downloader by pasting the Hugging Face repo URL.

The recommendation holding up in May 2026 comes from people actually running Claude Code on oMLX on M5 Max (see Diego R. Baquero’s gist for the source): Unsloth’s Qwen 3.6 35B-A3B family in MoE with ~3B active parameters per token. On 128 GB the 8-bit fits without breaking a sweat:

Primary (chat + code + reasoning): unsloth/Qwen3.6-35B-A3B-MLX-8bit (~37.7 GB). MoE 35B with 3B active. The all-rounder: long chat, code, agents. On 128 GB it fits alongside everything else without squeezing.
More compressed alternative: unsloth/Qwen3.6-35B-A3B-UD-MLX-4bit (~21.6 GB) if you want two primary models loaded at once. Loses a notch of quality versus 8-bit but leaves room to experiment.
Dense reasoning (when MoE falls short): Mistral-Large-2-123B-Instruct-mlx-4bit (~70 GB) or Llama-3.3-70B-Instruct-mlx-4bit (~40 GB). For deep reasoning in a single pass, where a dense architecture beats a small-activation MoE.
Fast helper: Qwen3-14B-Instruct-mlx-4bit (~8 GB). For cheap tasks in agents, parsing and summaries.
Vision: Qwen2.5-VL-32B-Instruct-mlx-4bit (~18 GB) covers OCR, image description and multimodal reasoning.
Embeddings: BGE-M3-mlx (~1.2 GB), dense + sparse + multi-vector in a single model.
Reranker: ModernBERT-base-mlx (~150 MB) to close the loop on a decent RAG pipeline.

Comfortable concurrent load with Qwen3.6 35B-A3B 8-bit as primary + 14B helper + VL-32B + embeddings + reranker: around 65-70 GB. Add Mistral Large 2 123B on top for dense reasoning and you hit ~135 GB nominal. The LRU policy moves idle models to SSD, so the cohabitation works in practice for sessions that do not pin everything at once. Pin the primary model from Model Manager so it never gets evicted.

Point Claude Code at the local endpoint

oMLX exposes an Anthropic-compatible API at http://127.0.0.1:8000. In current versions the routes live under /v1: POST /v1/messages and POST /v1/messages/count_tokens. Claude Code respects ANTHROPIC_BASE_URL, so pointing the CLI at your Mac is a matter of exporting environment variables. First, turn off the attribution header in Claude Code’s global config so the gateway does not bolt extra noise onto the prompt:

Since 0.5.0 there is a shortcut that does all of this for you and did not exist when this recipe was written:

omlx launch claude

It sets ANTHROPIC_BASE_URL against your server, puts the configured key in ANTHROPIC_AUTH_TOKEN (or omlx if there is none), empties ANTHROPIC_API_KEY to force the base URL to be used, raises API_TIMEOUT_MS to 3,000,000 and disables non-essential traffic. It also sets CLAUDE_CODE_MAX_CONTEXT_TOKENS and CLAUDE_CODE_AUTO_COMPACT_WINDOW to what the engine can actually do, which is what the context-scaling option used to do by hand. It enforces a minimum window of 48,000 tokens and will not start if the chosen model falls short. There are equivalent commands for Codex, OpenCode, OpenClaw, Hermes and Pi, described in the dashboard and command line guide.

The manual recipe below still works and is the one to use if you want fine control over each variable.

~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Then the startup command:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8000
export ANTHROPIC_AUTH_TOKEN=<your_api_key>
export ANTHROPIC_DEFAULT_OPUS_MODEL=unsloth/Qwen3.6-35B-A3B-MLX-8bit
export ANTHROPIC_DEFAULT_SONNET_MODEL=unsloth/Qwen3.6-35B-A3B-MLX-8bit
export ANTHROPIC_DEFAULT_HAIKU_MODEL=Qwen3-14B-Instruct-mlx-4bit
export ANTHROPIC_DEFAULT_MODEL=unsloth/Qwen3.6-35B-A3B-MLX-8bit
export API_TIMEOUT_MS=600000
export CLAUDE_CODE_USE_BEDROCK=0
export DISABLE_NONESSENTIAL_TRAFFIC=1
claude --bare

The --bare flag skips hooks, LSP, plugin sync and auto-memory, dropping Claude Code’s system prompt to around 1,795 tokens (versus the thousands it uses with everything loaded). For offline work against a local model that is the sensible default: every token in the system prompt is bandwidth your Mac would otherwise burn. Drop the flag when you point back at api.anthropic.com.

The oMLX dashboard builds this command for you in the Claude Code with oMLX section: pick Opus, Sonnet and Haiku from three dropdowns and copy the ready-to-paste command. Set Context scaling for Claude Code to 64000: Claude Code requests 200k tokens by default, but a local model behaves better with a 64k ask than a 200k ask it cannot honor. The option scales the reported counts so auto-compact triggers at the target size.

A real caveat: Claude Code is tuned to Claude’s tool-use format and response patterns. A non-Claude model behind ANTHROPIC_BASE_URL works for autocomplete and reasoning, but you will see drops in tool-call reliability and in agentic loops. Use this for offline work, sensitive data that should not leave the Mac, or as a fallback when api.anthropic.com is rate-limiting you. It is not a 1:1 substitute for Claude Opus 4.7.

SSH from another Mac

If oMLX runs on a Mac Studio and you want to use Claude Code from your MacBook, SSH port forwarding is the bridge:

ssh -L 8000:localhost:8000 user@mac-studio

Once connected, 127.0.0.1:8000 on your laptop points to the Studio’s oMLX. Save this script as claude-local.sh:

#!/bin/bash
export ANTHROPIC_BASE_URL='http://localhost:8000'
export ANTHROPIC_AUTH_TOKEN=''
export ANTHROPIC_DEFAULT_OPUS_MODEL='Qwen3.6-35B-A3B-MLX-8bit'
export ANTHROPIC_DEFAULT_SONNET_MODEL='Qwen3.6-35B-A3B-MLX-8bit'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='Qwen3-14B-MLX-4bit'
export ANTHROPIC_DEFAULT_MODEL='Qwen3.6-35B-A3B-MLX-8bit'
export API_TIMEOUT_MS=600000
export CLAUDE_CODE_USE_BEDROCK=0
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude --bare --dangerously-skip-permissions

Make it executable with chmod +x claude-local.sh and run it from the SSH session. The default API key is the empty field. If you set one in Settings → Auth & Info, replace '' with it.

--bare drops Claude Code’s system prompt to ~1,795 tokens. --dangerously-skip-permissions bypasses interactive permission prompts that don’t make sense in an automated pipeline.

Benchmark on real hardware

Bench → Performance runs tests on your actual hardware. The panel covers prefill at eight prompt sizes (pp1024, pp4096, pp8192, pp16384, pp32768, pp65536, pp131072, pp200000) and continuous batching at 2x, 4x and 8x concurrency. Results go to the public oMLX leaderboard, and My Submissions shows yours next to other machines on the same profile. On 0.6.4 the upload happens automatically when each run finishes; how to avoid it is in the 0.6.4 benchmarks.

Reference numbers measured on M5 Max 40-core with 128 GB on oMLX 0.3.8, in May 2026. Not extrapolated (the omlx.ai leaderboard already has M5 Max submissions, and vLLM’s independent TurboQuant study published 11 May 2026 confirms the figures for the large dense models):

Qwen 3.6 35B-A3B 8-bit (MoE, 3B active): 65-80 tok/s on decode at short context. The model that most changes day-to-day use on this machine. Live benchmarks from this setup:

Test	TTFT	Decode TPS	E2E	Peak Mem
pp1024/tg128	577 ms	72.4 tok/s	2.35s	38.5 GB
pp4096/tg128	1,293 ms	83.1 tok/s	2.83s	36.2 GB
pp8192/tg128	2,995 ms	82.1 tok/s	4.55s	36.5 GB
pp32768/tg128	13,785 ms	15.2 tok/s	22.18s	40.9 GB

Continuous batching (pp1024 / tg128):

Batch	Decode TPS	Speedup
1x (baseline)	72.4 tok/s	1.00x
2x	87.1 tok/s	1.20x
4x	123.8 tok/s	1.71x
8x	237.7 tok/s	3.28x

Llama 3.3 70B 4-bit: 14-18 tok/s on decode.
Mistral Large 2 123B 4-bit with TurboQuant 3.5-bit on KV cache: 8-11 tok/s on decode. The number that matters at 128k context is peak memory, ~74 GB (FP16 KV blows past 128 GB). dasroot.net’s long-context M5 Max experiment documents the same peaks for the 104B dense model.
gpt-oss-20b MXFP4-Q4 on M5 Max 40c per the public oMLX benchmark submission lands around 100 tok/s on decode.

The tables above are our own measurement on 0.3.8, and on 15 September 2026 I re-ran the tests on 0.6.4 on this same machine. With no acceleration at all, this model goes from 15.2 to 77.9 tok/s with a 32k prompt. Speculative decoding adds between 1.07x and 1.88x, depending on the model and the context. The new tables are in the 0.6.4 benchmarks.

vLLM measured the TurboQuant KV-cache compression at 4.41x in May 2026. That figure is what separates "I have 128k context but it does not fit" from "I have it and can load two other models alongside it". At 4-bit and 3.5-bit, quality stays close to full precision; at 3-bit you start to feel it in code and long-form reasoning.

Advanced settings for maximum performance on 0.6.4

On 0.6.4, the biggest speed lever on this M5 Max is speculative decoding, and the right method depends on the model. Measured through the API at temperature 0.6, Qwen3.8-27B oQ4e went from 21.1 to 39.7 tok/s with Lightning MTP. Qwen3.6-35B-A3B 8-bit went from 79.7 to 117.5 tok/s with VLM MTP. Everything in this section was measured on 15 September 2026 on the machine this guide is about, and the method and the full tables are in the 0.6.4 benchmarks section.

Which acceleration method to use with each model

oMLX 0.6.4 has three speculative decoding methods and allows only one per model:

Lightning MTP: uses the multi-token prediction (MTP) head that ships inside the weights. It only works if the conversion kept the mtp.* tensors.
VLM MTP: uses an external MTP drafter under 2 GB, trained for that base model. It only kicks in when no other request is running.
DFlash: uses a z-lab block-diffusion drafter that proposes up to 16 tokens per pass. It serves requests one at a time and keeps its own prefix cache.

In all three the large model verifies every proposed token, so the output comes from the large model, not from the drafter. This is what each combination measured on this M5 Max:

Model	Method	What to download	Size	Decode writing code	Decode with 15,000 tokens of context
Qwen3.6-35B-A3B 8-bit	VLM MTP	`mlx-community/Qwen3.6-35B-A3B-MTP-bf16`	1.7 GB	79.7 → 117.5 tok/s	84.0 → 90.7 tok/s
Qwen3.6-35B-A3B oQ4e	Lightning MTP	`Jundot/Qwen3.6-35B-A3B-oQ4e-mtp` (full model)	21.6 GB	100.2 → 119.2 tok/s	100.2 → 115.5 tok/s
Qwen3.8-27B oQ4e	Lightning MTP	`Jundot/Qwen3.8-27B-oQ4e-mtp` (full model)	17.0 GB	21.1 → 39.7 tok/s	21.4 → 27.2 tok/s
Qwen3.8-27B 4-bit	VLM MTP	`mlx-community/Qwen3.8-27B-MTP-bf16`	0.87 GB	24.1 → 34.5 tok/s	21.7 → 23.2 tok/s
Gemma 4 12B 8-bit	VLM MTP	`mlx-community/gemma-4-12B-it-assistant-bf16`	0.88 GB	27.4 → 50.5 tok/s	26.6 → 39.2 tok/s
gpt-oss-20b	None	–	–	–	–

For Qwen3.6-35B-A3B, the oQ4e build with Lightning MTP was the fastest in both tests and takes about 15 GB less than the 8-bit one. With long context and prose answers every gain shrinks, because the large model accepts fewer draft tokens, but no configuration was slower than its baseline.

If a Qwen model’s settings show the warning Config declares MTP layers but the weight files contain neither mtp.* tensors nor native nextn layers, the conversion stripped the MTP head. The default mlx-lm converters do that: it applied to the Qwen3.6-35B-A3B builds from mlx-community and the Qwen3.8-27B builds from lmstudio-community installed on this Mac. You have two ways out: download a build that keeps the head, such as the oQ4e-mtp builds published by the oMLX author, or turn on VLM MTP with an external drafter.

Downloading the drafters

Drafters download like any other model. In Models → Downloader, paste the Hugging Face repository id and start the download. oMLX recognises drafters by their type and marks them as helpers; with Hide Helper Models on, they also stay out of the API’s model list.

Turning on Lightning MTP

With a model that keeps its MTP head, open Settings → Model Settings, click the model’s gear icon and turn on Lightning MTP in the Acceleration block. When you save, oMLX reloads the model.

On Qwen the default is 3 draft tokens per cycle, and an adaptive controller adjusts it from each response’s acceptance rate. The oMLX log writes one line per response with that rate: on Qwen3.6-35B-A3B oQ4e it sat around 72-77%, with 2.5 to 2.9 tokens emitted per cycle. With greedy sampling the output matches the model without MTP, apart from tiny numerical differences. With temperature, rejection sampling keeps the large model’s distribution.

Turning on VLM MTP with an external drafter

In the same Acceleration block, turn on VLM MTP, pick the drafter from the drop-down and save. Three conditions in the 0.6.4 code are worth knowing first:

The model has to load on the vision engine. The multimodal Qwen3.6 and Qwen3.8 builds do so by default, but on a text-only model the setting is silently ignored.
It cannot be combined with TurboQuant or with repetition or presence penalties. The built-in Qwen presets set presence_penalty to 1.5, which turns it off.
It only speeds up a request when nothing else is running. With concurrent requests, oMLX falls back to normal batching.

You can apply the same change through the admin API, which is handier when you configure more than one model or script it. The first command logs in with your key and stores the cookie; the second updates the model’s settings:

curl -c omlx.cookies -X POST http://127.0.0.1:8000/admin/api/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key_here"}'

curl -b omlx.cookies -X PUT \
  http://127.0.0.1:8000/admin/api/models/Qwen3.6-35B-A3B-8bit/settings \
  -H "Content-Type: application/json" \
  -d '{"vlm_mtp_enabled": true,
       "vlm_mtp_draft_model": "Qwen3.6-35B-A3B-MTP-bf16"}'

The model name in the path and the drafter name are the ids shown in the model list. For Lightning MTP the body is {"mtp_enabled": true}. The endpoint rejects any field it does not know, so a typo does not slip through.

DFlash only pays off with short prompts

DFlash was the fastest method with 1,000-token prompts and the worst with long context. In the built-in benchmark, Qwen3.6-35B-A3B 8-bit rose from 92 to 112 tok/s with a 1k prompt, but dropped from 78 to 17 tok/s with 32k. Qwen3.8-27B 4-bit dropped from 23.5 to 6.3 tok/s with 32k. If you use Claude Code, which sends tens of thousands of tokens of context every turn, leave it off.

For short-prompt work such as chat or autocomplete, download the matching z-lab drafter: z-lab/Qwen3.6-35B-A3B-DFlash (0.77 GB), z-lab/Qwen3.8-27B-DFlash2 (3.85 GB) or z-lab/gemma4-12B-it-DFlash (1.46 GB). Turn it on in Acceleration → DFlash and quantise the drafter to 4 bits. On the 27B, the 4-bit drafter gave 48.2 tok/s with a 1k prompt against 36.9 tok/s in bf16, and used 2.5 GiB less.

It has two more limits. It serves one request at a time. And although dflash_max_ctx sends long requests to the normal engine, after the first one DFlash stays off until you reload the model.

Prefill on the Neural Engine: no gain with Lightning MTP

Qwen ANE Prompt Processing splits part of the Qwen3.5, 3.6 and 3.8 prefill between Apple’s Neural Engine (ANE) and the GPU. The Tune for this Mac button measures the best split on your machine and saves nothing until you apply the result. On Qwen3.8-27B oQ4e it recommended sending 35% of the MLP channels and 37.5% of the GDN layers to the ANE. With that split, prefill on an 8,193-token prompt went from 452 to 510 tok/s, 12.8% more.

That 12.8% did not hold with the full model. With the split applied and Lightning MTP on, the built-in benchmark measured 505 tok/s of prefill with a 4k prompt against 499 without the ANE, and 422 against 471 with 32k. Through the API, the first token with 15,100 tokens of context took 34.8 s, against 35.2 s without the ANE. In exchange the loaded model grew from 16.0 to 20.7 GB and loading went from 2 to 20 s, so on this Mac I left it off.

Before tuning it on an M5 Max, turn off Use both ANEs in the model settings. That mode is meant for the M3 Ultra, which joins two chips and has two ANEs. It only speeds up prompts of 2,048 tokens or more; generation stays on the GPU.

The project itself documents three costs. It is not bit-exact, because the ANE runs weights requantised to INT8. It relies on private Apple interfaces that a macOS update can break, and it lengthens model load. If you turn it on anyway, also turn on Reuse Compiled ANE Programs under Global Settings → Advanced so it does not recompile on every start.

The global settings that matter

oMLX’s default global configuration already suits a single user, and only four settings change anything measurable:

Kernel memory limit: macOS caps the memory the GPU can wire by default, and the dashboard shows a red warning when that cap is below what oMLX could use. Run sudo sysctl iogpu.wired_limit_mb=124518, which on 128 GB is RAM minus 5%, and restart oMLX, which applies it at start-up. The value is lost when the Mac restarts.
Prefill Priority: set it to Speed. When memory is tight, Max Context shrinks prefill down to 32 tokens per step so the prompt fits, while Speed keeps full speed and rejects what does not fit.
Hide Helper Models: turn it on so drafters stay out of /v1/models and no client picks one by mistake.
Max Concurrent Requests: keep it between 8 and 16, and do not lower it to 1. The scheduler admits no new request while as many cache writes are pending as that limit.

Burst Decode can stay on Balanced. Aggressive holds tokens for up to 200 ms before sending them, against 100 ms, so the client sees the first token later. One last warning: clicking Save Settings unloads every loaded model, even if you did not touch the cache, because the dashboard resends every field.

What does not make it faster

Three settings with promising names did not improve single-user speed:

TurboQuant KV: with Lightning MTP on Qwen3.8-27B oQ4e, turning it on at 4 bits left peak memory unchanged with a 32k prompt (24.4 GiB) and lowered decode from 35.4 to 30.3 tok/s. In these hybrid models only the full-attention layers keep a KV cache, so there is little to compress. It saves memory on huge contexts; it does not make generation faster.
SpecPrefill: brings the first token forward by having a small model drop the prompt tokens it scores as unimportant. The large model never sees them, so it loses information by design.
Chunked Prefill: it only cuts time to first token when requests overlap.

Benchmarks on 0.6.4 on this M5 Max

With 0.6.4 and the settings above, this M5 Max generates between 1.19 and 1.88 times more tokens per second when writing code. With 15,000 tokens of context, the gain sits between 1.07 and 1.47 times. Without any acceleration, Qwen3.6-35B-A3B 8-bit now holds 77.9 tok/s with a 32k prompt, where 0.3.8 dropped to 15.2 tok/s. The tests date from 15 September 2026.

How it was measured

There are two test sets, because the built-in benchmark shows how speed changes with context but cannot compare with and without acceleration:

Through the API: streaming requests to /v1/chat/completions at temperature 0.6 with reasoning off. There are two tests. In the short one, each configuration answers three coding tasks (Python, TypeScript and Go) twice, with 768-token answers. In the long one, it answers two questions about roughly 15,100 tokens of source code, with 512-token answers. Timing is taken on the client.
Built-in benchmark: started from POST /admin/api/bench/start, three repeats per configuration and the median, prompts of 1,025, 4,097, 16,385 and 32,769 tokens, 256 generated tokens and the code_python corpus. It always samples greedily, which is the best case for speculative decoding.

Every request starts with a unique prefix, so none of them benefits from the prefix cache. Tables show the median, with the minimum and maximum in brackets when they spread more than 10% from the median in the API tests, or more than 25% in the built-in benchmark.

The tests ran back to back for about three hours, with other applications open. The built-in benchmark records macOS thermal pressure, and 194 of its 242 measurements were taken at the Heavy level, the third of five (Nominal, Moderate, Heavy, Trapping and Sleeping). Only the first gpt-oss batch ran cold. Its prefill with a 16k prompt gave 3,140 tok/s cold and 1,755 tok/s hot.

Read the absolute figures as those of a hot Mac. The comparisons with and without each setting were run one after the other, so the relative gains are more reliable than the absolute values.

Two details of the 0.6.4 built-in benchmark change how to read it. First, when it finishes it uploads the results to omlx.ai with the chip, the models and an identifier derived from the Mac, and the dashboard has no option to prevent it. With a local model, the only way to keep the results on the Mac is to tick ANE-aligned prompts (+1 token). That is the checkbox I used, which is why the prompts are one token longer.

Second, it loads vision models on the text-only engine unless MTP is on, so comparing with and without acceleration mixes two engines. With short prompts, Qwen3.6-35B-A3B oQ4e scored 49 tok/s on that engine and 100 tok/s through the API. That is why the gains in this guide come from the API tests.

Speed through the API with coding answers

Model	Configuration	Decode	First token	768-token answer
Qwen3.6-35B-A3B 8-bit	No acceleration	79.7 tok/s	0.37 s	10.0 s
	VLM MTP	117.5 (110.5-125.5) tok/s	0.37 s	6.9 s
Qwen3.6-35B-A3B oQ4e-mtp	No acceleration	100.2 tok/s	0.34 s	8.0 s
	Lightning MTP	119.2 (108.5-139.1) tok/s	0.46 s	6.9 s
Qwen3.8-27B 4-bit	No acceleration	24.1 tok/s	0.79 s	32.6 s
	VLM MTP	34.5 tok/s	0.65 s	22.8 s
Qwen3.8-27B oQ4e-mtp	No acceleration	21.1 tok/s	0.82 s	37.3 s
	Lightning MTP	39.7 tok/s	0.94 s	20.4 s
Gemma 4 12B 8-bit	No acceleration	27.4 tok/s	0.84 s	28.9 s
	VLM MTP	50.5 (47.5-52.7) tok/s	0.66 s	15.9 s

Speed through the API with 15,000 tokens of context

Model	Configuration	Decode	First token
Qwen3.6-35B-A3B 8-bit	No acceleration	84.0 tok/s	6.20 s
	VLM MTP	90.7 tok/s	5.96 s
Qwen3.6-35B-A3B oQ4e-mtp	No acceleration	100.2 tok/s	5.83 s
	Lightning MTP	115.5 tok/s	6.14 s
Qwen3.8-27B 4-bit	No acceleration	21.7 tok/s	34.5 s
	VLM MTP	23.2 tok/s	32.6 s
Qwen3.8-27B oQ4e-mtp	No acceleration	21.4 tok/s	31.3 s
	Lightning MTP	27.2 (24.4-30.1) tok/s	35.2 s
Gemma 4 12B 8-bit	No acceleration	26.6 tok/s	20.1 s
	VLM MTP	39.2 tok/s	19.3 s

Each row is the median of two 512-token answers over the same code context. With this context the large model accepted fewer draft tokens than when writing code: on Qwen3.8-27B 4-bit, the VLM MTP gain fell from 1.43x to 1.07x.

Built-in benchmark by prompt length

Generation speed in tok/s by prompt length, with prefill at 4k and MLX peak memory, which includes the weights:

Model and configuration	1k	4k	16k	32k	Prefill 4k	Peak
Qwen3.6-35B-A3B 8-bit, no acceleration	92.1	91.1	84.1	77.9	2,426	38.7 GiB
Qwen3.6-35B-A3B 8-bit, VLM MTP	118.3	106.6	100.2	94.4	3,113	41.8 GiB
Qwen3.6-35B-A3B 8-bit, DFlash (4-bit drafter)	112.4	110.5	32.6 (23.3-35.0)	16.6	2,734	38.2 GiB
Qwen3.6-35B-A3B oQ4e-mtp, no acceleration	49.3	46.1	45.2	42.2	2,258	23.2 GiB
Qwen3.6-35B-A3B oQ4e-mtp, Lightning MTP	77.2 (47.0-101.7)	85.8	87.9 (85.7-116.6)	82.8 (54.7-99.5)	2,014	24.6 GiB
Qwen3.6-35B-A3B oQ4e-mtp, DFlash (4-bit drafter)	142.7	86.3	39.2	17.3	3,373	22.7 GiB
Qwen3.8-27B 4-bit, no acceleration	30.6	27.3	25.0	23.5	525	21.7 GiB
Qwen3.8-27B 4-bit, VLM MTP	39.3	36.6	36.4	30.9	619	25.4 GiB
Qwen3.8-27B 4-bit, DFlash2 (4-bit drafter)	48.2 (38.7-51.1)	43.7	35.8 (22.0-39.0)	6.3	561	22.8 GiB
Qwen3.8-27B 4-bit, DFlash2 (bf16 drafter)	36.9	35.1	22.3	5.9	568	25.3 GiB
Qwen3.8-27B oQ4e-mtp, no acceleration	27.0	26.4	24.4	21.4	545	22.2 GiB
Qwen3.8-27B oQ4e-mtp, Lightning MTP	48.0 (42.6-58.6)	37.7	41.1	35.4	499	24.4 GiB
Qwen3.8-27B oQ4e-mtp, Lightning MTP + TurboQuant 4-bit	42.2	37.7	39.7	30.3	547	24.4 GiB
Qwen3.8-27B oQ4e-mtp, Lightning MTP + ANE prefill	35.6	33.1	35.8	30.9	505	28.3 GiB
Qwen3.8-27B oQ4e-mtp, DFlash2 (4-bit drafter)	41.4	33.8	18.8 (16.6-21.9)	5.8	458	23.3 GiB
Gemma 4 12B 8-bit, no acceleration	31.0	30.5	30.1	28.8	955	14.5 GiB
Gemma 4 12B 8-bit, VLM MTP	65.6	42.7	50.6	49.0	940	15.5 GiB
Gemma 4 12B 8-bit, DFlash (4-bit drafter)	92.4 (35.5-158.0)	34.4	53.4	51.2	997	18.1 GiB
gpt-oss-20b, no acceleration	120.2	106.5	100.4	78.8	3,491	12.4 GiB

DFlash figures with a 1k prompt varied widely between repeats: on Gemma 4 12B they were 35.5, 92.4 and 158.0 tok/s. Speed depends on how many draft tokens the large model accepts, and that changes with the text it has to continue.

Compared with 0.3.8

The May table and this one are not fully comparable. That one was measured on the Qwen3.6-35B-A3B-MLX-8bit copy with 128 output tokens; this one, on the mlx-community copy with 256. Even so, the long-context improvement is too large to come from those differences:

Qwen3.6-35B-A3B 8-bit, built-in benchmark	0.3.8 (May)	0.6.4 (September)
Decode with a 1k prompt	72.4 tok/s	92.1 tok/s
Decode with a 4k prompt	83.1 tok/s	91.1 tok/s
Decode with a 32k prompt	15.2 tok/s	77.9 tok/s
First token with a 1k prompt	577 ms	298 ms

End-to-end verification

A curl call to the OpenAI-compatible API to confirm the server is alive and a model responds:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-Coder-30B-A3B-Instruct-mlx-8bit",
    "messages": [{"role": "user", "content": "Hello from oMLX"}]
  }'

And from Claude Code, once you have exported the variables from the previous section:

claude --print "Are you running locally?"

The reply should come back from local without touching api.anthropic.com. To confirm at the network level, open Activity Monitor → Network, filter by the claude process and check that the outbound connection is against 127.0.0.1:8000.

What has changed since 0.3.8

This guide was written against oMLX 0.3.8 in May 2026. The current version is 0.6.4, released on 29 August 2026, and more than a dozen releases in between touch exactly what is tuned here. What follows is the summary of what changed, with the figures attributed to whoever measured them.

Lightning MTP speculative decoding

This is the change that affects this configuration most. Version 0.5.0, from 10 July 2026, added native depth-k speculative decoding for Qwen3.6-27B, Qwen3.6-35B-A3B, DeepSeek-V4-Flash and GLM-5.2.

On an Apple M3 Ultra the project measured Qwen3.6-35B-A3B going from 89.6 to 140.4 tok/s, a 1.57x gain. Qwen3.6-27B went from 35.0 to 55.1 tok/s. On this M5 Max, measured through the API on 15 September 2026, Lightning MTP took Qwen3.8-27B oQ4e from 21.1 to 39.7 tok/s. How to turn it on, and when another method is the better choice, is in the advanced settings.

Custom kernels, with a note for M5

The same 0.5.0 added custom compute kernels for DeepSeek V4, Qwen3.5/3.6 and GLM-5.2, with prefill improvements measured on M3 Ultra. They are 45% on DeepSeek-V4-Flash (313.3 to 455.8 tok/s at 64k context), 33% on Qwen3.6-27B and 99% on GLM-5.2 at 32k. What matters for this machine is that dispatch is NAX-aware precisely to avoid regressions on the M5 series, so it is worth confirming the effect rather than assuming it.

oQ and oQe quantisation

oMLX no longer depends only on the weights you download: it brings its own quantisation scheme. Version 0.5.0 added oQe, an activation-importance calibration pass with expert-coverage tracking for MoE models. In the project’s measurements oQ4e improves average accuracy over oQ4 while staying in the same disk-size class. That is 83.88% against 82.83% on Qwen3.6-35B-A3B, and 73.09% against 70.01% on Qwen3.5-9B.

The neural engine and cold starts

The 0.6.3 branch worked on the prefill path over Apple’s neural engine. Two of the project’s figures matter day to day. Bank compilation memory dropped from 35.8 GB to 4.7 GB, and an optional persistent compile cache cuts fresh-process startup by 53% to 66%. Version 0.6.4 continued down that road and improved Qwen3.8-Flash-Next prompt processing by 33.5%, with 24.2% less total request time at 32k, again on M3 Ultra.

New endpoints

The OpenAI- and Anthropic-compatible pair has been joined by /v1/rerank for document reranking, /v1/responses for Codex compatibility and /v1/mcp/tools for Model Context Protocol. With an embedding model and a reranker loaded at once, a whole retrieval pipeline fits on the same server. The full breakdown is in the guide to the API, the key and the port.

Sub-key authentication

Where there used to be a list of equivalent keys, there are now three credentials with different powers. A main key opens the API and the panel; sub-keys only call the API and cannot log into the panel or change settings; panel session tokens are held in a signed cookie. If you are handing access to more than one application, hand out sub-keys.

The setting names

The memory configuration in the earlier section still holds as judgement, but the keys are named differently in ~/.omlx/settings.json. The memory ceiling is now memory_guard_tier, with four levels (safe, balanced, aggressive and custom), and the bespoke value goes in memory_guard_custom_ceiling_gb. By default the ceiling is system RAM minus 8 GB. The two cache tiers are hot_cache_max_size and ssd_cache_max_size, and the concurrency limit is max_concurrent_requests.

Watch one of them: hot_cache_max_size ships as "0", which disables the hot cache in RAM. I go through it in benchmarks and the memory ceiling.

Other pieces that did not exist

Profiles save named bundles of settings over a single model, exposed as model:profile and at no extra memory cost. Aliases rename a model as far as the API is concerned. And there is experimental distributed inference, splitting a model’s layers across more than one Mac over SSH according to each machine’s memory, accounting for whether the link is Thunderbolt or 10GbE. The first two are in the dashboard and command line guide.

Sources and further reading

Diego R. Baquero, "Running Claude Code with a local LLM": the tested configuration recipe this post’s settings are based on (TurboQuant 3.5-bit, 64k context, attribution off, Qwen 3.6 35B-A3B models).
A First Comprehensive Study of TurboQuant, vLLM blog, 11 May 2026: independent analysis confirming 3.5-bit matches full-precision quality.
omlx.ai/benchmarks: public leaderboard with real submissions from M5 Max and other machines.
Maxing Out M5 Max Context Windows: Memory Fragmentation and TurboQuant Benchmarks (dasroot.net, April 2026): the other detailed experiment on long-context M5 Max with TurboQuant.
Repositories: jundot/omlx, ml-explore/mlx, ml-explore/mlx-lm, huggingface.co/mlx-community, huggingface.co/unsloth.

If you came here wondering what this actually is and how it differs from Apple’s MLX framework, I separate the two in what is oMLX. For a cross-platform alternative outside Apple Silicon, the Ollama local LLM guide covers the model catalogue and OpenAI-compatible API. To wire the local endpoint into an agent, the Anthropic SDK tutorial and the MCP multi-vendor patterns already talk to this same format with no code changes.

Related resources

Frequently asked questions

Do I need to set an API key to use oMLX locally only?

No. oMLX ships with the API key field empty, and as long as the instance only listens on 127.0.0.1 that is safe for local testing. The moment you expose it to the LAN or share the endpoint, go to Settings → Auth & Info and set a long random string. Current versions also offer sub-keys that can only call the API and cannot log into the panel or change settings, meant for handing access to more than one application.

Can I use Claude Code from a MacBook against oMLX running on a Mac Studio?

Yes, through SSH port forwarding: ssh -L 8000:localhost:8000 user@mac-studio makes 127.0.0.1:8000 on the laptop point at the Studio's oMLX. Then export the same variables (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN and the ANTHROPIC_DEFAULT_*_MODEL set) in a script such as claude-local.sh, make it executable with chmod +x and run claude --bare from the SSH session. If you set a key in Settings → Auth & Info, replace the empty string with it.

Are the benchmarks in this post still valid if I install 0.6.4?

The May tables, no: they were measured on 0.3.8, and when I re-ran them on 15 September 2026, 0.6.4 was faster on this same machine. Without acceleration, Qwen3.6-35B-A3B 8-bit goes from 15.2 to 77.9 tok/s with a 32k prompt. Lightning MTP or VLM MTP add between 1.07x and 1.88x, depending on the model and the context. If you measure on your own Mac, compare through the API and not only with Bench → Performance, which runs vision models on a different engine when MTP is off.

Originally published on jacar.es, where the benchmarks are kept up to date with each oMLX release.