Needle Platform Tags: Complete Guide to Engine Support for Cross-Platform Inference

Needle supports six platform tags for its inference engine: macosx_11_0_arm64, manylinux2014_x86_64, manylinux2014_aarch64, musllinux_1_2_aarch64, win_amd64, and win_arm64.

Needle's inference engine is distributed as a native binary (.so on Linux/macOS, .dll on Windows) that must match your operating system and CPU architecture. Understanding which platform tags Needle supports is essential for deployment automation, cross-compilation workflows, and reproducible machine learning infrastructure. The needle fetch command uses these tags to download the correct engine binary from the Hugging Face model hub.

Supported Platform Tags for Needle Engines

According to the cactus-compute/needle source code, the following platform tags are officially supported when using needle fetch --platform-tag:

Platform Tag	Target System
macosx_11_0_arm64	macOS 11 (Big Sur) on Apple Silicon (ARM64)
manylinux2014_x86_64	Linux manylinux2014 on 64-bit x86 CPUs
manylinux2014_aarch64	Linux manylinux2014 on 64-bit ARM CPUs
musllinux_1_2_aarch64	Alpine Linux musl 1.2 on 64-bit ARM
win_amd64	Windows 64-bit (x86_64)
win_arm64	Windows on ARM 64-bit processors

These tags follow Python wheel naming conventions and are documented in doc/apis.md at line 159.

How Needle Platform Tag Detection Works

When you run needle fetch without arguments, the tool automatically detects your host platform and downloads the matching engine binary to ~/.cache/cactus-needle/<engine version>/.

Supplying --platform-tag <tag> overrides this autodetection. This capability enables three critical use cases:

• Cross-compilation workflows — Build for target architectures different from your build machine
• Offline device provisioning — Pre-download engines for air-gapped deployments
• Reproducible deployments — Pin exact engine binaries across environments

Using Needle Platform Tags: CLI Examples

Fetch Engine for Current Machine (Default)

needle fetch

Explicitly Request Specific Platforms

# macOS Apple Silicon

needle fetch --platform-tag macosx_11_0_arm64

# Linux x86_64 (most common server target)

needle fetch --platform-tag manylinux2014_x86_64

# Linux ARM64 (AWS Graviton, Raspberry Pi 4+)

needle fetch --platform-tag manylinux2014_aarch64

# Alpine Linux ARM64 (containerized deployments)

needle fetch --platform-tag musllinux_1_2_aarch64

# Windows x86_64

needle fetch --platform-tag win_amd64

# Windows ARM64 (Surface Pro X, Dev Kit 2023)

needle fetch --platform-tag win_arm64

Loading Custom Engine Paths in Python

If you've cached a platform-specific binary outside the default location, point Needle to it using the NEEDLE_LIB_PATH environment variable:

import os
import needle

# Path to a previously fetched musllinux aarch64 engine

engine_path = os.path.abspath("./engines/libneedle.so")
os.environ["NEEDLE_LIB_PATH"] = engine_path

agent = needle.Needle(tools=[...])
result = agent.run("What is the sunrise time tomorrow?")
print(result)

This pattern is implemented in needle/playground/server.py, which demonstrates binary location logic for production deployments.

Key Source Files for Platform Tag Implementation

File	Purpose
doc/apis.md	Documents --platform-tag option and supported tags
needle/__init__.py	Reads NEEDLE_LIB_PATH, exposes public Needle API
needle/playground/server.py	Production example of engine binary loading

Summary

• Needle supports six platform tags: three Linux variants, two Windows variants, and one macOS variant
• Tags follow Python wheel conventions: {platform}_{version}_{arch} format
• needle fetch --platform-tag <tag> overrides automatic detection for controlled deployments
• Engine binaries cache to ~/.cache/cactus-needle/ or load from custom paths via NEEDLE_LIB_PATH
• Complete tag list is maintained in doc/apis.md as implemented in cactus-compute/needle

Frequently Asked Questions

What happens if I use the wrong platform tag?

Needle will download the binary you specified, but it will fail to load at runtime with a dynamic linker error or architecture mismatch exception. Always verify your target platform with uname -m (Linux/macOS) or wmic cpu get Architecture (Windows).

Can I use Needle on musl-based Linux systems?

Yes. The musllinux_1_2_aarch64 platform tag supports Alpine Linux and other musl-based distributions on ARM64 hardware. This is critical for containerized deployments using minimal base images.

How do I deploy Needle to multiple architectures in CI/CD?

Run needle fetch --platform-tag <tag> for each target architecture in your build matrix, then bundle the appropriate binary with your deployment artifact. Alternatively, set NEEDLE_LIB_PATH in your runtime environment to point to pre-staged engine binaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}