# Desktop app (https://docs.neuralisapp.com/getting-started/desktop-app)

The desktop app is Neuralis on your own computer: the same host the Docker
image runs, its vector store, and this computer as your own
[device](https://docs.neuralisapp.com/getting-started/devices.md) — your projects, agents and folders in one
window of tabs, with the host kept running in the tray so scheduled work goes on. It
opens the same data folder a Docker install on that machine uses (`~/.neuralis`,
on Windows `%USERPROFILE%\.neuralis`), so the projects you already have are the
projects you see.

## Download [#download]

The installers are attached to each [GitHub
release](https://github.com/neuralisapp/neuralis/releases) — no app store
carries them:

| OS | File | Notes |
| --- | --- | --- |
| Windows 11 x64 | the `.exe` installer | installs for your user only, into `%LOCALAPPDATA%\Programs\Neuralis`, no administrator; unsigned — SmartScreen asks first (**More info** → **Run anyway**) |
| Linux x64 and arm64 | the `.AppImage`, or the `.deb` package | the AppImage runs after `chmod +x` (it needs FUSE 2: `libfuse2`, on Ubuntu 24.04 `libfuse2t64`) and updates itself; the deb installs with `sudo apt install` on the downloaded file and is updated the same way |
| macOS | the `.dmg` disk image (or the `.zip`) | a **preview**, untested, built for Intel: unsigned, so Gatekeeper asks first (**System Settings → Privacy & Security → Open Anyway**); it has not run on an installed Mac yet and does not update itself |

The app carries everything it starts: Node.js, the host, the `neuralis`
command line and the Qdrant vector store. Docker is optional — with Docker the
first-run page recommends keeping the vectors in a Qdrant container of this
folder's own, and the virtual desktop (machines) needs it.

## First run [#first-run]

On a new data folder the app opens a setup page: the owner's email and
password, the first project, where the search index lives (in Docker, or built
in), whether the virtual desktop is on, and whether local AI models run here
(not now, an Ollama already running, Ollama in Docker, or Ollama downloaded for
the app). On a data folder a Docker install set up, it offers to open that
install's projects on its Qdrant — the same users, passwords and credentials —
and, when the Docker app is still running, to stop it first, because only one
host opens a data folder at a time. On Windows, agent commands run in
PowerShell.

## Every day [#every-day]

- **Tabs.** The first tab is this computer's Neuralis — always there, its dot
  saying whether it is starting, running or failed. Every other host you open
  is a tab of its own: close it, drag it to another place, or drag it out of
  the strip into a window of its own (its page moves with it). A host on plain
  `http://` keeps at most 3 tabs — they share its 6 connections and each holds
  one for live updates; the app brings up an open one instead and says why.
  **+** opens the
  app's host list. Ctrl+Tab and Ctrl+Shift+Tab switch tabs; Ctrl+Shift+W and
  Ctrl+Shift+T close and add one (⌘W and ⌘T on a Mac) — Ctrl+W and Ctrl+T stay
  the terminal's.
- **Close and quit.** Closing the main window hides it; the host keeps running in
  the tray. A window you dragged a tab into closes with its tabs. **Quit Neuralis** in the tray stops the device, then the host and
  its vector store, in that order.
- **This computer as a device.** **This computer…** in the tray opens the
  app's page for it: **Pair…** pairs it with the host the app runs (or a host
  open in a tab) after a question naming that host, and **Cancel pairing** stops
  a pairing that runs; **Allow a folder…** grants a folder — the home
  or a whole drive too, with the device's own folder and tools and the host's
  own data in the Neuralis folder (its keys, users, projects and backups) kept
  out, which the dialog names; a folder inside one of them is refused — and a
  pending agent request (**Answer…**) opens a dialog that grants
  exactly the folder it asked for; **Allow background commands…** lets commands keep running up to an hour
  each. Every widening is asked again in a dialog of your system; **Remove**
  takes a folder back at once. **Pause agent access** in the tray (or on the
  page) stops this computer's device until you resume it or restart the app —
  a host restart or a new pairing does not start it again. The rules are on the
  [devices](https://docs.neuralisapp.com/getting-started/devices.md) page.
- **Other hosts.** **+** in the tab strip (or Ctrl+Shift+T) opens a team's Neuralis
  in a tab with its own sign-in — see [join a
  team](https://docs.neuralisapp.com/getting-started/join-a-team.md) — or,
  with one click, a host this computer is paired with or one you opened
  before (the app remembers the last 8 by address only; **Forget** removes
  one). The app's own host always opens in the first tab. A host on this
  computer opens on the address it answers on (`127.0.0.1` or `localhost`).
  A new host tab shows "Connecting to …" until the host answers. A host
  tab that cannot load says so — "This host did not
  answer" (or, when it sent the tab elsewhere, that it could not be
  opened), with the reason — and offers **Retry**; a host that did not answer
  is also tried again by itself, at most every 30 seconds.
- **Reach.** The **Reach** section of **This computer** makes the app reachable
  on this network (it asks, then restarts the host; a switch that fails says
  why there), and shows whether it is reachable from anywhere — and
  `neuralis tunnel on DOMAIN` for reaching it so. Changing the address signs MCP clients and the CLI out and
  pairs devices again.
- **Updates.** At start the installed app checks the public releases once, for
  at most a few seconds (offline, the host starts as usual). The Windows app and
  the AppImage ask, download the new release, check it against the release's
  checksum and install it before the host starts — the host data is then upgraded
  offline, as `neuralis upgrade --apply` does; a download that fails or does not
  match is never installed: the app says so, starts the current version, and the
  tray offers the update again. The deb (replacing a system package needs your
  administrator password) and the macOS preview name the new version and open
  its download page. The question opens over the app's window; unanswered for
  two minutes it counts as **Later**: the host starts and the tray keeps offering
  the update. **Check for updates…** in the tray asks again, and offers a
  restart into the new release.
- **Uninstall.** On Windows, **Settings → Apps → Neuralis → Uninstall** removes
  the app, its update download and its `neuralis://` link handler. Your data
  stays: the data folder (`%USERPROFILE%\.neuralis`) and the app's profile and
  logs (`%APPDATA%\Neuralis Desktop`) — delete them yourself to remove everything.

**The icon.** On Windows and Linux the app and its tray icon are the Neuralis
mark on a transparent background; on macOS the app keeps the mark on its tile,
and the menu-bar icon is the bare mark, drawn in the menu bar's own colour.

The app's own log is in its profile folder (Linux `~/.config/Neuralis Desktop/logs/`,
Windows `%APPDATA%\Neuralis Desktop\logs\`, macOS `~/Library/Logs/Neuralis/`);
what the host prints goes to `app/logs/host.log` in the data folder.

## Limits [#limits]

- Members' shells on the desktop host run only under the OS sandbox once it has
  proven itself on this computer; until then they are refused and the computer
  serves its owner alone ([platforms](https://docs.neuralisapp.com/getting-started/platforms.md)).
- The Windows and macOS builds are unsigned; the macOS build is a preview.
- Windows is built for x64 only.
