# Where to Find Pre‑Trained Weights for Needle 2: Hugging Face and CLI Download Guide

> Easily find and download pre-trained weights for Needle 2. Access them via Hugging Face or use the convenient `needle download` CLI command for quick integration.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Pre‑trained weights for Needle 2 are hosted on Hugging Face at `Cactus-Compute/needle2` and can be downloaded manually or fetched automatically via the `needle download` CLI command.**

If you're building with the Needle 2 inference engine, you'll need the base weights to power your agent. The Cactus Compute team distributes these as a compact binary package through Hugging Face, with multiple retrieval options to fit your workflow.

## Hugging Face Hub: Direct Download

The official source for Needle 2 pre‑trained weights is the Hugging Face repository **Cactus‑Compute/needle2**:

```bash

# Direct URL: https://huggingface.co/Cactus-Compute/needle2

```

According to the project README, this hub page stores the baked‑in **14 MB engine** file named `needle‑2.cact` — the complete weight bundle required for inference.

To use a manually downloaded file, pass its path to the `Needle` constructor:

```python
import needle

agent = needle.Needle(
    weights="~/needle-2.cact",  # path to your downloaded .cact file

    tools=[...]
)
result = agent.run("What is the weather in London?")
print(result["results"])

```

## CLI Download: Automated Fetch and Cache

The `needle` package provides a purpose‑built command for retrieving the engine. As documented in [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) (lines 58–63), running:

```bash
needle download Cactus-Compute/needle2

```

This command:
1. Detects your current platform
2. Pulls the appropriate engine binary from Hugging Face
3. Caches it at `~/.cache/cactus-needle/<engine‑version>/`

Once cached, the engine (with embedded weights) is available for completely **offline inference**.

You can verify the download location:

```bash
needle download Cactus-Compute/needle2 --print-path

```

## Automatic Lazy Loading: Zero‑Configuration Option

If you skip the `weights` argument entirely, Needle 2 handles retrieval automatically. The constructor in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) triggers a lazy download on first use:

```python
import needle

# No explicit weights — library fetches engine when first needed

agent = needle.Needle(tools=[...])
response = agent.run("Turn on the kitchen lights")
print(response["results"])

```

This approach suits rapid prototyping but requires network access on the initial run.

## Key Implementation Details

| Component | Location | Purpose |
|-----------|----------|---------|
| [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md) (line 15) | Repository root | Announces Hugging Face weight location |
| [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) (section "Offline devices") | Documentation | Documents `needle download` command and cache behavior |
| [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) | Package core | Implements `weights` parameter handling |
| [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) | CLI module | Implements download command logic |

## Summary

- **Primary source**: Hugging Face repository `Cactus-Compute/needle2` hosts the official `needle‑2.cact` weights file
- **Manual workflow**: Download from Hugging Face, then pass file path to `needle.Needle(weights=...)`
- **CLI workflow**: Run `needle download Cactus-Compute/needle2` to cache platform‑specific engine
- **Automatic workflow**: Omit `weights` argument for lazy first‑time download
- **Cache location**: `~/.cache/cactus-needle/<engine‑version>/` enables offline operation

## Frequently Asked Questions

### How large are the Needle 2 pre‑trained weights?

The complete engine file is **14 MB**, as stated in the repository README. This compact size enables fast distribution and embedding in edge deployments.

### Can I run Needle 2 without internet access?

Yes. After running `needle download Cactus-Compute/needle2` once, the cached engine in `~/.cache/cactus-needle/` supports fully offline inference with no subsequent network requirements.

### What file format contains the Needle 2 weights?

The weights are packaged as a **`.cact` file** — a Cactus‑specific binary format that bundles the neural network weights with the optimized inference engine.

### Is the `needle download` command required, or can I use standard Hugging Face tools?

You can download `needle‑2.cact` directly through the Hugging Face web interface or `huggingface-cli`, but the `needle download` command automatically selects the correct platform binary and manages cache placement for you.