Install and run Arcane OS on Linux or WSL

Arcane OS currently includes native GTK 4 and WebKitGTK 6.0 Provisioner and Shell hosts plus one shared application host for the exact verified 22-app catalog. Ubuntu under WSLg is the simplest Linux development route on a Microsoft NT machine. Linux remains an experimental developer host even though the controlled WSL Shell and Calculator evidence is now complete for those two journeys.

The Linux artifact is an inventory-verified unsigned-local-test build for development and controlled acceptance. It is not publisher-signed or a release candidate. Installation and account changes require a separately authorized, already-root Provisioner because automatic sudo and PolicyKit brokerage intentionally remains fail-closed.

What works today

• The Linux bundle builds native ArcaneProvisioner, ArcaneShell, and one shared ArcaneAppHost for the 22 registered applications.
• A verified already-root installation writes the protected runtime under /opt/arcane-os.
• Arcane Shell can open inside an already-authenticated Linux or WSLg desktop session.
• Arcane.user.current() reports the current Linux operating-system account as a host-account.
• The Shell lists the exact verified application catalog and launches only the fixed root-owned ArcaneAppHost --app=<verified-id> command. Each application receives its own Core process, WebKitGTK profile, log, title, and declared capabilities.
• Standard local Linux accounts can be staged, separately activated, assigned the protected Arcane shell shim, and restored from an already-root Provisioner.
• Native Linux can register the protected Arcane OS X11 display-manager session. WSLg uses manual launch and does not change the distribution's default boot target.

Controlled Ubuntu/WSL acceptance has verified the protected installed tree, an earlier exact application-catalog listing and dispatch, rendered Shell pixels, and one representative application journey. That historical evidence does not yet cover the current 22-app catalog and does not claim production signing, complete application functionality, all accessibility journeys, or native display-manager sign-in.

You do not need to log out of Linux and sign back in to open the Shell for development, demonstrations, or screenshots. A direct launch demonstrates the native Shell experience; it is not evidence of first-login account provisioning.

Install the build prerequisites

Use WSL 2 with WSLg, Ubuntu, Node.js 22 or newer, npm, and internet access for dependency installation. From Microsoft NT, install Ubuntu when it is not already present:

wsl --install -d Ubuntu
wsl --list --verbose

Restart Microsoft NT if requested, open Ubuntu, and complete its one-time username setup. Current WSL includes WSLg, so a separate X11 server is not required. In Debian or Ubuntu, install the native compiler and host libraries:

sudo apt update
sudo apt install -y build-essential git pkg-config xdg-utils libgtk-4-dev libwebkitgtk-6.0-dev libjson-glib-dev

Optional native pickers use Zenity or KDialog when one is installed. Opening external URIs uses xdg-open, normally supplied by xdg-utils.

Prepare and build the checkout

For the least cross-platform friction, keep a dedicated Linux checkout inside the WSL filesystem. Do not copy a Microsoft NT node_modules directory into Linux:

git clone https://github.com/TheWizardNexus/ARCANE-OS.git ~/ARCANE-OS
cd ~/ARCANE-OS
cd machine_bundles/arcane-os-machine-bundle
./build-linux.sh
npm run verify:distribution:linux:unsigned-local-test

The bundle launcher prepares the checkout, verifies public lock sources, freshly recreates both locked npm dependency trees, compiles the GTK/WebKitGTK hosts, creates the deterministic 22-app portable source, publishes the verified Linux catalog projection, and binds all of it into dist/linux. If internet access is unavailable and the repository-local npm cache is complete, run ./build-linux.sh --offline; an incomplete cache fails before compilation. The explicit verifier rechecks the exact release inventory before installation. Keep one commit as the source of truth when using separate Microsoft NT and WSL checkouts; do not manually merge generated dist/ trees or node_modules.

Open the native Shell

From the machine-bundle directory:

./start-shell.sh --allow-unsigned-local-release

If Arcane OS is already installed at the standard machine path, the equivalent direct command is:

/opt/arcane-os/bin/arcane-shell

From Microsoft NT PowerShell or Command Prompt, the equivalent installed launch is:

wsl.exe -d Ubuntu -- /opt/arcane-os/bin/arcane-shell

Create an Arcane OS (Linux) desktop shortcut with this target:

C:\Windows\System32\wsl.exe -d Ubuntu -- /opt/arcane-os/bin/arcane-shell

Use the exact distribution name from wsl --list --quiet when it is not Ubuntu. The shortcut can use assets/arcane-sigil.ico from the machine bundle and Microsoft NT may offer Pin to taskbar from its context menu. The installed Linux desktop entries are /usr/share/applications/arcane-shell.desktop and /usr/share/applications/arcane-provisioner.desktop, with /usr/share/pixmaps/arcane-os.png as their icon; WSLg should publish them into the Microsoft NT Start menu.

Wait until the Shell has resolved its identity, operating system, host, and application state before taking a screenshot. Use a public-safe username and hostname or crop those fields. Close the Shell window when finished. Do not choose Log out merely to exit a demonstration: that action requests a real logout of the current Linux desktop session.

WSLg rendering and [WARN:COPY MODE]

When the shared Arcane GTK host detects WSLg through WSL2_GUI_APPS_ENABLED=1 and GDK_BACKEND is truly unset, it defaults GTK/WebKitGTK to the WSLg X11 compatibility path before GTK initializes. An explicitly configured GDK_BACKEND, including wayland, is preserved, and ordinary native Linux sessions are unchanged.

If the taskbar title contains [WARN:COPY MODE] and clicking the icon produces no rendered window, Microsoft WSLg started without its normal graphics-redirection path. This label is not an Arcane mode and does not refer to clipboard copying. Save all work in every running WSL distribution, close its GUI applications, and run the following from Windows Terminal:

wsl --shutdown

This command terminates every running WSL distribution, WSLg application, and background service. Reopen Ubuntu and launch Arcane again. Arcane cannot safely restart the WSL virtual machine from inside the affected Linux GUI process.

Open the Provisioner for inspection

./start-provisioner.sh --allow-unsigned-local-release

The Linux Provisioner can report the platform boundary and diagnostic state. An exact verified unsigned-local build launched from a separately authorized, already-root session can install Arcane and perform the experimental standard-account workflow. Automatic privileged brokering remains fail-closed; a regular-user Provisioner cannot install Arcane or change accounts, passwords, or login shells.

Install or repair the verified build

Close the regular-user Provisioner. After separately deciding to authorize this exact verified local build, launch it as root while preserving the WSLg display variables:

sudo -H \
  --preserve-env=DISPLAY,WAYLAND_DISPLAY,XDG_RUNTIME_DIR,PULSE_SERVER,DBUS_SESSION_BUS_ADDRESS,WSL2_GUI_APPS_ENABLED,GDK_BACKEND,XAUTHORITY \
  ./start-provisioner.sh --allow-unsigned-local-release

Arcane itself does not run sudo, PolicyKit, a package manager, or a remote installer. The operator establishes the root process through the distribution's administrator boundary.

Confirm that the Provisioner reports Linux, root scope, and the expected unsigned-local release. Select Check again, review the state, then select the displayed Install Arcane OS or repair action for that verified build. Wait for completion before closing the Provisioner. Under WSLg the installer writes the protected runtime under /opt/arcane-os but does not register a display-manager session or change the boot target.

Return to the normal, unprivileged Ubuntu account and launch the installed Shell:

/opt/arcane-os/bin/arcane-shell

Select Calculator for a simple local application check.

Local AI and Ollama

Missing Ollama does not block base Arcane OS installation on Linux or WSL. Local model requests require an Ollama executable inside WSL and an enabled, active ollama.service or arcane-ollama.service whose service command runs that executable with serve. Microsoft NT-host Ollama alone does not satisfy this Linux service check.

After installing Ollama through an administrator-approved Linux package or verified upstream package, check it before retrying Arcane:

command -v ollama
systemctl is-enabled ollama.service
systemctl is-active ollama.service
curl -fsS http://127.0.0.1:11434/api/version

connect ECONNREFUSED 127.0.0.1:11434 means no reachable service is listening there. Arcane does not automatically install or rewrite the Linux Ollama service.

Dynamic application frames and PDF previews

Linux dynamic applications use an integrity-bound WebKitGTK Web Process Extension instead of the frame-blind UI-process script-message signal. Only a verified packaged main frame receives the native transport. An application declaring web.embed may load declared HTTP(S) frame origins and local blob:/PDF previews; external subframes receive no Arcane Core bridge, and any external top-level navigation is stopped and returned to the verified application URI.

Embedded content must have an accessible name, keyboard-reachable controls and return path outside the frame, plus a text or download fallback when the document cannot be used. The complete Linux WebKitGTK frame-aware bridge contract is maintained in private developer material; public readers can review the repository-access boundary.

Current Linux limits

• Linux account provisioning is experimental, unsigned-local, and already-root only. Follow the Linux user-provisioning guide; automatic elevation, publisher signing, and disposable-host account acceptance remain incomplete.
• The exact 22-app catalog can be verified, listed, and dispatched through the shared host. Application metadata cannot choose an executable, arguments, or environment.
• Declared HTTP(S) frames and local blob:/PDF previews are implemented through the frame-aware extension, but exact Ubuntu compilation/runtime, hostile-frame and process-swap behavior, complete 22-app journeys, and accessibility acceptance remain outstanding. New-window creation remains fail-closed.
• Ollama service installation and machine-service integration require manual Linux administration.
• A configured OpenAI token is written under ${XDG_CONFIG_HOME:-$HOME/.config}/arcane-os/credentials/openai.token; creation requests mode 0600, but Arcane OS does not yet repair permissions on a pre-existing token file. Linux does not use the Microsoft NT DPAPI store.
• Linux local builds are not production-signed release candidates and do not replace clean-machine acceptance.

Use this workflow for development and controlled acceptance, and treat Linux as experimental until its real account, PAM, display-manager, WSLg, accessibility, recovery, and signing gates are complete. Follow the Linux user-provisioning walkthrough for standard-account staging, separate activation, temporary-password handling, native display-manager sign-in, WSLg differences, and shell recovery. The machine bundle's VALIDATION.md records the current 0.8.7 verification status; until native Linux results are explicitly recorded there, it is not native Linux acceptance evidence.