Installation

Maturity: how far the subjects on this page are today, as of 2026-10-05. 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, native Node)Copy Anchor Link

npm create neuralis my-neuralis
cd my-neuralis && npm install

On Linux, npm 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 scaffolds a project directory you own — the host application including a bundled Dockerfile (the docker-compose.yml is generated by the setup script, tailored to your machine) — and npm install pulls the @neuralis/* packages from the registry. A directory rather than a global install is deliberate: this is where your .env, your generated compose file and your build output live, and where you point filesystem mounts and your own packages. Upgrading is an explicit step, not a package manager replacing the folder underneath you.

Then either run natively:

npm run neuralis:setup   # interactive first-run setup — see the next page
npm run build
npm run start

Setup writes .env and the compose file beside the host folder, so the native build and server load the same configuration. The shipped host can build without the development monorepo. You can also switch to Docker with the setup-generated compose file. Native mode requires Node 22.22.2 or newer (26 recommended, 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
pnpm neuralis:setup   # must run BEFORE compose; safe to re-run later
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 pnpm 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 exec neuralis-neuralis-1 sh -c 'cd /neuralis && node --import tsx scripts/mount.mts 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
pnpm 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 a newer build takes by itself before it upgrades a stored data format, so pnpm neuralis:checkpoint restore <id> can take you back one build.
• 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.