Version: v3

Browsers Customization

Browsers use policies to manage settings and configurations programmatically. This is useful for Neko containers that can be set up with a specific configuration every time a fresh container is created. It also prevents users from changing certain settings, which is useful for security and privacy. For example, not allowing users to install extensions can prevent them from installing malicious extensions that could compromise their privacy and security.

However, as a user of Neko, you may want to customize your browser settings (install your own extensions) or wish to have your bookmarks and settings persist across sessions.

Persistent Browser Profile

When you run a browser in a container, the browser runs in a fresh environment every time you create (or upgrade) the container. This means that any changes you make to the browser settings or your browsing history will be lost when you stop the container. This is because the container is ephemeral and does not persist data across sessions.

If you want to persist your browser settings, bookmarks, extensions, and browsing history across sessions, you need to mount a volume to the browser's profile directory. This allows you to store your browser data outside of the container so it can be accessed even after the container is stopped or removed.

docker-compose.yaml
services:
  neko:
    image: "ghcr.io/m1k1o/neko/firefox:latest"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "8080:8080"
      - "52000-52100:52000-52100/udp"
    volumes:
      - "./profile:/home/neko/.mozilla/firefox/profile.default"
    environment:
      NEKO_DESKTOP_SCREEN: 1920x1080@30
      NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
      NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
      NEKO_WEBRTC_EPR: 52000-52100
      NEKO_WEBRTC_ICELITE: 1

Replace ./profile with the path to the directory where you want to store your browser data. This directory will be created if it does not exist.

Make sure to set the correct permissions for the directory so that the container can access it. The Neko user inside the container has a UID of 1000, so you need to set the ownership of the directory to 1000:1000. You can do this by running the following command:

sudo chown -R 1000:1000 ./profile

The path inside the container will be /home/neko/.mozilla/firefox/profile.default, which is the default profile directory for Firefox. You can find the profile directory for other browsers in the table below:

Browser	Profile Directory Path
firefox	`/home/neko/.mozilla/firefox/profile.default`
tor-browser	`/opt/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default`
waterfox	`/home/neko/.waterfox/profile.default`
chromium	`/home/neko/.config/chromium`
google-chrome	`/home/neko/.config/google-chrome`
ungoogled-chromium	`/home/neko/.config/chromium`
microsoft-edge	`/home/neko/.config/microsoft-edge`
brave	`/home/neko/.config/brave`
vivaldi	`/home/neko/.config/vivaldi`
opera	`/home/neko/.config/opera`

Browser Policy Files

Browser policy files are JSON files that contain settings and configurations for the browser. These files are used to manage the browser settings programmatically and can be used to enforce certain policies, such as disabling extensions, setting the homepage, and more.

note

In the example below, we are using the Firefox browser. Make sure you replace /usr/lib/firefox/distribution/policies.json with the correct path for the browser you are using according to the tables below.

If you want to customize the policy file, you can mount your own policy file to the container. This allows you to customize the browser settings and configurations to your liking.

docker-compose.yaml
services:
  neko:
    image: "ghcr.io/m1k1o/neko/firefox:latest"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "8080:8080"
      - "52000-52100:52000-52100/udp"
    volumes:
      - "./policy.json:/usr/lib/firefox/distribution/policies.json"
    environment:
      NEKO_DESKTOP_SCREEN: 1920x1080@30
      NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
      NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
      NEKO_WEBRTC_EPR: 52000-52100
      NEKO_WEBRTC_ICELITE: 1

If you just want to modify the default policy file, you can copy the current policy file from the container to your local machine:

# Create a container without starting it
docker create --name neko ghcr.io/m1k1o/neko/firefox:latest
# Copy the policy file from the container to your local machine
docker cp neko:/usr/lib/firefox/distribution/policies.json ./policy.json
# Remove the container
docker rm neko

Or you can download the default policy file from the repository directly:

# Replace firefox with the browser you are using
curl -o ./policy.json https://raw.githubusercontent.com/m1k1o/neko/refs/heads/main/apps/firefox/policies.json

If you wish to disable the policies altogether, you can just create an empty JSON file. This will disable all policies and allow you to customize the browser settings as you wish.

policy.json

{}

Firefox-based Browsers

The full configuration options for the Firefox-based policy JSON file can be found in the Mozilla Policy Templates documentation.

The policy files are located in the following paths:

Browser	Policy File Path
firefox	`/usr/lib/firefox/distribution/policies.json`
tor-browser	`/opt/tor-browser_en-US/Browser/distribution/policies.json`
waterfox	`/usr/lib/waterfox/distribution/policies.json`

Allow persistent data in policies

By default, the browsers in Neko are set up to forget all cookies and browsing history when they are closed. If you want to allow persistent data, you can set the following policies in the JSON file:

policy.json
{
  "policies": {
    "SanitizeOnShutdown": false,
    "Homepage": {
      "StartPage": "previous-session"
    }
  }
}

Manage extensions

By default, the browsers in Neko do not allow installing extensions except for the ones that are pre-installed.

installation_mode: The installation mode for the extension. It can be one of the following:
- allowed: The extension can be installed by the user.
- blocked: The extension cannot be installed by the user.
- force_installed: The extension is installed automatically and cannot be removed by the user.

policy.json
{
  "policies": {
    "ExtensionSettings": {
      "*": {
        "installation_mode": "blocked"
      },
      "sponsorBlocker@ajay.app": {
        "install_url": "https://addons.mozilla.org/firefox/downloads/latest/sponsorblock/latest.xpi",
        "installation_mode": "force_installed"
      },
      "uBlock0@raymondhill.net": {
        "install_url": "https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi",
        "installation_mode": "force_installed"
      }
    }
  }
}

Chromium-based Browsers

The full configuration options for the Chromium-based policy JSON file can be found in the Chrome Enterprise documentation.

The policy files are located in the following paths:

Browser	Policy File Path
chromium	`/etc/chromium/policies/managed/policies.json`
google-chrome	`/etc/opt/chrome/policies/managed/policies.json`
ungoogled-chromium	`/etc/chromium/policies/managed/policies.json`
microsoft-edge	`/etc/opt/edge/policies/managed/policies.json`
brave	`/etc/brave/policies/managed/policies.json`
vivaldi	`/etc/opt/vivaldi/policies/managed/policies.json`
opera	Does not support policies.

Allow file uploading & downloading

By default, the browsers in Neko do not allow local file access. If you want to allow file uploading and downloading, you can set the following policies in the JSON file:

policy.json
{
  "DownloadRestrictions": 0,
  "AllowFileSelectionDialogs": true,
  "URLAllowlist": [
    "file:///home/neko/Downloads"
  ]
}

Allow persistent data in policies

By default, the browsers in Neko are set up to forget all cookies and browsing history when they are closed. If you want to allow persistent data, you can set the following policies in the JSON file:

policy.json
{
  "DefaultCookiesSetting": 1,
  "RestoreOnStartup": 1
}

Manage extensions

By default, the browsers in Neko do not allow installing extensions except for the ones that are pre-installed.

ExtensionInstallForcelist: These extensions will be installed automatically and cannot be removed by the user.
ExtensionInstallAllowlist: These extensions can be installed by the user when needed; they are not pre-installed.
ExtensionInstallBlocklist: These extensions cannot be installed by the user, which is * (all extensions) by default.

The ID of the extension can be found in the URL of the extension in the Chrome Web Store. For example, the ID of the uBlock Origin extension is cjpalhdlnbpafiamejdnhcphjbkeiagm.

policy.json
{
  "ExtensionInstallForcelist": [
    "cjpalhdlnbpafiamejdnhcphjbkeiagm;https://clients2.google.com/service/update2/crx",
    "mnjggcdmjocbbbhaepdhchncahnbgone;https://clients2.google.com/service/update2/crx"
  ],
  "ExtensionInstallAllowlist": [
    "cjpalhdlnbpafiamejdnhcphjbkeiagm",
    "mnjggcdmjocbbbhaepdhchncahnbgone"
  ],
  "ExtensionInstallBlocklist": [
    "*"
  ]
}

Persistent Browser Profile​

Browser Policy Files​

Firefox-based Browsers​

Chromium-based Browsers​

Persistent Browser Profile

Browser Policy Files

Firefox-based Browsers

Chromium-based Browsers