Updating

A release is one version for every package and companion image. An update replaces the application, never the data: ~/.neuralis and the vector store stay where they are, and a stored data format the new release needs is raised offline, with a checkpoint taken first. Take a backup before you start.

Which install do you have?Copy Anchor Link

How you update depends on how the folder that holds .env was made. Look at that folder — ls -a shows the hidden .env:

npx neuralis update works in the first and the third kind. In an image-only folder it stops with "not inside a Neuralis install folder": that folder has no package to move — the image is the release, so the update is the steps below.

npm install folderCopy Anchor Link

cd my-neuralis
npx neuralis update            # plan only: the folder, the services and the version it would move to
npx neuralis update --apply    # update to the latest release

--apply installs the release exactly (the @neuralis/* packages come with it; the packages you registered are untouched), moves the image tag in .env and every companion image still on the release default (in .env and the platform configuration; a custom image is reported and left alone), then runs the rest itself: it regenerates the compose file, stops the app (Qdrant keeps running), raises the stored data formats, recreates the stack and waits for the health check. A folder that registers packages of its own rebuilds its derived image (npx neuralis rebuild) in place of the plain restart. It refuses before moving anything when the app answers on its port but no compose service of the folder runs it. A failing step stops it, and it prints where it stopped, what already ran and the way back. --version <x> updates to a named release instead of the latest and --manifest <https-url|file> to a named release line; without either, the update never moves an install to an older version.

Image-only folderCopy Anchor Link

The Docker installer and setup run from the image make this folder. Pick the release (the tags are on Docker Hub) and write it into .env first — the compose file is generated from what .env names:

cd ~/neuralis                  # the folder that holds .env and docker-compose.yml
NEURALIS_VERSION=0.3.2         # the release to move to
sed -i "s|^NEURALIS_IMAGE_TAG=.*|NEURALIS_IMAGE_TAG=$NEURALIS_VERSION|; s|^NEURALIS_MACHINE_IMAGE=neuralisapp/webtop-ubuntu-xfce:.*|NEURALIS_MACHINE_IMAGE=neuralisapp/webtop-ubuntu-xfce:$NEURALIS_VERSION|" .env

The second expression moves only the default desktop image; a desktop image of your own in NEURALIS_MACHINE_IMAGE is left as it is. Then regenerate the compose file from the new image, and stop, upgrade and restart:

NEURALIS_TAG=0.3.2   # the release in .env NEURALIS_IMAGE_TAG
cd ~/neuralis   # the folder that holds docker-compose.yml
docker run --rm --user "$(id -u):$(id -g)" \
  -v /var/run/docker.sock:/var/run/docker.sock --group-add "$(stat -c %g /var/run/docker.sock)" \
  -v "$HOME/.neuralis:/.neuralis" -e NEURALIS_HOST_HOME="$HOME/.neuralis" \
  -v "$PWD:$PWD" \
  neuralisapp/neuralis:"$NEURALIS_TAG" node bin/neuralis.mjs setup --compose-only --output "$PWD"
docker compose stop neuralis
docker compose run --rm --no-deps neuralis node bin/neuralis.mjs upgrade --apply
docker compose up -d -V

What each step does: setup --compose-only, run from the new image, rewrites the compose file for the release .env names and asks nothing (without the tag line it refuses and writes nothing); stop stops only the app, so Qdrant keeps running for the upgrade; upgrade --apply raises the stored data formats the release needs, after a checkpoint — "nothing to do" is a normal answer; up -d -V starts the new image and renews the anonymous volumes, which would otherwise hide its runtime. Open the app when docker compose ps reports it healthy. A pinned MCP sidecar image is changed in admin Config, not in .env.

Git cloneCopy Anchor Link

NEURALIS_VERSION=0.3.2         # the release to move to
git fetch --tags && git checkout "v$NEURALIS_VERSION" && npm install
npx neuralis update --version "$NEURALIS_VERSION" --apply   # the image tag and companion images

Then regenerate the compose file (npx neuralis setup --compose-only), stop the app (docker compose stop neuralis), raise the data formats (npx neuralis upgrade --apply) and recreate the stack (docker compose up -d -V) — the command prints these steps. A clone run natively stops its process, raises the data formats the same way (npx neuralis upgrade --apply), then npm run build and npm run start replace the compose steps.

From 0.1.0 (once)Copy Anchor Link

The 0.1.0 scaffolder unpacked the host package into the install folder, and its own update command never moves the host. With the app stopped, convert the folder to the npm layout once, then update:

docker compose stop neuralis
npx --yes [email protected] convert .
npx neuralis update --apply

The conversion keeps .env, .npmrc, both compose files and every dependency line you added; it deletes exactly the files the 0.1.0 package shipped, behind a checkpoint in the folder's checkpoints/, and prints the way back. Re-running it resumes; a converted folder is left alone. A host-broker unit written before the conversion is replaced once by neuralis device install on that machine.

After the updateCopy Anchor Link

• Going back a version, the stored data formats and checkpoints: Deployment.
• Qdrant's own version is a separate, deliberate step (npx neuralis qdrant-upgrade, see the production checklist).
• What changed in each release: the changelog.