# How to Run Needle on an Air-Gapped Device Without Network Access

> Learn how to run Needle on an air-gapped device. Discover its offline capabilities, with all model weights in a single binary and zero network calls for inference.

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

---

**Yes, Needle supports fully offline operation once the inference engine is obtained, with all model weights baked into a single 14 MB binary and zero network calls during inference.**

**Air-gapped deployment** is a core design goal of Needle, the lightweight LLM inference library from Cactus Compute. After a one-time preparation step on a connected machine, the entire package—including tool-calling, structured extraction, and LoRA-fine-tuned models—runs entirely in RAM with no internet connectivity required.

## Three Steps for Air-Gapped Needle Deployment

The `cactus-compute/needle` repository provides explicit mechanisms to ensure offline operation. Each mechanism is backed by specific source files and environment variables.

### Step 1: Pre-Fetch the Engine on a Connected Machine

The `needle fetch` command downloads the platform-specific engine binary and caches it locally. This is the only step that requires network access.

In [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py), the fetch command retrieves the correct binary for your target architecture and stores it at:

```bash
~/.cache/cactus-needle/<engine version>/

```

Example command for a Linux x86_64 target:

```bash
needle fetch --platform-tag manylinux2014_x86_64

```

After fetching, copy this cached directory to your air-gapped device via USB, secure transfer, or your organization's approved media.

### Step 2: Configure the Engine Location on the Air-Gapped Host

On the isolated machine, Needle's engine-loading logic in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) checks multiple locations in priority order:

1. **User cache directory** (`~/.cache/cactus-needle/`) — standard location
2. **Package directory** — engine placed inside the installed `needle/` folder (takes priority)
3. **Explicit path** — specified via the `NEEDLE_LIB_PATH` environment variable

Set `NEEDLE_LIB_PATH` to bypass cache lookups entirely:

```bash
export NEEDLE_LIB_PATH="/opt/needle/libneedle.so"

```

### Step 3: Install and Run with Network Calls Disabled

Install the Python package from a local wheel to eliminate PyPI dependency:

```bash

# On connected machine

pip download cactus-needle -d ./needle-wheels

# On air-gapped device

pip install --no-index --find-links ./needle-wheels cactus-needle

```

Set `HF_HUB_OFFLINE=1` to prevent any accidental Hugging Face Hub connection attempts, as documented in [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md).

## Complete Air-Gapped Usage Example

```python

# 1. Configure offline environment

import os
os.environ["NEEDLE_LIB_PATH"] = "/opt/needle/libneedle.so"  # pre-copied engine

os.environ["HF_HUB_OFFLINE"] = "1"                          # disable HF network calls

# 2. Import and use Needle—no network traffic occurs

import needle

@needle.tool
def add(a: int, b: int):
    """Add two integers."""
    return {"result": a + b}

agent = needle.Needle(tools=[add])
response = agent.run("What is 7 plus 5?")
print(response["results"])  # → [{'result': 12}]

```

The `.cact` model weights file (~14 MB) loads into memory alongside the engine (~28 MB total RAM usage). No external services are contacted.

## Why Inference Requires Zero Network Access

Needle's architecture guarantees offline operation through several implementation details:

- **Self-contained engine** — The C++ inference binary performs all tokenization, model execution, and sampling locally
- **Baked-in weights** — No dynamic model downloads or weight streaming
- **No telemetry** — No usage reporting, update checks, or cloud dependencies
- **Deterministic caching** — Engine location resolution is purely filesystem-based

The test suite in [`tests/test_weights.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_weights.py) explicitly verifies that the engine loads once and remains resident without network calls.

## Environment Variables for Air-Gapped Configurations

| Variable | Purpose | Source File |
|----------|---------|-------------|
| `NEEDLE_LIB_PATH` | Override engine binary location | [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) |
| `HF_HUB_OFFLINE=1` | Disable Hugging Face Hub network access | [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) (documented) |
| `NEEDLE_CACHE_DIR` | Alternative cache directory (if implemented) | Check [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) |

## Summary

- **Needle is fully air-gappable** after the engine binary is obtained once via `needle fetch`
- **Three deployment paths**: cache directory, package directory, or `NEEDLE_LIB_PATH` environment variable
- **Zero runtime network calls** — the engine never contacts external services during inference
- **Minimal resource footprint** — ~28 MB RAM for the complete inference stack
- **Verified offline operation** — test coverage in [`tests/test_weights.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_weights.py)

## Frequently Asked Questions

### Does Needle require internet access for any feature after initial setup?

No. According to the `cactus-compute/needle` source code, all inference operations—including tool-calling, JSON extraction, and LoRA adapters—execute entirely within the loaded engine. The only network-related function is `needle fetch`, which is explicitly designed as a one-time preparation step performed on a connected machine.

### What is the minimum file set needed to run Needle offline?

You need: (1) the installed `cactus-needle` Python package, (2) the platform-specific engine binary obtained via `needle fetch`, and (3) your `.cact` model weights file. The engine binary can be as small as several megabytes depending on platform. Place the engine in the cache location, package directory, or point to it with `NEEDLE_LIB_PATH`.

### Can I verify that Needle is not making network calls?

Yes. The [`tests/test_weights.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_weights.py) file contains assertions that verify single engine loading without network activity. For runtime verification, use network monitoring tools (`tcpdump`, `strace -e connect`) or firewall rules blocking all egress—the engine will continue functioning normally.

### Does the Hugging Face integration break air-gapped operation?

No, provided you set `HF_HUB_OFFLINE=1`. This environment variable is the standard Hugging Face mechanism for disabling all Hub network calls. Needle respects this setting and does not attempt downloads when offline mode is enabled, as documented in [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md).