Version: v3

Docker Images

Neko as a standalone streaming server is available as a Docker image. But that is rarely interesting for general use. The real power of Neko is in its ability to accommodate custom applications in the virtual desktop environment. This is where the various flavors of Neko Docker images come in.

The base image is available as multi-arch image at ghcr.io/m1k1o/neko/base. See Supported Architectures for more information.

Naming Convention

Neko Docker images are available on GitHub Container Registry (GHCR). The naming convention for Neko Docker images is as follows:

ghcr.io/m1k1o/neko/[<flavor>-]<application>:<version>

<flavor> is the optional flavor of the image, see Available Flavors for more information.
<application> is the application name or base image, see Available Applications for more information.
<version> is the semantic version of the image from the GitHub tags. There is always a latest tag available.

An alternative registry is also available on Docker Hub, however, only images without flavor and with the latest version are available there.

m1k1o/neko:<application>

info

You should always prefer the GHCR registry with the ability to use flavors and specific versions.

Available Applications

The following applications are available as Neko Docker images:

Firefox-based browsers

In comparison to Chromium-based browsers, Firefox-based browsers do not require additional capabilities or a bigger shared memory size to not crash.

Icon	Name	Docker Image
	Firefox The open-source browser from Mozilla.	`ghcr.io/m1k1o/neko/firefox`
	Tor Browser A browser designed to access the Tor network for enhanced privacy.	`ghcr.io/m1k1o/neko/tor-browser`
	Waterfox A privacy-focused browser based on Firefox.	`ghcr.io/m1k1o/neko/waterfox`

Check the Firefox-based browsers customization guide for more information on how to customize Firefox-based browsers (configuring profile, installing extensions, etc.).

Chromium-based browsers

There are multiple flavors of Chromium-based browsers available as Neko Docker images.

They need --cap-add=SYS_ADMIN (see security implications for more information) and extended shared memory size (--shm-size=2g) to work properly.

Docker run command
Docker Compose configuration

docker run \
  --cap-add=SYS_ADMIN \
  --shm-size=2g \
  ghcr.io/m1k1o/neko/chromium

docker-compose.yaml
cap_add:
- SYS_ADMIN
shm_size: 2g

Icon	Name	Docker Image
	Chromium The open-source project behind Google Chrome.	`ghcr.io/m1k1o/neko/chromium`
	Google Chrome The most popular browser in the world.	`ghcr.io/m1k1o/neko/google-chrome`
	Ungoogled Chromium A fork of Chromium without Google integration.	`ghcr.io/m1k1o/neko/ungoogled-chromium`
	Microsoft Edge The new Microsoft Edge is based on Chromium.	`ghcr.io/m1k1o/neko/microsoft-edge`
	Brave A privacy-focused browser.	`ghcr.io/m1k1o/neko/brave`
	Vivaldi A highly customizable browser.	`ghcr.io/m1k1o/neko/vivaldi`
	Opera* A fast and secure browser.	`ghcr.io/m1k1o/neko/opera`

* requires extra steps to enable DRM, see instructions here. libffmpeg is already configured.

Check the Chromium-based browsers customization guide for more information on how to customize Chromium-based browsers (configuring profile, installing extensions, etc.).

Desktop Environments

These images feature a full desktop environment where you can install and run multiple applications, use window management, and more. This is useful for people who want to run multiple applications in a single container.

Icon	Name	Docker Image
	Xfce A lightweight desktop environment.	`ghcr.io/m1k1o/neko/xfce`
	KDE Plasma A feature-rich desktop environment.	`ghcr.io/m1k1o/neko/kde`

Other Applications

As it would be impossible to include all possible applications in the repository, a couple of the most popular ones that work well with Neko have been chosen. Custom images can be created by using the base image and installing the desired application.

Icon	Name	Docker Image
	Remmina A remote desktop client.	`ghcr.io/m1k1o/neko/remmina`
	VLC A media player.	`ghcr.io/m1k1o/neko/vlc`

Remmina Configuration

To use Remmina with Neko, you can either pass the REMMINA_URL=<proto>://[<username>[:<password>]@]server[:port] environment variable (proto being vnc, rdp or spice):

docker run \
  -e REMMINA_URL=vnc://server:5900 \
  ghcr.io/m1k1o/neko/remmina

Or bind-mount a custom configuration file to ~/.local/share/remmina/path_to_profile.remmina. Then pass the REMMINA_PROFILE=<path_to_profile.remmina> environment variable:

default.remmina
[remmina]
name=Default
protocol=VNC
server=server.local
port=5900

docker run \
  -v /path/to/default.remmina:/root/.local/share/remmina/default.remmina \
  -e REMMINA_PROFILE=/root/.local/share/remmina/default.remmina \
  ghcr.io/m1k1o/neko/remmina

VLC Configuration

To use VLC with Neko, you can either pass the VLC_MEDIA=<url> environment variable:

docker run \
  -e VLC_MEDIA=http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4 \
  ghcr.io/m1k1o/neko/vlc

You can also bind-mount your local media files to the container, create a custom playlist, and pass the VLC_MEDIA=<path_to_playlist> environment variable:

docker run \
  -v /path/to/media:/media \
  -e VLC_MEDIA=/media/playlist.xspf \
  ghcr.io/m1k1o/neko/vlc

tip

See neko-apps repository for more applications.

Supported Architectures

Neko Docker images are built with docker buildx and are available for multiple architectures. The following architectures are supported by the base image:

linux/amd64 - 64-bit Intel/AMD architecture (most common).
linux/arm64 - 64-bit ARM architecture (e.g., Raspberry Pi 4, Apple M1/M2).
linux/arm/v7 - 32-bit ARM architecture (e.g., Raspberry Pi 3, Raspberry Pi Zero).

Availability Matrix

The availability of applications for ARM architecture is limited due to the lack of support for some applications. The following table shows the availability of each application for each architecture. The ✅ symbol indicates that the application is available for that architecture, while the ❌ symbol indicates that it is not available.

Application	AMD64	ARM64	ARMv7	Reference
Firefox	✅	✅ *	✅ *	-
Waterfox	✅	❌	❌	Github Issue, Reddit
Chromium	✅	✅ *	✅ *	-
Google Chrome	✅	❌	❌	Community Post
Ungoogled Chromium	✅	❌	❌	Downloads Page
Microsoft Edge	✅	❌	❌	Community Post
Brave	✅	✅ *	❌	Requirements Page
Vivaldi	✅	✅ *	✅ *	-
Opera	✅	❌	❌	Forum Post
Tor Browser	✅	❌	❌	Forum Post
Remmina	✅	✅	✅	-
VLC	✅	✅	✅	-
Xfce	✅	✅	✅	-
KDE	✅	✅	✅	-

* No DRM support.

tip

Oracle Cloud ARM free tier is a great way to test Neko on ARM architecture for free. You can use the ghcr.io/m1k1o/neko/xfce image to run a full desktop environment with Xfce and test the applications.

Available Flavors

Keep in Mind

Currently the focus is on CPU images (wihout any flavor). So the GPU support might not work as expected.

The following flavors are available for Neko Docker images:

nvidia - NVIDIA GPU support.
intel - Intel GPU support.

Intel (VAAPI GPU hardware acceleration)

Only for architecture linux/amd64.

For images with VAAPI GPU hardware acceleration using Intel drivers use:

The base image is available at ghcr.io/m1k1o/neko/intel-base.

Nvidia (CUDA GPU hardware acceleration)

Only for architecture linux/amd64.

For images with Nvidia GPU hardware acceleration using EGL use:

The base image is available at ghcr.io/m1k1o/neko/nvidia-base.

danger

There is a known issue with EGL and Chromium-based browsers, see m1k1o/neko #279.

Naming Convention​

Available Applications​

Firefox-based browsers​

Chromium-based browsers​

Desktop Environments​

Other Applications​

Remmina Configuration​

VLC Configuration​

Supported Architectures​

Availability Matrix​

Available Flavors​

Intel (VAAPI GPU hardware acceleration)​

Nvidia (CUDA GPU hardware acceleration)​