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
Keep an install current with neuralosd update --check (or neuralosd update --yes): pip/uv/pipx installs upgrade through their package manager; the
standalone binaries verify the release's sha256 before an atomic swap. There
is no silent background updater.
Every command documents itself: neuralosd help lists the surface,
neuralosd help <command> (or <command> --help) prints a full page with
examples, exit codes and safety notes, and neuralosd help --json emits the
machine-readable catalogue for orchestrating agents.
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
Metadata
Release files for neuralosd 3.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| neuralosd-3.5.0.tar.gz | 581.4 kB | Without provenance | Details for neuralosd-3.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| neuralosd-3.5.0-py3-none-any.whl | Python 3 | none | any | Details for neuralosd-3.5.0-py3-none-any.whl |
Total release size: 1.0 MB
Release files / neuralosd-3.5.0.tar.gz
| Download URL | neuralosd-3.5.0.tar.gz |
|---|---|
| Size | 581.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4f3e0a2c60973a34f0b766f5f103d89e180bd367a8496027f9879b174a809783
|
|
BLAKE2b-256 checksum How to use checksums |
dc2934b2b13855a286b300821d29239ed1379afd9f74f446e8bfbe0c58cf003a
|
| 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.5.0-py3-none-any.whl
| Download URL | neuralosd-3.5.0-py3-none-any.whl |
|---|---|
| Size | 430.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69f7c3bd1ce01e909eefa569416185eb7e50cf22a446c780594030974e7f0a49
|
|
BLAKE2b-256 checksum How to use checksums |
8c265e3394afb3f50c8522e32c67f53cbae3e444d8f8d701f89787ed24c00bae
|
| 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.5.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.