Installation

This guide covers installing Cactus on all supported platforms, including macOS, Linux, iOS, and Android.

System Requirements

macOS

OS: macOS 13.0+ (Ventura or later)
CPU: Apple Silicon (M1+) recommended, Intel supported
RAM: 2GB minimum, 4GB recommended
Disk: 500MB for Cactus + 200-500MB per model
Tools: Homebrew (for package install) or Xcode Command Line Tools (for source)

Linux

OS: Ubuntu 20.04+, Debian 11+, or compatible
CPU: ARM64 or x86_64 (ARM64 recommended for performance)
RAM: 2GB minimum, 4GB recommended
Disk: 500MB for Cactus + 200-500MB per model
Tools: python3.12, cmake, build-essential, libcurl4-openssl-dev

iOS

OS: iOS 14.0+
Device: iPhone 6s or later (A9 chip+)
RAM: 1GB+ available (depends on model size)
Development: Xcode 14.0+, Swift 5.7+

Android

OS: Android API 24+ (Android 7.0+)
Architecture: arm64-v8a (64-bit ARM)
RAM: 1GB+ available (depends on model size)
Development: Android Studio, Kotlin 1.9+

Cactus requires 64-bit ARM architecture for optimal performance. 32-bit ARM and x86 devices are not officially supported.

macOS Installation

Option 1: Homebrew (Recommended)

The fastest way to install on macOS:

brew install cactus-compute/cactus/cactus

Verify installation:

cactus --help

This installs:

Cactus CLI tool (cactus)
Pre-built libraries (libcactus.a)
Header files for C/C++ integration

Option 2: Source Build

For development or custom builds:

# Clone repository
git clone https://github.com/cactus-compute/cactus
cd cactus

# Run setup script
source ./setup

The setup script will:

Configure git hooks for DCO (Developer Certificate of Origin)
Create a Python 3.12 virtual environment in venv/
Install Python dependencies from python/requirements.txt
Install the cactus CLI tool in editable mode

The setup script must be sourced (not executed) to activate the virtual environment:

source ./setup  # correct
./setup         # incorrect

Verify installation:

cactus --help
which cactus  # should show ./venv/bin/cactus

Linux Installation

Install Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3.12 python3.12-venv python3-pip \
  cmake build-essential libcurl4-openssl-dev git

Raspberry Pi OS:

sudo apt-get update
sudo apt-get install python3.12 python3.12-venv python3-pip \
  cmake build-essential libcurl4-openssl-dev git

Python 3.12 is required. On older distributions, you may need to add a PPA:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.12 python3.12-venv

Build from Source

# Clone repository
git clone https://github.com/cactus-compute/cactus
cd cactus

# Run setup script
source ./setup

Verify installation:

cactus --help

Configure Git Identity (Optional)

If you plan to contribute, configure your git identity:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

iOS Installation

Step 1: Build XCFramework

From the Cactus source directory:

cactus build --apple

This generates:

apple/cactus-ios.xcframework/ - iOS framework (device + simulator)
apple/cactus-macos.xcframework/ - macOS framework
apple/libcactus-device.a - Static library for iOS device
apple/libcactus-simulator.a - Static library for iOS simulator

Step 2: Integrate into Xcode Project

Option A: XCFramework (Recommended)

Drag cactus-ios.xcframework into your Xcode project
In your app target settings, go to “General” → “Frameworks, Libraries, and Embedded Content”
Ensure cactus-ios.xcframework is set to “Embed & Sign”
Copy apple/Cactus.swift into your project

Option B: Static Library

Add libcactus-device.a to “Link Binary With Libraries” in Build Phases
Create a folder with cactus_ffi.h and module.modulemap
Add to Build Settings:
- “Header Search Paths” → path to header folder
- “Import Paths” (Swift) → path to module folder
Copy apple/Cactus.swift into your project

Step 3: Download Models

Models must be bundled with your app or downloaded at runtime:

# Download to project directory
cactus download google/gemma-3-270m-it

# Copy to Xcode project resources
cp -r weights/gemma-3-270m-it MyApp/Resources/

In Xcode, add the model folder to your target’s “Copy Bundle Resources”.

Step 4: Use in Swift

import Foundation

// Get bundle path
let modelPath = Bundle.main.path(forResource: "gemma-3-270m-it", ofType: nil)!

// Initialize model
let model = try cactusInit(modelPath, nil, false)
defer { cactusDestroy(model) }

// Run inference
let messages = #"[{"role":"user","content":"Hello!"}]"#
let result = try cactusComplete(model, messages, nil, nil, nil)
print(result)

See the Swift SDK Guide for complete API documentation.

Android Installation

Step 1: Build Shared Library

From the Cactus source directory:

cactus build --android

This generates android/build/lib/libcactus.so.

Step 2: Integrate into Android Project

For Android-only Apps

Copy libcactus.so to app/src/main/jniLibs/arm64-v8a/
Copy android/Cactus.kt to app/src/main/java/com/cactus/

For Kotlin Multiplatform

Copy source files:
- Cactus.common.kt → shared/src/commonMain/kotlin/com/cactus/
- Cactus.android.kt → shared/src/androidMain/kotlin/com/cactus/
- Cactus.ios.kt → shared/src/iosMain/kotlin/com/cactus/
- cactus.def → shared/src/nativeInterop/cinterop/
Copy binaries:
- libcactus.so → app/src/main/jniLibs/arm64-v8a/
Update build.gradle.kts:

kotlin {
    androidTarget()
    
    listOf(iosArm64(), iosSimulatorArm64()).forEach {
        it.compilations.getByName("main") {
            cinterops {
                create("cactus") {
                    defFile("src/nativeInterop/cinterop/cactus.def")
                    includeDirs("/path/to/cactus/ffi")
                }
            }
        }
        it.binaries.framework {
            linkerOpts("-L/path/to/apple", "-lcactus-device")
        }
    }
    
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
        }
    }
}

Step 3: Download Models

On your development machine:

cactus download google/gemma-3-270m-it

Copy the model to your Android device:

adb push weights/gemma-3-270m-it /sdcard/cactus/models/

Or bundle in app/src/main/assets/ and copy to internal storage at runtime.

Step 4: Use in Kotlin

import com.cactus.*
import android.os.Environment
import org.json.JSONObject

// Use external storage or app-specific directory
val modelPath = "${Environment.getExternalStorageDirectory()}/cactus/models/gemma-3-270m-it"

// Initialize model
val model = cactusInit(modelPath, null, false)

// Run inference
val messages = """[{"role":"user","content":"Hello!"}]"""
val resultJson = cactusComplete(model, messages, null, null, null)
val result = JSONObject(resultJson)

Log.d("Cactus", "Response: ${result.getString("response")}")

// Cleanup
cactusDestroy(model)

See the Kotlin SDK Guide for complete API documentation.

SDK-Specific Setup

Python SDK

Python bindings are installed automatically with source ./setup. To rebuild Python bindings:

cactus build --python

Verify:

from cactus import cactus_init, cactus_complete
print("Cactus Python SDK loaded successfully")

See the Python SDK Guide for complete documentation.

Swift SDK

Build for all Apple platforms:

cactus build --apple

Outputs:

cactus-ios.xcframework - iOS (device + simulator)
cactus-macos.xcframework - macOS
libcactus-device.a - iOS device static lib
libcactus-simulator.a - iOS simulator static lib

See the Swift SDK Guide for integration instructions.

Kotlin SDK

Build for Android:

cactus build --android

Output: android/build/lib/libcactus.so See the Kotlin SDK Guide for integration instructions.

Flutter SDK

Build for all platforms:

cactus build --flutter

See the Flutter SDK Guide for integration instructions.

Rust SDK

Rust bindings use bindgen to generate FFI wrappers from C headers. See rust/README.md for setup instructions.

Downloading Models

CLI Download

Download models using the CLI:

# Default precision (INT4)
cactus download google/gemma-3-270m-it

# Specific precision
cactus download LiquidAI/LFM2-1.2B --precision INT8
cactus download openai/whisper-small --precision FP16

# With HuggingFace token (for gated models)
cactus download meta/llama-3-1b --token hf_...

# Force reconversion
cactus download LiquidAI/LFM2-VL-450M --reconvert

Models are saved to weights/<model-name>/.

Available Precisions

Precision	Size	Speed	Quality	Use Case
INT4	~150MB	Fastest	Good	Default, mobile devices
INT8	~300MB	Fast	Better	When RAM is available
FP16	~600MB	Slower	Best	Required for some models (Moonshine)

Moonshine models require FP16 precision:

cactus download UsefulSensors/moonshine-base --precision FP16

Model Locations

Models are stored in:

macOS/Linux: ./weights/ (relative to repo root)
iOS: App bundle or Documents directory
Android: External storage or app-specific directory (/sdcard/cactus/models/)

Cloud API Setup (Optional)

Cactus supports automatic cloud handoff when on-device confidence is low. Set your Cactus Cloud API key:

cactus auth

This will prompt you to enter your API key, which is saved to ~/.cactus/auth. Check status:

cactus auth --status

Clear key:

cactus auth --clear

Cloud handoff is optional. Cactus works fully offline without an API key.

Testing Installation

Run the built-in test suite:

# Quick test with default models
cactus test

# Test specific model
cactus test --model LiquidAI/LFM2-VL-450M

# Run only LLM tests
cactus test --llm

# Run only STT tests  
cactus test --stt

# Run performance benchmarks
cactus test --benchmark

# Test on connected iPhone
cactus test --ios

# Test on connected Android device
cactus test --android

Building for Production

iOS Release Build

cactus build --apple

Then archive your app in Xcode:

Product → Archive
Distribute App → App Store Connect
Upload to TestFlight or App Store

Android Release Build

Ensure libcactus.so is in app/src/main/jniLibs/arm64-v8a/
Build release APK or AAB:

./gradlew assembleRelease  # APK
./gradlew bundleRelease    # AAB (for Play Store)

Sign and upload to Google Play Console

Model Size: Models can be 150-600MB each. Consider:

Downloading models on first launch instead of bundling
Using INT4 quantization to reduce size
Implementing on-demand model download

Troubleshooting

macOS: “command not found: cactus”

# If using Homebrew
brew install cactus-compute/cactus/cactus

# If using source, ensure setup was sourced
source ./setup
which cactus  # should show ./venv/bin/cactus

Linux: “python3.12: command not found”

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.12 python3.12-venv

iOS: “dyld: Library not loaded”

Ensure XCFramework is set to “Embed & Sign” in:

Target → General → Frameworks, Libraries, and Embedded Content

Android: “java.lang.UnsatisfiedLinkError”

Ensure libcactus.so is in the correct location:

app/src/main/jniLibs/arm64-v8a/libcactus.so

Verify it’s included in the APK:

unzip -l app.apk | grep libcactus

“Failed to initialize model”

Check:

Model path is correct (use absolute paths)
Model was fully downloaded:
```
ls -lh weights/gemma-3-270m-it/
```
Sufficient RAM available (close other apps)
Correct precision for model (Moonshine requires FP16)

Build Errors

# Clean and rebuild
cactus clean
source ./setup
cactus build --apple  # or --android, --python, etc.

Next Steps

Run Your First Inference

Follow the Quickstart to run your first model.

Explore the API

Read the Engine API Reference for all available functions.

SDK Guides

Check out platform-specific guides: Python, Swift, Kotlin

Advanced Features

Learn about Tool Calling, RAG, and Embeddings.

Additional Resources

For issues or questions, please open an issue on GitHub or ask in the Reddit community.

Get Started

Core Concepts

Guides

Platform SDKs

Advanced

​Installation

​System Requirements

​macOS

​Linux

​iOS

​Android

​macOS Installation

​Option 1: Homebrew (Recommended)

​Option 2: Source Build

​Linux Installation

​Install Dependencies

​Build from Source

​Configure Git Identity (Optional)

​iOS Installation

​Step 1: Build XCFramework

​Step 2: Integrate into Xcode Project

​Option A: XCFramework (Recommended)

​Option B: Static Library

​Step 3: Download Models

​Step 4: Use in Swift

​Android Installation

​Step 1: Build Shared Library

​Step 2: Integrate into Android Project

​For Android-only Apps

​For Kotlin Multiplatform

​Step 3: Download Models

​Step 4: Use in Kotlin

​SDK-Specific Setup

​Python SDK

​Swift SDK

​Kotlin SDK

​Flutter SDK

​Rust SDK

​Downloading Models

​CLI Download

​Available Precisions

​Model Locations

​Cloud API Setup (Optional)

​Testing Installation

​Building for Production

​iOS Release Build

​Android Release Build

​Troubleshooting

​macOS: “command not found: cactus”

​Linux: “python3.12: command not found”

​iOS: “dyld: Library not loaded”

​Android: “java.lang.UnsatisfiedLinkError”

​“Failed to initialize model”

​Build Errors

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Installation

System Requirements

macOS

Linux

iOS

Android

macOS Installation

Option 1: Homebrew (Recommended)

Option 2: Source Build

Linux Installation

Install Dependencies

Build from Source

Configure Git Identity (Optional)

iOS Installation

Step 1: Build XCFramework

Step 2: Integrate into Xcode Project

Option A: XCFramework (Recommended)

Option B: Static Library

Step 3: Download Models

Step 4: Use in Swift

Android Installation

Step 1: Build Shared Library

Step 2: Integrate into Android Project

For Android-only Apps

For Kotlin Multiplatform

Step 3: Download Models

Step 4: Use in Kotlin

SDK-Specific Setup

Python SDK

Swift SDK

Kotlin SDK

Flutter SDK

Rust SDK

Downloading Models

CLI Download

Available Precisions

Model Locations

Cloud API Setup (Optional)

Testing Installation

Building for Production

iOS Release Build

Android Release Build

Troubleshooting

macOS: “command not found: cactus”

Linux: “python3.12: command not found”

iOS: “dyld: Library not loaded”

Android: “java.lang.UnsatisfiedLinkError”

“Failed to initialize model”

Build Errors

Next Steps

Additional Resources