Installation

Maturity: how far the subjects on this page are today, as of 2026-10-09. How maturity is measured.

Neuralis ships through three channels. All three deliver the same runtime: the Next.js host application plus the @neuralis/* builtin packages installed as real directories under node_modules/. The app listens on port 3100; the external MCP endpoint listens on port 3101 (see MCP access).

1. npm (self-hosted)Copy Anchor Link

npm create neuralis my-neuralis   # an npm project that depends on one exact neuralis release
cd my-neuralis
npx neuralis setup                # interactive first-run setup — see the next page
docker compose up -d

On Linux, the install compiles the terminal's native module (node-pty ships no Linux prebuild), so python3, make and a C++ compiler must be present first — on Debian or Ubuntu, apt install build-essential python3. The same holds for a source checkout (channel 3); the Docker image is unaffected.

This creates an install folder you own: an ordinary npm project whose package.json depends on the exact neuralis version (with save-exact in its .npmrc), the host package and the @neuralis/* packages under node_modules/, and the neuralis command line as npx neuralis <command>. A folder rather than a global install is deliberate: this is where your .env, your generated compose file and your mounts live, and where your own registered packages are listed. Updating is npx neuralis update --apply — one exact release for every package and image, carried through this folder's own stack (stop, data upgrade, restart, health check), never the package manager replacing the folder underneath you (Deployment).

Setup writes .env and the compose file into this folder; the compose file runs the published image at the exact release recorded there. Running the host natively, without Docker, is done from a clone of the public host repository (channel 3), which is the host package itself: there npx neuralis setup, npm run build and npm run start share one folder and one .env. Native mode requires Node 26 or newer (the version the image runs) and a Qdrant instance for vector memory — the setup script can download and start a Qdrant binary for you, or fall back to a degraded in-memory mode.

2. Docker image (recommended for teams)Copy Anchor Link

docker pull neuralisapp/neuralis:<version>   # the release you install
npx neuralis setup    # in an install folder from §1 (npm create neuralis); BEFORE compose; safe to re-run
docker compose up -d  # starts neuralis (:3100, :3101) + qdrant

A pre-built image with everything installed, plus Qdrant as a sidecar service. Run the setup script before the first docker compose up: it creates the ~/.neuralis data directories with correct ownership (if Docker creates them first they end up root-owned), writes the NEXTAUTH_SECRET, and generates the docker-compose.yml — the compose file is a setup artifact tailored to your machine (ports, user/group IDs, Qdrant mode, optional local Ollama service), not a file shipped with the install. Regenerate it any time with npx neuralis setup --compose-only after configuration changes or an update. The compose file runs the image at the exact release recorded in .env as NEURALIS_IMAGE_TAG — never a moving tag; an update moves that line (Deployment covers updating and rolling back).

This is the expected path for an organization deploying on-prem or in a private cloud: the DevOps team deploys the stack, users sign in through the configured auth, and per-project membership controls what each user sees. See deployment for reverse-proxy, TLS, and port-exposure guidance.

The same operator tooling is baked into the image, so a deployment that never checks anything out can still run it — inside the container rather than on the host:

docker compose exec neuralis node bin/neuralis.mjs mount list

That form inspects; anything that writes a compose file, rebuilds an image or restarts the stack has to run on the host, because a container cannot recreate itself. The complete command list — and which form applies to which install — ships with every deployment as the neuralis-operations skill.

3. Git clone (fork the host)Copy Anchor Link

git clone https://github.com/neuralisapp/neuralis
cd neuralis
npm install

The host application in source form, with @neuralis/* dependencies resolved from the registry. This channel exists for advanced self-hosters and organizations that want to customize the host layer — their own auth provider, branding, or audit pipeline — while consuming the platform packages unchanged.

What is persistentCopy Anchor Link

Application state lives outside the container or process:

• ~/.neuralis/app/ — platform configuration, encrypted credentials, audit data, and first-party packages' platform-level data and logs.
• ~/.neuralis/projects/ — per-project data, agents, conversations, and project-installed packages.
• ~/.neuralis/checkpoints/ — the copies npx neuralis upgrade --apply takes before it raises a stored data format (the running app never raises one), so npx neuralis checkpoint restore <id> can take you back one build; the generated compose file binds this folder, so a checkpoint taken in a one-off container lands here too.
• The qdrant-data Docker volume — the vector index (back it up together with ~/.neuralis).

Rebuilding the image or reinstalling the host never touches these. Backing them up, upgrading and going back a version are covered in deployment.

Continue with first-run setup.