create-neuralis

The scaffolder behind npm create neuralis <dir> — the primary install path for a self-hosted Neuralis deployment.

npm create neuralis my-neuralis
cd my-neuralis
npx neuralis setup

What it does

1. Claims an empty target directory (refuses a non-empty one — this creates a whole install folder, it does not merge into an existing project).
2. Resolves the exact neuralis version (this scaffolder's own, or --version <v>) and writes the folder's package.json: { "private": true, "dependencies": { "neuralis": "<exact>" } }. The install folder is an ordinary npm project the operator owns; the packages you register later are further lines of the same file. After dependencies it copies that release's own overrides and allowScripts (one npm view neuralis@<exact> --json): the dependency floors the release's lockfile was fixed with — floors, so npm still resolves the newest matching version — and the install scripts npm may run (node-pty's build and the build-tool check before it; npm 12 runs none it is not told to). npm reads both only from this root manifest, so they live here, and npx neuralis update rewrites them for the release it installs. A release that ships neither gets neither, and the run says so.
3. Writes an .npmrc with save-exact=true, so a later npm install <pkg> in the folder writes an exact pin instead of a caret range.
4. Runs npm install, which brings in the host package under node_modules/neuralis (with the @neuralis/* packages it pins exactly) and the neuralis command line as npx neuralis <command>.
5. Prints the next step.

npm create neuralis@<v> installs neuralis <v>, the release this scaffolder belongs to; --version <v> installs another version (--version latest included).

Converting a 0.1.0 folder (once)

The 0.1.0 scaffolder unpacked the host package into the folder itself. With the app stopped, npx --yes create-neuralis@<version> convert <dir> moves such a folder to the layout above, once: it records the old manifest, lock and tarball file list under .neuralis-convert/, writes the new package.json (every dependency line the 0.1.0 package did not ship — a registered package, a file: path — carried verbatim, plus the target release's overrides and allowScripts), removes the 0.1.0 node_modules/ and installs fresh (an install that fails for a network reason leaves the folder without node_modules/ until the registry answers; the Docker-run app is unaffected), then runs the installed neuralis convert --from <old>, which refuses while the app answers, takes one checkpoint and deletes exactly the files the old package shipped. .env, .npmrc, the compose files and anything else in the folder stay. The old tree rides in that checkpoint as one archive (the system tar). A refusal before the checkpoint puts the old package.json, lock and .npmrc back and reinstalls the 0.1.0 tree; a re-run resumes an interrupted conversion and leaves a converted folder alone; npx neuralis convert --rollback <checkpoint id> puts the 0.1.0 folder back. A folder that was run natively (it holds a .next/ build) is refused with nothing written: a native run moves to a source clone (copy .env into it; the NEURALIS_HOME data is untouched).

Prerequisites

Node.js >=26 (the scaffolder and the neuralis command refuse an older one by name). On Linux, step 4 also compiles the terminal's native module (node-pty ships no Linux prebuild), so the machine needs python3, make and a C++ compiler — on Debian/Ubuntu sudo apt install build-essential python3. Without them the scaffolder refuses before it writes the folder, naming what is missing and the install line; a later npm install there refuses the same way before anything compiles (the check is @neuralis/agent-core's preinstall). The Docker image has the module compiled in and runs setup itself, so Docker alone needs neither Node.js nor a compiler.

Design notes

Zero runtime dependencies. This is the first thing a stranger runs; it must not ask them to trust a dependency tree before they have seen anything.

Every registry interaction goes through a child npm process, never a hardcoded registry URL. npm exports its own configuration into an initializer's environment, so running this against a private or local registry resolves the host package from that registry — which is also how the release rehearsal exercises the real code path rather than a test double.

The scaffolder is not the updater. Updating an install folder is npx neuralis update --apply inside it — it moves the code and the image tags, then stops, upgrades, restarts and health-checks that folder's own stack; this package creates a folder, and converts a 0.1.0 one once.

Related install paths

| Channel | Command | |---|---| | npm scaffold (this package) | npm create neuralis <dir> | | Docker image | setup runs from the neuralisapp/neuralis image itself (latest, or a release tag) — the installation guide carries the command | | Source | git clone the public host repository |

License

FSL-1.1-ALv2 (see the repository LICENSE.md; licensor Eszes LLC). Each version converts to Apache-2.0 two years after its release.