| --- |
| license: apache-2.0 |
| tags: |
| - on-device |
| - inference |
| - webassembly |
| --- |
| |
|  |
|
|
| # Cactus runtime |
|
|
| Prebuilt runtime binaries for [Needle 3](https://cactuscompute.com/needle), [Whistle](https://cactuscompute.com/blog/whistle) and [Mirage](https://huggingface.co/Cactus-Compute/mirage). |
| One engine runs text, speech and vision locally. Model weights live in their own repositories. |
|
|
| ## Get started |
|
|
| ```sh |
| pip install -U cactus-compute |
| ``` |
|
|
| Use `import cactus` in Python. The package downloads the matching engine and model weights on first use. |
| See the [Python API](https://cactuscompute.com/blog/needle-python-docs) and [source code](https://github.com/cactus-compute/cactus). |
|
|
| To download a native runner with a model, choose a platform from the table below. |
|
|
| ```sh |
| cactus download macos-arm64 --model whistle --out ./runtime |
| ./runtime/macos-arm64/cactus --model ./runtime/macos-arm64/whistle.cact --audio clip.wav |
| ``` |
|
|
| Use `--model needle3` or `--model mirage` for the other models. Omit `--model` to download binaries alone. |
|
|
| ## Supported platforms |
|
|
| Release **4.0.0** has 17 target folders under [`releases/4.0.0`](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0). |
| Native runners load `.cact` weights at runtime. Static libraries include `cactus.h` for C and C++ applications. |
|
|
| | Target | Folder | Files | |
| | --- | --- | --- | |
| | macOS Apple Silicon | [macos-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/macos-arm64) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Linux x86-64 | [linux-x86_64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/linux-x86_64) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Linux ARM64 | [linux-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/linux-arm64) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Linux ARMv7 | [linux-armv7](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/linux-armv7) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Linux RISC-V | [linux-riscv64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/linux-riscv64) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Linux MIPS32el | [linux-mipsel](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/linux-mipsel) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Windows x64 | [windows-x86_64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/windows-x86_64) | `cactus.exe`, `libcactus.a`, `cactus.h` | |
| | Windows ARM64 | [windows-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/windows-arm64) | `cactus.exe`, `libcactus.a`, `cactus.h` | |
| | Android ARM64 | [android-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/android-arm64) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Android ARMv7 | [android-armv7](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/android-armv7) | `cactus`, `libcactus.a`, `cactus.h` | |
| | Android RISC-V | [android-riscv64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/android-riscv64) | `cactus`, `libcactus.a`, `cactus.h` | |
| | iOS ARM64 | [ios-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/ios-arm64) | `libcactus.a`, `cactus.h` | |
| | iOS Simulator ARM64 | [ios-sim-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/ios-sim-arm64) | `libcactus.a`, `cactus.h` | |
| | tvOS ARM64 | [tvos-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/tvos-arm64) | `libcactus.a`, `cactus.h` | |
| | watchOS ARM64 | [watchos-arm64](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/watchos-arm64) | `libcactus.a`, `cactus.h` | |
| | Browser and Node.js | [wasm](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/wasm) | `cactus.js`, `cactus.wasm`, `cactus.h` | |
| | WASI Preview 2 | [wasm-component](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/wasm-component) | `cactus.component.wasm`, `cactus.wit` | |
|
|
| The [Python runtime wheels](https://huggingface.co/Cactus-Compute/cactus/tree/main/releases/4.0.0/python) cover macOS ARM64 and x86-64, Linux ARM64 and x86-64 with glibc or musl, and Windows ARM64 and x64. These contain the shared library. Install `cactus-compute` from PyPI to use them through the Python API. |
|
|
| The WASI component exports `cactus:runtime/engine@4.0.0`. It is also available as the signed OCI artifact `ghcr.io/cactus-compute/cactus-runtime-component:4.0.0`. |
|
|
| ## Weights and releases |
|
|
| - [Needle 3 weights](https://huggingface.co/Cactus-Compute/needle3) |
| - [Whistle weights](https://huggingface.co/Cactus-Compute/whistle) |
| - [Mirage weights](https://huggingface.co/Cactus-Compute/mirage) |
|
|
| Release artifacts have SHA-256 checksums in the [manifest](https://huggingface.co/Cactus-Compute/cactus/blob/1a028f5a3972b67dd8d8752f882113d475e7ec4c/releases/4.0.0/manifest.json). |
| For reproducible downloads, use revision `1a028f5a3972b67dd8d8752f882113d475e7ec4c` or tag `v4.0.0` and paths under `releases/4.0.0/`. |
|
|
| See the [deployment guide](https://cactuscompute.com/blog/needle-supported-devices) for native integration, browser use and offline setup. |
|
|
