Troubleshooting

Docker permission denied

If you see /var/run/docker.sock: connect: permission denied:

1. Add your user to the docker group (creates the group first if it doesn’t exist):

   getent group docker >/dev/null || sudo groupadd docker
   sudo usermod -aG docker $USER
   newgrp docker

2. Set the socket permissions so only root and members of the docker group can access it:

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

   This sets the socket to rw-rw----, removing access for all other users. You must be in the docker group (step 1) for this to work.

3. Log out and back in (or reboot) for the group change to take full effect. The newgrp command above applies it to the current shell only.

AppArmor sandbox error (Ubuntu 24.04)

If you see FATAL:setuid_sandbox_host.cc(158)] The SUID sandbox helper binary was found, but is not configured correctly, 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 launch the app again.

Running with Podman on restricted Linux systems

1. Install the Podman shim script

Some environments need a wrapper around podman to fix an NFS volume-mount bug and to sanitize the UID/GID that the App passes to the container.

Create the directory if it doesn’t already exist:

mkdir -p ~/.local/bin

Then create a file named ~/.local/bin/podman with the following content. This shim will be found on PATH before the real podman binary:

#!/bin/bash

CURRENT_UID=$(id -u)
CURRENT_GID=$(id -g)

NEW_ARGS=()
for arg in "$@"; do
    # 1. Fix the NFS volume-mount bug by appending the overlay override option (:O)
    if [[ "$arg" == *"/nfs/<mount>"* ]]; then
        arg="${arg//\/nfs\/<mount>:\/data/\/nfs\/<mount>:\/data:O}"
    fi

    # 2. Sanitize the network IDs
    if [[ "$arg" == *"NB_UID=${CURRENT_UID}"* ]]; then
        arg="${arg//NB_UID=${CURRENT_UID}/NB_UID=1000}"
    fi
    if [[ "$arg" == *"NB_GID=${CURRENT_GID}"* ]]; then
        arg="${arg//NB_GID=${CURRENT_GID}/NB_GID=100}"
    fi
    NEW_ARGS+=("$arg")
done

exec /usr/bin/podman "${NEW_ARGS[@]}"

Then make it executable:

chmod +x ~/.local/bin/podman

If you do need the UID workaround, add your account to /etc/subuid and /etc/subgid (this is why the shim above uses 1000):

# /etc/subuid
<USERNAME>:1000:65536

# /etc/subgid
<USERNAME>:100000:65536

2. Download the image over the CLI

Because pulls through the App can time out, pull and re-tag the image from a terminal first (run this as the user who will launch the App):

podman pull ghcr.io/neurodesk/neurodesktop/neurodesktop:<version>
podman tag ghcr.io/neurodesk/neurodesktop/neurodesktop:<version> docker.io/vnmd/neurodesktop:<version>

Then stop any lingering Podman processes (e.g. a hung pull) and Neurodesk containers, and migrate Podman. The App creates containers named neurodeskapp or neurodeskapp-<port>:

# Stop any running Neurodesk containers
podman stop neurodeskapp 2>/dev/null
podman rm -f neurodeskapp 2>/dev/null
# Force-kill any hung podman or neurodeskapp processes
pkill -9 -u <USERNAME> -f "podman|neurodeskapp"
podman system migrate

3. Point the launcher at the shim

Edit the application shortcut so it uses your ~/.local/bin PATH:

sudo nano /usr/share/applications/neurodeskapp.desktop

Set the Exec line to:

Exec=bash -c "PATH=\"$HOME/.local/bin:$PATH\" /opt/NeurodeskApp/neurodeskapp" %U

Then launch the App from the application menu (the shortcut), not from the CLI.

4. Recovering from a broken volume or incompatible storage

If a session fails to start, delete the broken home volume and try again:

# Stop any running Neurodesk containers
podman stop neurodeskapp 2>/dev/null
podman rm -f neurodeskapp 2>/dev/null
# Force-kill any hung processes
pkill -9 -u $USER -f "podman|neurodeskapp"

# Delete the broken home volume
podman volume rm neurodesk-home

If Podman’s storage database is incompatible (for example after a Podman upgrade), reset it:

podman system reset -f

If that still doesn’t work, remove the stale storage config:

sudo rm -f /home/$USER/.config/containers/storage.conf

Then re-pull and re-tag the image (step 2 above), run podman system migrate, and launch again via the shortcut.