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

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, the fetch command retrieves the correct binary for your target architecture and stores it at:

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

Example command for a Linux x86_64 target:

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

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:

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

Complete Air-Gapped Usage Example

# 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 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
HF_HUB_OFFLINE=1	Disable Hugging Face Hub network access	doc/apis.md (documented)
NEEDLE_CACHE_DIR	Alternative cache directory (if implemented)	Check 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

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 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.

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