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 answers with
                         →   serve + monitor         their proof band

Every answer carries a verification band: execution (the probe ran and the results gate passed), golden (the exact question is in the human-written bank and its typed value oracle agreed), or refused. It is a proof of the path, not a promise that the business logic is right — see Security and the envelope contract in the reference.

Connectors: CSV/TSV, SQLite, Excel, JSON/JSONL, syslog, journald, Windows Event Log, REST APIs, browser snapshots, Plasma EDR events, mitmproxy HAR captures, and rea evidence bundles.

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"])

HTTP API (neuralosd serve)

neuralosd serve --instance-dir ./my-instance --port 9998 --api-key "$KEY"
# OpenAPI 3.1: http://127.0.0.1:9998/openapi.json
# HTML reference: http://127.0.0.1:9998/docs

Authenticated /v1 API over the same engine: discovery, ask, typed probe execution, the plan lifecycle with idempotency and a per-instance lock, an append-only hash-chained audit log, reload and metrics. --read-only refuses every mutation; --tls-cert/--tls-key wrap the listener; the default bind is loopback and a non-loopback bind requires a non-default key. See the HTTP API guide.

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

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.3.1
File Size Uploaded Provenance Actions
neuralosd-3.3.1.tar.gz 555.0 kB Without provenance Details for neuralosd-3.3.1.tar.gz

Built distribution (wheel)

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

Total release size: 961.7 kB

Release files / neuralosd-3.3.1.tar.gz

Download URL neuralosd-3.3.1.tar.gz
Size 555.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c49516cc8dc9122799450eeaa83931c203769ceb60de36624c41d4d62bd19c79
BLAKE2b-256 checksum
How to use checksums
38661ef831c8f49bbb52d9d30e03219cd77974dc7b6595c968835a54219b4752
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.3.1-py3-none-any.whl

Download URL neuralosd-3.3.1-py3-none-any.whl
Size 406.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62e489c18c70f6473a6876b3b7a081be7059965a956d7c31986f62e54dce26da
BLAKE2b-256 checksum
How to use checksums
8f0db228deaf53d419bfdc2ffc8bc89fc8889956a1eacba71ddaf0dc97066b6a
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.3.1

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