Skip to main content

neuralosd — deterministic-first agentic runtime

One pip install. Two sandbox backends. Any data source. Offline. On CPU.

neuralosd is the agentic runtime for neuralOS — the 121M-parameter on-device tool-calling model. It turns any data source into a private, offline question-answering service inside hardware-isolated microVMs.

pip install neuralosd[all]

# or with uv (faster, and can supply its own Python)
uv pip install "neuralosd[all]"
uv tool install neuralosd                      # global CLI
uvx neuralosd ask --instance-dir . "how many rows"   # no install at all

Single-file binaries (no Python required)

Every release ships standalone Nuitka binaries in three variants — the Python runtime, the framework, the docs and the skills are all embedded in one file:

Variant File Adds
base neuralosd-<platform> framework + docs + skills + on-device model
boxlite neuralosd-boxlite-<platform> + the BoxLite microVM engine
msb neuralosd-msb-<platform> + the Microsandbox msb runtime

Each variant carries exactly its own backend — check with neuralosd backends:

Sandbox backends:
  boxlite  [available]
  msb      [not installed]
macos-arm64 macos-x64 linux-x64 linux-arm64 windows-x64
base ✓ ✓ ✓ ✓ ✓
boxlite ✓ — ✓ ✓ —
msb ✓ — ✓ ✓ ✓

— = no upstream wheel for that platform (boxlite: no Windows/Intel-macOS; microsandbox: no Intel-macOS).

# base
curl -L -o neuralosd https://github.com/DrOlu/neuralosd/releases/latest/download/neuralosd-linux-x64
chmod +x neuralosd
./neuralosd init --source data.csv --name mydata
./neuralosd ask --instance-dir ./mydata "how many rows"

# with a sandbox backend
curl -L -o neuralosd-msb https://github.com/DrOlu/neuralosd/releases/latest/download/neuralosd-msb-macos-arm64
chmod +x neuralosd-msb
./neuralosd-msb backends            # msb [available]
./neuralosd-msb deploy --instance-dir ./mydata --name box --backend msb

The first run extracts the payload once (~10 s); later runs are cached and start in ~0.25 s. Built with Nuitka; every binary is verified by a 12-check CLI smoke suite plus a strict backend check in CI.

Beyond what's baked in: the sidecar

A frozen binary cannot import the host's packages — installing a library does not make it visible. So when a probe needs something the binary doesn't carry, it can run that probe in the host Python instead, via a small helper:

# on the HOST (not inside the binary):
pip install neuralosd        # provides the `neuralosd-sidecar` command
pip install pypdf pywinrm    # whatever your probes need

# then just use the binary as normal — it delegates automatically
./neuralosd-msb ask --instance-dir ./mydata "pdf pages"

No Python on the machine? uv can supply one. neuralosd sidecar --setup creates a dedicated environment at ~/.neuralosd/sidecar — installing a Python if necessary — and the binary then finds it with no configuration at all:

neuralosd sidecar --status                      # uv found? provisioned?
neuralosd sidecar --setup --with pypdf,pywinrm  # create it
neuralosd sidecar --setup --force               # rebuild from scratch

Provisioning is always explicit — it touches the network, so it never happens silently while answering a question.

How it decides:

Situation Behaviour
probe's imports all resolve in the binary runs in-process (fast, no subprocess)
probe's import is missing (even lazily, inside the function) retried in the sidecar
probe marked tier="sidecar" always runs in the sidecar
missing import, no sidecar installed exits with pip install <lib> and the neuralosd sidecar --setup hint

Opt out with NEURALOSD_SIDECAR=off, or point at a specific helper with NEURALOSD_SIDECAR=/path/to/neuralosd-sidecar.

So the binary stays one stable file, and you never rebuild it to gain a library — you just add the library to the helper.

What it does

YOUR DATA (CSV, DB, API, logs)     THE RUNTIME                THE RESULT
──────────────────────           ──────────────            ──────────────
profile → model → generate  →   @probe + router    →    ask in English,
                         →   chains + guardrails     get verified
                         →   serve + monitor         answers, offline

Two sandbox backends

Backend Install Best for
BoxLite pip install neuralosd[boxlite] persistent service boxes, CoW clones, port publication
Microsandbox pip install neuralosd[msb] live RAM snapshots, CoW forks, declarative recreate

Both run the same probe contract. Switch by configuration, not code.

Quick start

# 1. Install
pip install neuralosd[all]

# 2. Build an instance from your data
neuralosd init --source your_data.csv --name my-analyst

# 3. Deploy into a sandbox
neuralosd deploy --name my-analyst --backend boxlite

# 4. Ask
neuralosd ask --instance my-analyst "how many records"

The @probe framework

from neuralosd import probe, Instance

@probe(
    description="Customers ranked by lifetime spend",
    triggers=["top customers", "best customers"],
    args={"limit": {"type": "integer", "min": 1, "max": 25, "default": 10}},
    pii=["email"],
)
def top_customers(limit: int = 10):
    return db.query("SELECT ... LIMIT %s", (limit,))

inst = Instance(name="my-analyst", probes=[top_customers])
env = inst.ask("top customers")
print(env["results"])

Chains (multi-step answers)

from neuralosd import chain, ChainRunner

@chain(name="genre_deep_dive", steps=[
    {"probe": "top_genres"},
    {"probe": "tracks_by_genre", "args": {"genre": "{{step_0.genre}}"}},
])
def genre_deep_dive(ctx): ...

runner = ChainRunner(probes_by_name)
runner.register("genre_deep_dive", genre_deep_dive._chain_steps)
result = runner.run("genre_deep_dive")

Meta-selector (multi-instance routing)

from neuralosd import MetaSelector

selector = MetaSelector({
    "finance": {"description": "revenue, invoices, customers"},
    "ops":     {"description": "incidents, uptime, alerts"},
})
instance = selector.route("how many open incidents")  # → "ops"

HITL guardrails

from neuralosd import ConfirmStore
store = ConfirmStore()
pending = store.create(probe_fn, args, reason="low confidence")
# ... human confirms ...
result = store.confirm(pending["confirm_token"])

MCP server (a guarded surface for AI agents)

python3 -m neuralosd.mcp --dir /path/to/instance
# or add to Claude Desktop / Cursor MCP config

The server exposes fourteen tools — ask, search, describe, catalog, explain, health, memory, trace, delegate, discover, build, shadow, mothball, confirm — and every call goes through the same router as neuralosd ask: the calibrated gate, argument caging, PII masking, the results gate, the cache and the audit ledger. A refusal is a result with a machine-readable refusal.code, not an error and never a guess. Tools are discovered with search/describe instead of dumping the whole menu into the agent's context.

Agents get the contracts a harness needs: agent_id / session_id / run_id stamped on the audit row, per-agent ACL/PII/budget from acl.json, idempotency_key so a retry never executes twice, session memory, run traces, mesh delegation, HITL confirm, and the verified build/shadow/mothball lifecycle.

The HTTP service (neuralosd serve) carries the same contracts: POST /ask (sync or async: true), GET /runs/{id}, GET /audit, GET /tools, POST /v1/confirm/{token}, with X-Agent-Id / X-Session-Id / X-Run-Id headers.

Code signing

The Windows release binaries are Authenticode-signed. Signing runs inside the release workflow through SignPath and is gated on the SIGNPATH_* repository configuration (docs/signing.md); the job fails unless Get-AuthenticodeSignature reports Valid for every signed asset. The project is applying to the SignPath Foundation for publicly trusted code signing and will use SignPath Foundation-issued signing once approved.

License

MIT

Metadata

Release files for neuralosd 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neuralosd 3.0.0
File Size Uploaded Provenance Actions
neuralosd-3.0.0.tar.gz 511.7 kB Without provenance Details for neuralosd-3.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neuralosd 3.0.0
File Interpreter ABI Platform Actions
neuralosd-3.0.0-py3-none-any.whl Python 3 none any Details for neuralosd-3.0.0-py3-none-any.whl

Total release size: 886.0 kB

Release files / neuralosd-3.0.0.tar.gz

Download URL neuralosd-3.0.0.tar.gz
Size 511.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c319a7b546b3c8b6f2a437aa9240d9731d90d77306fa09d97a663c757cb69cd4
BLAKE2b-256 checksum
How to use checksums
78be526b557f87b07dbb5a66a1f184eb22a8c76ffb99f11b6a585c8007867005
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / neuralosd-3.0.0-py3-none-any.whl

Download URL neuralosd-3.0.0-py3-none-any.whl
Size 374.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b608449f0c97bdb3ece98baa50798aea0679df6d4a9a1930201b40ef85ed911e
BLAKE2b-256 checksum
How to use checksums
ac0d247d3c5a2fae6442209322286d57144a3c4ae907f5c5980c5221e571d04b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for neuralosd 3.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page