Igloo

A terminal for nsl machines and containers.

Igloo is a GNOME terminal that opens nsl machines the way it opens Podman, Toolbox and Distrobox containers. nsl runs WSL-style Linux machines on atomic Linux hosts: systemd-nspawn containers inside a systemd-vmspawn VM. Pick a machine from the New Tab menu, or create, configure and remove machines in Preferences.

Igloo is based on Ptyxis by Christian Hergert, and keeps everything Ptyxis does. It installs as io.github.frostyard.Igloo, beside Ptyxis, with its own settings.

Install

Igloo is published to the Frostyard Flatpak remote. Add it once, then install Igloo and update it with flatpak update:

flatpak remote-add --if-not-exists frostyard https://frostyard.github.io/flatpak-index/frostyard.flatpakrepo

flatpak install frostyard io.github.frostyard.Igloo

Igloo uses the GNOME 51 runtime from Flathub. Every pull request's CI run also keeps a bundle, igloo-flatpak, to try a change before it merges: unzip it and run flatpak install --user igloo.flatpak.

What it adds to Ptyxis

• New Tab menu. The dropdown next to the new tab button lists nsl machines in a Machines section. Picking one opens a tab in that machine. The menu ends with Manage Machines….
• Profiles and sessions. A profile's Default Container can be an nsl machine, and pinned or restored tabs reopen in their machine. New tabs keep the current machine as they keep the current container.
• Main menu → Machines opens the Machines page in Preferences:
  • every machine with its distribution, tier, state and default marker;
  • New Machine asks for a name, a distribution from the signed nsl catalogue, isolation, default and an optional username, then runs nsl create in a terminal so downloads and verification are visible, and offers to open the new machine;
  • per machine: Open Terminal, Start/Stop, Make Default, Edit Profile… (creates or opens a profile whose default container is the machine, for its own palette, font and command) and Remove… (nsl stop then nsl remove --yes, after a confirmation);
  • Resources: shared VM memory and processors, autostart, idle timeout and isolated VM resources, written to nsl.conf;
  • Host: nsl doctor, nsl update and nsl shutdown.

If nsl is not installed, the page links to its installation guide.

Requirements

nsl 0.8.0 or later must be installed on the host; the Flatpak does not bundle it. Igloo reads nsl's state through --json, which 0.8.0 introduced; with an older nsl, machines still open from the New Tab menu, but the Machines page asks you to update. The agent looks for nsl on PATH, then in ~/.local/bin, /home/linuxbrew/.linuxbrew/bin, ~/.linuxbrew/bin, /usr/local/bin and /usr/bin, because a session started through flatpak-spawn often has a minimal PATH. The page's Check Again button looks again after you install it.

Build and install the Flatpak

You need the GNOME 51 SDK and flatpak-builder:

flatpak install --user flathub org.gnome.Sdk//51 org.flatpak.Builder

Build and install for your user (on hosts where home is under /var/home, flatpak-builder needs --filesystem=home to see the checkout):

flatpak run --filesystem=home org.flatpak.Builder --user --install --force-clean build-dir io.github.frostyard.Igloo.json

flatpak run io.github.frostyard.Igloo

To produce a single-file bundle for another computer:

flatpak run --filesystem=home org.flatpak.Builder --repo=repo --force-clean build-dir io.github.frostyard.Igloo.json

flatpak build-bundle repo igloo.flatpak io.github.frostyard.Igloo

The manifest builds VTE 0.84.1 with fast_float and simdutf on top of the GNOME 51 runtime, then builds this checkout.

CI builds the same manifest with its tests on every push and pull request. On main it also exports an OCI image with flatpak build-bundle --oci and pushes it to ghcr.io/frostyard/igloo, which the Frostyard remote serves.

Develop inside the build environment

Build the dependencies once, then use meson inside the SDK:

flatpak run --filesystem=home org.flatpak.Builder --user --force-clean --stop-at=ptyxis build-dir io.github.frostyard.Igloo.json

flatpak build --filesystem=home build-dir sh -c 'meson setup _build --prefix=/app && ninja -C _build && meson test -C _build'

The meson option generic names the application. It defaults to igloo, which also sets the application and GSettings IDs to io.github.frostyard.Igloo; ptyxis, terminal and builder build upstream's names.

How it works

Like Ptyxis, Igloo runs ptyxis-agent on the host, outside the Flatpak sandbox, and talks to it over a private D-Bus connection. Igloo adds to the agent:

• PtyxisNslProvider (agent/ptyxis-nsl-provider.c) exports a container, nsl:NAME, for every machine nsl list --json reports, except incomplete machines and machines being removed. It reads machine names from NSL_HOME/machines at startup, so restored sessions find their machines before nsl list finishes. It reloads when nsl changes its records, its default machine or a VM's runtime directory, and shortly after a terminal starts a machine. It never polls: an nsl list against a running VM counts as activity and would keep the VM from idling.
• PtyxisNslContainer (agent/ptyxis-nsl-container.c) spawns terminals with nsl run -m NAME --cd / -- env VARS… /bin/sh -c SCRIPT DIR ARGV…. nsl only forwards terminal and locale variables, so env carries the rest (VTE_VERSION, PTYXIS_PROFILE, proxies). The script changes to the requested directory, or to the guest home, and starts the account's login shell when the requested program is missing in the machine.
• org.gnome.Ptyxis.Machines (agent/ptyxis-machines-impl.c, interface in agent/org.gnome.Ptyxis.Agent.xml) lists machines and images, reads and writes nsl.conf, and runs short nsl commands for the Preferences page. Writes keep the file's comments and are checked with nsl config; a file nsl rejects is restored.

The directory a new tab starts in follows nsl's rules:

Requested directory	Shared machine	Isolated machine
none (a fresh window)	guest home	guest home
/mnt/host/… (from another machine tab)	kept	guest home
a host directory in your home, /run/media/USER or /mnt	/mnt/host/…, matched by device and inode like nsl	tried as a machine path
anything else	tried as a machine path, else the guest home	same

A new tab receives the previous tab's directory in host terms, so a host tab opened from a machine tab at /mnt/host/var/home/you/src starts in /var/home/you/src. Links clicked in a machine tab that point below /mnt/host open the host file they name.

agent/ptyxis-nsl.c reads the documents nsl list --json, nsl images --json and nsl config --json print, as nsl's CLI contract defines them (nsl ADR-0021). It ignores fields it does not know, and testsuite/test-nsl.c covers real output. The Resources rows take their ranges from config --json.

Known limitations

• A tab only learns its machine's working directory when the guest shell reports it with OSC 7, as vte.sh does. The nsl Debian image ships no such script, so a new tab opened from a machine tab starts in the guest home instead of the current directory. Installing vte.sh (Debian: libvte-2.91-common) in a machine, or adding it to nsl's machine images, fixes this.
• Machine states on the Machines page refresh when the page is shown, after an action and after starting a terminal, not continuously.
• Export and import are not in the interface yet; use nsl export and nsl import.

Relationship to Ptyxis

Igloo follows Ptyxis upstream. Source files, code symbols and the internal D-Bus names keep Ptyxis's names so that upstream changes merge cleanly; only what users see is renamed. Report problems with Igloo's nsl features here, not to Ptyxis. README.ptyxis.md is upstream's README, describing everything Igloo inherits.

License and credits

Igloo is free software under the GNU General Public License, version 3 or later, like Ptyxis. Ptyxis is by Christian Hergert and its contributors; its icons are by Jakub Steiner. The Igloo icon and the nsl integration are by Frostyard.