Neurodesk App

Determine system privileges

Before running the app, check whether your system has privileged access (root/admin permissions). This determines which engine you need to use to run the app:

• If you have privileged access → use the Docker or Podman engine.
• If you do not have privileged access → use the TinyRange engine, or run a remote instance.

Minimum system requirements

1. At least 5 GB free space for the Neurodesktop base image.
2. One of the following options, depending on system privileges:
   • With privileged access: Docker or Podman to run the respective engines.
   • Without privileged access: the TinyRange engine (included with Neurodesk App) and QEMU (only on macOS).

Downloading Neurodesk App

Windows Windows Installer (.exe)

macOS Intel (.dmg) · Apple silicon (.dmg)

Debian / Ubuntu x64 (.deb) · arm64 (.deb)

Red Hat / Fedora / SUSE x64 (.rpm) · arm64 (.rpm)

Arch (AUR) neurodeskapp-bin

More variants: macOS Apple silicon · Debian/Ubuntu arm64 · Red Hat arm64

Microsoft Edge

On Microsoft Edge, follow these steps to download the executable file:

Installing Docker

Note

Docker is required for starting a local instance of Neurodesk. If only connecting to a remote Neurodesk server, you may skip installing Docker.

The Neurodesk App requires Docker to be installed on your computer. If you already have Docker installed, you can skip this step.

• Docker Desktop for Windows
• Docker Desktop for Mac
• Docker Engine for Linux

After installation, open a terminal (Linux/macOS) or command prompt (Windows) and run the following command to verify that Docker is working correctly:

docker --version
docker run hello-world

Installing QEMU

Note

QEMU is only needed if you are using TinyRange on macOS. It is not needed on Windows or Linux using TinyRange since it is included in the install.

The easiest way to install QEMU on macOS is using Homebrew:

brew install qemu

You can verify the installation by running:

qemu-system-aarch64 --version

Installing Neurodesk App

If you have an existing Neurodesk App installation, please first uninstall it by following the uninstall instructions. Then, install the app for your system:

• Debian, Ubuntu Linux Installer: sudo apt install -f ./NeurodeskApp-Setup-Debian.deb
• Red Hat, Fedora, SUSE Linux Installer: sudo rpm -i NeurodeskApp-Setup-Fedora.rpm
• Arch-based package via AUR: yay neurodesk (or follow instructions here)
• macOS Installer: double-click the downloaded .dmg file, then drag NeurodeskApp.app to the Applications folder. To start the app, right-click on NeurodeskApp.app and select Open. For Apple Silicon systems (M1/M2), make sure to enable Rosetta support in the Docker settings for best performance.
• Windows Installer: double-click the downloaded .exe file. Accept to install from an unknown publisher with Yes, then accept the licence agreement and click Finish at the end.

Launching Neurodesk App

The Neurodesk App can be launched directly from your operating system’s application menu, or by running the neurodeskapp command in the command line.

Note that the Neurodesk App will set the File Browser’s root directory based on the launch method used. The default working directory is the user’s home directory, which can be customised from the Settings dialog.

Sessions and projects

Sessions represent local project launches and connections to existing Neurodesk servers. Each Neurodesk UI window in the app is associated with a separate session, and sessions can be restored with the same configuration later on.

Session start options

You can start a new session by using the links at the Start section of the Welcome Page.

• Open Local Neurodesk.. creates a new session in the default working directory.
• Connect to remote Neurodesk server.. creates a session by connecting to a remote Neurodesk server.

Previously opened sessions are stored as part of application data and they are listed on the Welcome Page. Clicking an item in the Recent sessions list restores the selected session.

Connecting to local Neurodesk

Neurodesk App creates new Neurodesk sessions by launching a locally running Neurodesk server and connecting to it. To open a local instance, click the Open Local Neurodesk.. button in the Start section of the Welcome Page.

This will show a JupyterLab interface. There are two options to interact with Neurodesk through this interface:

• By clicking the NeurodeskApp icon on the right. This will launch a new window to start a Neurodesk interface.
• By module-loading containers on the left bar. You can interact with loaded modules through the command line interface.

Connecting to a remote Neurodesk server

It can also connect to an existing Neurodesk server instance that is running remotely. In order to connect to a server, click the Connect to remote Neurodesk server.. button in the Start section of the Welcome Page.

This will launch a dialog that automatically lists the remote Neurodesk server instances.

Select a server from the list or enter the URL of the Neurodesk application server. If the server requires a token for authentication, make sure to include it as a query parameter of the URL as well (/lab?token=<token-value>). After entering a URL, hit Enter to connect.

If the Persist session data option is checked, then the session information is stored and Neurodesk App will re-use this data on the next launch. If this option is not checked, the session data is automatically deleted at the next launch and servers requiring authentication will prompt for re-login.

You can delete the stored session data manually at any time by using the Clear History option in the Privacy tab of the Settings dialog.

Configuration and data files

Neurodesk App stores data in ~/neurodesktop-storage for Linux and Mac, or C:/neurodesktop-storage for Windows, as default.

Add a custom data directory

Neurodesk App stores its data in the following locations:

• By default, /home/jovyan/neurodesktop-storage in the app (bound to the local directory ~/neurodesktop-storage on Unix/macOS or C:/neurodesktop-storage on Windows).
• By choice: in the settings window below, select Additional Directory on the left side bar, click Change to select the local directory, then click Apply & restart. The next time you start the app, the data from the local directory can be found in /home/jovyan/data.

Caution

If you are using Windows it is currently not possible to mount external hard drives. We recommend copying data from the external drive to your local disk first and then processing it in Neurodesk.

Note

If you are using macOS and Docker, mounting an external hard drive will work out of the box. If you are using Podman you have to modify the Podman machine settings with the following commands once and then set the path in the Neurodesk App:

podman machine reset -f
podman machine init --rootful --now -v /Volumes:/Volumes -v $HOME:$HOME podman-machine-default

Tip

If you are using conda environments and you are installing packages or even new kernels, make sure to read the conda tutorial.

Troubleshooting Neurodesk App

/var/run/docker.sock: connect: permission denied, docker

This means that Docker is not correctly set up yet. Run:

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

sudo chown root:docker /var/run/docker.sock
sudo chmod 666 /var/run/docker.sock

FATAL:setuid_sandbox_host.cc(158)

If you see the error FATAL:setuid_sandbox_host.cc(158)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /opt/NeurodeskApp/chrome-sandbox is owned by root and has mode 4755. Trace/breakpoint trap (core dumped), this is caused by a recent change in Ubuntu 24.04.

A temporary workaround: create the file /etc/apparmor.d/neurodeskapp with this content:

# This profile allows everything and only exists to give the
# application a name instead of having the label "unconfined"

abi <abi/4.0>,
include <tunables/global>

profile neurodeskapp "/opt/NeurodeskApp/neurodeskapp" flags=(unconfined) {
  userns,

  # Site-specific additions and overrides. See local/README for details.
  include if exists <local/neurodeskapp>
}

Then restart your computer and try to start the Neurodesk App again.

Uninstalling Neurodesk App

Windows

Open the Windows Apps & Features dialog via Start Menu → Settings → Apps and uninstall Neurodesk App.

To remove the application cache, delete the C:\Users\<username>\AppData\Roaming\neurodeskapp directory. The AppData directory is hidden, so activate hidden items in Windows Explorer under View → Show → Hidden Items.

macOS

Find NeurodeskApp.app in Finder (/Applications or ~/Applications) and move to Trash with CMD + Delete. Clean other application files:

rm -rf ~/Library/neurodeskapp                       # remove application cache
rm -rf ~/Library/Application\ Support/neurodeskapp  # remove user data

Debian / Ubuntu

sudo apt-get purge neurodeskapp # remove application
sudo rm /usr/bin/neurodeskapp   # remove command symlink
rm -rf ~/.config/neurodeskapp   # remove application cache

Red Hat / Fedora / SUSE

sudo rpm -e neurodeskapp        # remove application
sudo rm /usr/bin/neurodeskapp   # remove command symlink
rm -rf ~/.config/neurodeskapp   # remove application cache

Arch

sudo pacman -Rs neurodeskapp-bin