Neuralis 0.3.1

Neuralis 0.3.1

Released: 2026-10-17 · Image: neuralisapp/neuralis:0.3.1 · npm: npm create neuralis@0.3.1 · CLI: npm install -g @neuralis/cli@0.3.1

Highlights

• The documented install commands run as pasted. The Docker first-install block names its release on its own first line (NEURALIS_TAG=latest, or a release tag) instead of a version placeholder that the shell read as a file redirect.
• Setup names every missing prerequisite before it asks anything or writes a file, with the fix for your platform.

Changes

Changed

• Setup checks the ports the stack will publish. A port that is already taken is named together with what holds it, and setup offers the next free one; --compose-only stops and names the .env key to change.
• The bundled Qdrant's host port is a setting: NEURALIS_QDRANT_PORT in .env (default 6333). Backup, vector reset and the Qdrant upgrade read it.
• A Qdrant already answering on the host is offered, never adopted silently: setup asks whether this install runs its own Qdrant (the default) or uses the one it found as an external server. A setup re-run keeps the install's own vector store.
• The Compose project is named after the install folder, so a second install on the same Docker engine gets its own project and its own Qdrant volume.
• An npm install folder runs with Docker Compose only; setup no longer offers the native process mode there.

Fixed

• An npm install folder without a usable Docker stops before the first question and says why: Docker not installed, its daemon not answering, no permission on the Docker socket, or Docker Compose v2 missing. Before, setup completed and printed a next step that could not run.
• Setup run from the image stops before writing anything when the install folder is not mounted into the container.
• npm create neuralis and npm install in a source clone name the missing Linux build tools (python3, make, a C++ compiler) with the install command, before the native module build fails.
• The native Qdrant server on x86_64 Linux is the static musl build, so it starts on Debian 12 and Ubuntu 22.04 (the previous build needed glibc 2.38).
• A source clone inside a container (a devcontainer, Codespaces, CI) is set up as a clone, not as the Docker image.
• The CLI's Claude Code and Codex plugin starts its MCP server in Codex as well: it runs neuralis from PATH.
• The installation guide lists git as a prerequisite of the source clone and the clone's next steps after npm install.

Upgrading

No stored format changes, so the upgrade step finds nothing to convert. An existing .env keeps its ports; setup adds NEURALIS_QDRANT_PORT with 6333.

• npm install folder: npx neuralis update --version 0.3.1 --apply. Without --apply, the command previews the update.
• Public clone: git fetch --tags && git checkout v0.3.1 && npm install, then npx neuralis update --version 0.3.1 --apply and the steps it prints.
• Docker image only: follow the deployment guide's update steps with NEURALIS_TAG=0.3.1 — set the two .env image lines to 0.3.1, run the new image's setup --compose-only, stop the app, run upgrade --apply, and start it again.
• The CLI: npm install -g @neuralis/cli@0.3.1.

Rollback

Restore the previous code and image versions together (npm install neuralis@0.3.0 --save-exact in an npm install folder, or git checkout v0.3.0 && npm install in a clone) and recreate the stack.

Known limits

Neuralis remains beta. On Docker Desktop (macOS, Windows), setup's port check sees the setup shell's network, not Docker's; a port held only inside Docker Desktop is still reported by docker compose up. Native ARM runtime acceptance and all-channel non-localhost update coverage remain limited.

---

Source commit 5e95b9b19da55d0e59037783e2447914616b8114 · public snapshot commit b7c8ea17664ba89f2116ad96b5b70ff0a8cf8d4e

Neuralis 0.3.0

Neuralis 0.3.0

Released: 2026-10-16 · Image: neuralisapp/neuralis:0.3.0 · npm: npm create neuralis@0.3.0 · CLI: npm install -g @neuralis/cli@0.3.0

Highlights

• The neuralis command line reaches a Neuralis workspace as you: sign in once, call any package route, serve your agent's tools to Claude Code, Codex or Cursor over MCP, export its skills as a plugin, or launch Claude Code with your agent's capabilities.
• A Docker install that is not set up yet says so on every page and names the setup command; setup itself runs from the image without Node.js on the machine.

Changes

Added

• @neuralis/cli, a new npm package: login / logout (browser consent, revocable), whoami, request <METHOD> <package>/<route>, skill list / skill read, mcp (stdio bridge to the workspace's MCP endpoint), plugin export --for claude|codex|cursor|agents, and launch claude|codex with per-conversation capability sets in merged, governed or native mode.
• The CLI is a Claude Code and Codex plugin; the host package carries a marketplace entry for each.
• Sign-in grants are bound to the surface they were issued for (package-route API or MCP) and can be revoked.

Changed

• Built-in skills call the workspace through one neuralis request line, the same inside an agent's shell and on your own machine. The image ships the CLI.
• The new logo appears across the workspace, docs, landing page and marketplace.
• File review: the pending-changes list pages through large inventories, and repair runs in bounded, stoppable batches.

Removed

• The unused community MCP API key setting. Per-agent API keys are unchanged.

Fixed

• An unconfigured Docker instance answers "setup required" instead of a silent server error, and its health check reports unhealthy.
• Setup failures stop before writing anything and name the next step.

Upgrading

The update runs a data upgrade that binds existing sign-in grants to the MCP surface; existing MCP clients keep working.

• npm install folder: npx neuralis update --version 0.3.0 --apply. Without --apply, the command previews the update.
• Public clone: git fetch --tags && git checkout v0.3.0 && npm install, then npx neuralis update --version 0.3.0 --apply and the steps it prints.
• Docker image only: follow the installation guide's update steps — set the two .env image lines to 0.3.0, run the new image's setup --compose-only, stop the app, run upgrade --apply, and start it again.
• The CLI: npm install -g @neuralis/cli (Node.js 22 or newer), then neuralis login --host <your workspace URL>.

Rollback

Restore the checkpoint named by the update with the app stopped, then restore the previous code and image versions together (npm install neuralis@0.2.1 --save-exact in an npm install folder, or git checkout v0.2.1 && npm install in a clone) and recreate the stack.

Known limits

Neuralis remains beta. The CLI is an agent-class client: actions reserved for a person in the browser (connecting provider accounts, writing secrets) answer 403 human_only. Governed launch is Claude Code only. Native ARM runtime acceptance and all-channel non-localhost update coverage remain limited.

---

Source commit 5b870d1c03ace382cee1fa298d9534b461b3d3fa · public snapshot commit 830ed18747d014f2f03986bbe11462120a936a7e

Neuralis 0.2.1

Neuralis 0.2.1

Released: 2026-10-12 · Image: neuralisapp/neuralis:0.2.1 · npm: npm create neuralis@0.2.1

Highlights

• Windows installation works through the npm CLI, and the setup wizard detects Docker correctly.
• Workspace Groups, multiple app windows and revised docks make it easier to arrange work across agents.

Changes

Added

• Workspace Groups keep a shared arrangement across agents, alongside per-agent layouts.
• Apps that allow multiple instances can open in separate windows. The dock offers a window chooser and a New window action.
• Packages can provide dock images, subject to the same contribution access checks.
• Randomize and Undo change workspace appearance together while preserving windows and agent selection.

Changed

• Docks support corners and edge midpoints, horizontal or vertical orientation, and adjacent placement.
• Phone mode uses one foreground window and a dock sheet; selecting an agent brings its chat forward.
• Dark, Focus, Graphite and Light use light text. Light has a neutral grey background. Widget, dock and background appearance can be set separately.
• Admin's sidebar supports expanded, icon-only and hidden states.

Fixed

• Docker setup forwards a custom MCP port to the companion server correctly.
• First-run setup creates a missing data home before recording the Qdrant version.
• The Windows installer and updater invoke the npm CLI reliably instead of trying to spawn the npm command by name.
• The installer defaults to its own release version.
• Windows Docker detection no longer depends on shell redirection.
• Apps stays reachable outside the dock's scrolling area, and Dim dock tiles use the shared glass appearance.
• Workspace server rendering no longer fails on an incompatible hook call.
• Setup's login hint names the command to run.

Upgrading

Node.js 26 or newer is required on the machine running the installer and operator commands.

• npm install folder: npx neuralis update --version 0.2.1 --apply. Without --apply, the command previews the update. It updates the packages and image tags, regenerates compose, checkpoints and upgrades data with the app stopped, recreates the stack and checks health.
• Public clone: git fetch --tags && git checkout v0.2.1 && npm install, then npx neuralis update --version 0.2.1 --apply and the steps it prints.
• Image only: set NEURALIS_IMAGE_TAG=0.2.1 and NEURALIS_MACHINE_IMAGE=neuralisapp/webtop-ubuntu-xfce:0.2.1 in .env; update a pinned MCP sidecar image in Admin Config. Then stop only the app, run docker compose run --rm --no-deps neuralis node bin/neuralis.mjs upgrade --apply, and recreate with docker compose up -d -V. Keep Qdrant running.
• A folder created by 0.1.0: with the app stopped, first run npx --yes create-neuralis@0.2.1 convert ., then the npm-folder update above. Native deployments use a source clone.
• Existing Files tabs reset once when moving to the window-specific state. Old dock placement records use that dock's defaults; arrange them again if needed.

Rollback

Restore the checkpoint named by the update with the app stopped. Restore the previous code and image versions together: npm install neuralis@0.2.0 --save-exact in an npm install folder, or git checkout v0.2.0 && npm install in a clone. Restore the previous image settings and recreate the stack. A code-only rollback does not restore layout state.

Known limits

Neuralis remains beta. Existing virtual desktops keep their installed companion until recreated. Native ARM runtime acceptance and all-channel non-localhost update coverage remain limited. Some faint terminal and calendar text on the Light theme still needs contrast refinement.

---

Source commit 583632bd6cc5b5ce9ea148b6cba5b85c106b7e7f · public snapshot commit bdeed69f75b2d2d3f24d82c4259f678ae7b2f416

Neuralis 0.2.0

Neuralis 0.2.0

Released: 2026-10-10 · Image: neuralisapp/neuralis:0.2.0 · npm: npm create neuralis@0.2.0

Highlights

• One release is now one version everywhere: the host, the @neuralis/* packages, the image and its companion images move together, through one neuralis command line, and stored data is only ever raised by an explicit offline upgrade on a stopped app.
• A running installation tells its platform admins when a new release is published (Admin dashboard and Inbox, on by default, switchable off).
• Security fix: skill activation never hands a reserved platform secret to a skill. Update to 0.2.0.

Changes

Added

• neuralis command line — every operator command is one verb of one tool: npx neuralis <command> in an install folder, node bin/neuralis.mjs <command> inside the image (setup, update, upgrade, checkpoint, backup, mount, pkg, user, host-broker and the rest).
• neuralis upgrade — raises stored data formats on a stopped app: a dry run lists what would change and what blocks it; --apply takes one checkpoint, runs every pending upgrade, resumes an interrupted run and writes nothing when there is nothing to do.
• neuralis update reads the release manifest attached to the published GitHub release, so the host, its packages, the image tag and the default companion images move as one tested line, and in an install folder --apply runs the whole update — stop, offline upgrade, restart, health check; it never moves an install down unless you name an older manifest, and it leaves custom images untouched.
• create-neuralis convert — a one-time conversion of a folder created by npm create neuralis@0.1.0 into the new install-folder layout, behind a checkpoint, with a rollback.
• Release notice — platform admins see the installed and the latest version on the Admin dashboard and one Inbox notice per new version. The check reads the published release manifest once a day, sends no identity and installs nothing; turn it off with the updateCheck platform setting, or point updateManifestUrl at a public mirror.
• Operator packages in the container — a package added with neuralis pkg add in an install folder reaches the container: the install builds one local image on top of neuralisapp/neuralis:0.2.0 with your packages, rebuilt by neuralis rebuild (and by update --apply) only when the package list or the version changes.
• Docs changelog — every release's notes on the docs site.
• Brain notifications in the Inbox — a source sync that fails, recovers or completes, a finished re-index, and embedding that degrades or recovers, each with a link to the Sources panel or Vector Health.
• Setup offers "No embedding model": indexing, text and field search and source-discovered skills run without an embedding model or embedding API cost; a model can be added later in Admin → Vector.
• Claude Haiku 5.5 in the model catalog.

Changed

• Node.js 26 or newer — the neuralis command line and npm create neuralis now require Node.js 26 (the image already runs on it); on an older Node they stop at once and name the version they found.
• npm install folder — a folder made by npm create neuralis is now a plain npm project that pins neuralis to an exact version (save-exact); the @neuralis/* packages come pinned with it, and the packages you registered stay your own lines of its package.json.
• Companion images — the virtual desktop and the MCP sidecar default to the release version (:0.2.0) instead of a moving dev tag, so a pinned host no longer drifts.
• Container checkpoints persist — the generated compose file binds <NEURALIS_HOME>/checkpoints, so a checkpoint taken inside the container survives it; an upgrade refuses to write a checkpoint into the container's own writable layer.
• No data is converted while the app runs — every runtime data converter is gone; a stored-format change ships as an offline upgrade module, and a build that finds data behind its version refuses to start and names neuralis upgrade.
• Package identity — a package found in a project source is identified by its instance URI, so trust, grants and data stay with that copy; package data folders are a readable mirror of that URI under data/runtime/. The upgrade moves existing folders.
• Honest embedding state — the Sources panel, Files search and Vector Health say which search mode is in effect and why, and how much embedding work is still owed.
• Agent Config card — the base form sits above the rails, prompt sections are chips, and one Save stores the whole form.
• Outbound requests and the MCP client identify themselves with the release version.
• Claude Haiku 4.5 is removed from the catalog; an agent that used it needs a model chosen by hand. Conversation history and past usage are unchanged.

Fixed

• Usage and spend — each model call is priced on its own before the totals are summed, so tiered prices are no longer applied to a whole turn; the Claude Sonnet 5.5 cached-input price is corrected.
• A data source that kept failing its sync every minute on a very large single-line file now syncs in milliseconds; binary files stay out of the text index, and new local sources skip npm cache folders by default.
• An embedding provider out of credit no longer fails writes or syncs — the file is stored and indexed, and the embedding is caught up later.
• Pending review — a change for a file that no longer exists can be approved or dismissed, a bulk review groups the records it can act on, and an approve after a conflict no longer replays.
• Synced copies of the built-in packages no longer appear as extra source packages.
• neuralis update no longer reads a flag's value as a package name.
• Diff view — added and removed lines keep a full-width background under horizontal scroll.
• Stop — stopping a reply keeps the message you sent and its attachments; the turn ends cleanly instead of cutting the connection, and an unacknowledged message can be recovered.
• Attachments and images — a damaged or unsupported image is marked instead of failing the request, every model receives only the image formats it accepts, and files read from the virtual desktop arrive with their original bytes (images included). Text files such as SVG stay text.
• Setup — the hidden prompts (owner password, API keys) no longer echo into the terminal stream, and a pasted value ending in a newline is accepted.
• Docs — a public clone installs with npm install (the documented pnpm install failed), and every page spells operator commands as npx neuralis <verb>, the form a folder and a clone both run.

Security

• Skill activation never projects a reserved platform secret (a Git access token, an MCP access token, a channel token, a workflow signing secret) into a skill; a skill that asks for one sees it as missing. Every 0.1.0 install should update.
• Skill credentials are bounded by the caller: a skill always gets the caller's own user credentials, project- and agent-level ones only with credential-write permission in the project, global ones only with platform scope as well. A conversation continued by another member never inherits the previous member's skill credentials or shell scratch folder.
• The Git client library is updated to simple-git 4.0.2, clearing four published advisories.

Upgrading

• Before you start: install Node.js 26 or newer on the machine that runs npx neuralis / npm create neuralis (node --version). The Docker image brings its own.
• npm install folder: npx neuralis update --apply. It reads the published release manifest (--version 0.2.0 names it explicitly), moves the code and the image tags, regenerates the compose file, stops only this install's app (Qdrant keeps running), runs the offline upgrade behind a checkpoint, recreates the stack and waits for /api/health. A failing step stops it and prints where it stopped and the way back. Without --apply it prints that plan: the folder, the compose project, the services and the tags.
• A folder created by npm create neuralis@0.1.0: once, with the app stopped, npx --yes create-neuralis@0.2.0 convert ., then npx neuralis update --version 0.2.0 --apply. The converter comes fresh from npm, so the installed 0.1.0 code does not take part. A folder that was run natively (it holds a .next/ build) is refused with nothing written: a native run moves to a source clone.
• Public clone: git fetch --tags && git checkout v0.2.0 && npm install, then npx neuralis update --version 0.2.0 --apply and the steps it prints.
• Image only: set NEURALIS_IMAGE_TAG=0.2.0 and NEURALIS_MACHINE_IMAGE=neuralisapp/webtop-ubuntu-xfce:0.2.0 in .env (a pinned MCP sidecar image is changed in Admin → Config), then docker compose stop neuralis, docker compose run --rm --no-deps neuralis node bin/neuralis.mjs upgrade --apply, docker compose up -d -V.
• From 0.1.0, every channel: the offline upgrade checks that every stored credential opens with the key file (it names any that do not and writes nothing) and records each vector point's embedding proof. It does not re-embed, but it writes every point once: on a large index it keeps Qdrant busy for minutes, and it prints its progress every 10 000 points. Stop only the app, never docker compose down — Qdrant must keep running. A compose file generated by 0.1.0 has no checkpoints bind; update --apply regenerates it, and a hand-run upgrade refuses until one is in place and says so.
• Agents on Claude Haiku 4.5: choose another model in the agent's settings.
• Virtual desktops: an existing desktop keeps its old file-reading agent until it is recreated; recreate it from the machine settings to read original file bytes.

Rollback

• Code: npm install neuralis@0.1.0 --save-exact in the install folder (a clone: `git checkou...

Neuralis 0.1.0 — first public beta

Neuralis 0.1.0 is the first public beta of the self-hosted, multi-agent and multiplayer AI platform.

Install through one of three channels:

• npm: npm create neuralis my-neuralis
• Docker: docker pull neuralisapp/neuralis:0.1.0
• Source: the host snapshot in this repository, tagged v0.1.0.

Start with the installation guide and the published maturity overview. Deployment requirements, credentials, optional services and security boundaries are documented there.

Docker images are available for Linux amd64 and arm64. The optional MCP sidecar and Ubuntu XFCE desktop are distributed separately as neuralisapp/mcp-sidecar:0.1.0 and neuralisapp/webtop-ubuntu-xfce:0.1.0. Ubuntu XFCE is the desktop offering for this beta. Native amd64 browser automation passed release checks; ARM browser automation remains unverified on native hardware and was unstable under emulation.

This is an early beta. Review the maturity and deployment documentation before production use, back up existing data before upgrading, and supply your own model-provider credentials when needed. The package marketplace remains under development.