Cactus Compute's Mirage is a local vision model for describing images and structured extraction, shipped inside the same cactus-compute package as Needle (tool-calling text) and Whistle (speech). The weights live on Hugging Face as Cactus-Compute/mirage and trended in early November 2026 with 207 likes on the platform counter.
If you already read our Whistle on-device speech post, Mirage is the vision leg of the same edge agent story: one pip install, multiple tiny specialists, no mandatory cloud round trip.
TL;DR #
| Question | Answer |
|---|---|
| Install | pip install -U cactus-compute |
| Minimal API | cactus.Mirage().describe("photo.png") |
| Weights | mirage.cact ,mirage.safetensors , config on HF |
| First run | Downloads and caches engine plus weights |
| Task type | Image understanding, structured extraction |
| HF pipeline tag | image-text-to-text per model page |
| Siblings | Needle agents, Whistle ASR, MLX CQ on Mac |
What the Hugging Face card actually says #
The Mirage model page is short and practical:
- Install
cactus-compute. - Import
cactusand call**Mirage().describe** on a local image path. - The package downloads and caches engine binaries and weights on first use.
- The repo hosts
mirage.cact,mirage.safetensors, and model config files.
There is no hosted Inference Provider button on the card when we fetched it — this is bring-your-own-runtime, consistent with Cactus's on-device positioning.
The GitHub README (Apache 2.0, 14k+ stars when checked) places Mirage under Vision:
import cactus
print(cactus.Mirage().describe("photo.png"))
That one-liner is the entire public API surface on the README. Deeper structured extraction behavior lives in Cactus docs linked from the card (Python API, runtime binaries, fine-tuning guides).
How Mirage fits the Cactus stack #
Cactus markets "sub-50mb agentic, voice and vision intelligence for consumer devices." The November 2026 README unifies older package names:
| Component | Role | Our prior coverage |
|---|---|---|
| Needle 3 | Tool calling, structured JSON, embeddings | Referenced inside Whistle post |
| Whistle | 16.9 MB ASR, seven languages | Dedicated explainx.ai post |
| Mirage | Describe and structured vision | This post |
| MLX CQ path | Large CQ checkpoints on Apple silicon | README cactus-mlx server mode |
Mirage is not trying to be a frontier multimodal chat model. It is a specialist head you call when an edge workflow needs "what is in this photo?" or "fill this schema from pixels" without shipping frames to a vendor API.
That design matches wider on-device agent trends — but Cactus chases megabyte-scale modules instead of billion-parameter laptop agents.
On-device vision pipeline describing a photo locally without cloud API round trip
MLX and vision on Mac #
The same README documents cactus-mlx for Nemotron-class CQ checkpoints on Apple silicon with optional --image photo.jpg on vision-capable models. That path is separate from Mirage's native engine today:
cactus.Mirage()uses the Cactus native runtime described on HF.cactus-mlxtargetsMLX with different model families and OS requirements (macOS 26+, Python 3.12 per README).
Do not assume Mirage weights run through MLX without checking the current docs — the README explicitly says Needle, Whistle, and Mirage continue to use their native engine while MLX is an additional lane.
When Mirage is worth trying #
Good fits
- Offline demos where Wi-Fi failure cannot break vision.
- Privacy-sensitive capture (factory floor, clinic lobby) where policy blocks cloud vision.
- Pipelines that already use Whistle for voice and Needle for tools — add Mirage as a third local call.
Weak fits
- Frontier caption quality competitions against multi-hundred-billion cloud models.
- Huge video streams without a chunking strategy — Mirage's public API example issingle-image describe .
- Teams that need guaranteed SLAs from a hosted API — there is no Inference Provider on the HF card.
Compare with Inferssd-style consumer hardware stacks only at the abstract "local inference" level. Mirage is orders of magnitude smaller and task-narrower.
Install and first-run checklist #
- Python 3.9+ per README (MLX extra needs3.12+ on Mac).
pip install -U cactus-compute- Prepare a local image path (PNG/JPG as supported by your build).
- Run
cactus.Mirage().describe(path)once on a networked machine tocache weights . - Optional: set
CACTUS_TELEMETRY=0to disable anonymous usage counts per README. - Read runtime platform support in Cactus docs before you bake Mirage into a mobile ship cycle.
For training-oriented teams, the README points to cactus-compute[train] for fine-tuning Needle or Whistle. Mirage fine-tune docs may evolve — confirm on cactuscompute.com before you plan a custom vision head.
Structured extraction vs plain captions #
The HF card headline calls Mirage "image understanding and structured extraction." The README demo prints describe, which reads like a captioning entry point.
For builders, the important question is whether describe returns free text only or can be steered toward JSON fields via prompts or follow-on APIs in the full Python reference. The public one-liner does not document JSON mode; treat structured output as docs-deep until you verify in the installed package version.
That honesty matters when you compare against cloud vision OCR pipelines like Baidu Unlimited-OCR — different problem sizes.
Document and image layout understanding concept for structured field extraction workflows
Hugging Face traction: what likes mean #
207 likes on HF (per candidate feed, November 2026) signal early community curiosity, not a production maturity certificate. Likes track bookmarking, not benchmark wins.
Mirage sits in a model tree linked to Automation Foundation Models For Tiny Devices on HF — useful metadata if you are mapping edge foundation model families.
Security and supply-chain notes #
- Weights download from Hugging Face on first use — pinrevision hashes in regulated environments.
- Apache 2.0 on the GitHub org is favorable, but verify checksums andSBOM policy the way you would for any auto-downloaded binary engine.
- Mirage does not replace content moderation for user uploads; local vision can stillleak sensitive scenes into logs if you print describe output carelessly.
For agent stacks combining Mirage with tools, see agent harness comparison guides — vision output feeding tools is still untrusted text.
Packaging, telemetry, and enterprise checklist #
The README states that pip install -U cactus-compute pulls engine binaries for supported platforms on first use. That means your CI image must allow download-on-first-run or you must pre-cache weights in the image layer.
Telemetry: CACTUS_TELEMETRY=0 disables anonymous Python usage counts. Security reviews should still ask what engine-level diagnostics exist, because local models can phone home through separate update channels if you add them later.
Enterprise checklist before pilot:
| Step | Why it matters |
|---|---|
| Pin HF revision hash | Reproducible builds across laptops |
| Document image retention | Describe output may land in logs |
| Test cold-start latency | First describe after boot is slowest |
| Compare with Needle+Whistle path | Multi-modal agent wiring |
| Legal review Apache 2.0 | Redistribution of bundled binaries |
Mirage is Apache-friendly at the repo level, but binary engines may carry additional platform licenses buried in docs — read the runtime section, not only the GitHub license file.
Voice-to-vision agent sketches #
A pattern that fits Cactus's marketing:
- Whistle transcribes a short voice note.
- Needle chooses a tool based on the transcript.
- Mirage describes a snapshot captured on device.
None of the public docs ship a single fused model for that chain. You orchestrate three calls. That is acceptable for prototypes but forces you to handle failure modes (empty transcript, blurry photo) in application code.
If you already deploy Hugging Face pybot swarm demos, Mirage is closer to a specialist tool than a chat personality.
What people are asking #
Is Mirage a general VLM? Public docs position it as a Cactus vision head, not an open clone of a frontier multimodal chat model.
Can I run it on Linux servers? Check runtime binaries in Cactus docs; the README lists multiple platform targets.
Does it beat GPT-4o vision? Unknown from primary sources we fetched — there is no public leaderboard on the card.
Relation to cactus-needle? README says migrate to import cactus; older Needle 2 stays on legacy branches.
Benchmarks Mirage does not ship #
Unlike Whistle, Mirage's HF card includes no WER-style table or public accuracy grid. You should assume unknown performance on:
- Dense document scans with tiny fonts
- Low-light security camera frames
- Non-Latin storefront signage unless docs add languages
Run a 20-image private set before you replace a cloud OCR or vision API. Measure latency p50/p95, describe length stability, and false negatives on safety-critical tags (PPE, spills, intrusion).
If you need deterministic JSON schema compliance, wrap Mirage output with a second validation model or rules engine rather than trusting free-form captions in compliance workflows.
For mobile teams, combine Mirage with tensorfold-style local inference experiments only at the planning layer — they solve different layers of the stack. Mirage answers what is in frame; Tensorfold-style work answers how tokens move on device.
Document whether your product stores describe output server-side. On-device inference does not automatically mean on-device privacy if your app syncs captions to a cloud profile.
When you file bug reports upstream, include platform, package version, and image dimensions. Vision engines fail in ways speech models do not, and reproducible fixtures help maintainers more than star counts on Hugging Face.
Related reading #
Mirage package names, star counts, and Hugging Face metadata are accurate as of November 13, 2026.