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

> Discover Needle's supported platform tags for inference engines including macosx, manylinux, musllinux, and Windows. Optimize your cross-platform deployments efficiently.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: deep-dive
- Published: 2026-08-16

---

**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`](https://github.com/cactus-compute/needle/blob/main/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)

```bash
needle fetch

```

### Explicitly Request Specific Platforms

```bash

# 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:

```python
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`](https://github.com/cactus-compute/needle/blob/main/needle/playground/server.py), which demonstrates binary location logic for production deployments.

## Key Source Files for Platform Tag Implementation

| File | Purpose |
|------|---------|
| [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) | Documents `--platform-tag` option and supported tags |
| [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) | Reads `NEEDLE_LIB_PATH`, exposes public `Needle` API |
| [`needle/playground/server.py`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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.