doc_id: linux-support title: “Linux support baseline” language: en source_language: en implementation_status: current document_status: current translation_status: source-only last_verified: 2026-10-15 owners:
Linux has a Desktop preview for x64 and arm64, plus CLI/TUI and persistent Runtime Host paths. The release workflows build unsigned AppImage and Debian packages; they do not build RPM packages. Native Computer Use is unavailable on Linux. A running Electron window or a passing Xvfb smoke does not establish Wayland, accessibility, or native input support.
The IPMC-approved source archive is the Apache release. Desktop installers and npm packages are convenience builds; see the product release checklist and CLI installation guide.
Download the asset for your architecture from a Maka GitHub Release. Keep the version and architecture consistent across the package and any accompanying checksum. Replace <version> in the examples below with the downloaded asset's version.
| Architecture | AppImage | Debian package |
|---|---|---|
| x64 | Maka-<version>-linux-x86_64.AppImage | Maka-<version>-linux-amd64.deb |
| arm64 | Maka-<version>-linux-arm64.AppImage | Maka-<version>-linux-arm64.deb |
Formal release verification writes a matching .sha256 file for each package. When supplied, verify it from the download directory before installing:
sha256sum --check Maka-<version>-linux-x86_64.AppImage.sha256 # Or, for the x64 Debian package: sha256sum --check Maka-<version>-linux-amd64.deb.sha256
Require a successful checksum result. The packages are unsigned; a matching checksum checks the published bytes, not the publisher's identity. Do not assume a nightly asset has the same sidecars as a formal release.
For an AppImage, replace the example filename with the downloaded asset, make it executable, and run it as your ordinary desktop user:
chmod +x Maka-<version>-linux-x86_64.AppImage ./Maka-<version>-linux-x86_64.AppImage
If the AppImage runtime cannot mount its image because FUSE is unavailable, extraction avoids that mount requirement:
./Maka-<version>-linux-x86_64.AppImage --appimage-extract ./squashfs-root/AppRun
For Debian/Ubuntu, install the matching .deb through the package manager, then launch Maka from the desktop application menu:
sudo apt install ./Maka-<version>-linux-amd64.deb
Do not substitute a dpkg-deb -x extraction for installation: it does not perform the package‘s installation steps, including configuring Electron’s sandbox helper. The verification harness checks the deb payload but deliberately does not launch an extracted deb tree.
After launch, configure a real model connection under Settings → Models. Install ripgrep for the Runtime Grep tool and bubblewrap for the managed Linux sandbox. On Debian/Ubuntu:
sudo apt install ripgrep bubblewrap
Use Node.js ^22.19.0 || >=24.0.0; Node 23 is excluded. The npm package is maka-agent, and its public command is maka. The complete CLI currently follows the nightly tag; inspect the CLI guide before selecting another release line.
npm install --global maka-agent@nightly maka --version maka --help cd /path/to/project maka
First-run setup configures model connections. maka run "Summarize this project" executes a non-interactive turn. Linux profile data lives under $XDG_CONFIG_HOME/Maka, or ~/.config/Maka when XDG_CONFIG_HOME is unset. The workspace is workspaces/default beneath that profile. Credentials are local plaintext files protected by the operating-system account and owner-only permissions; see SECURITY.md.
On Linux, maka runtime-host service install uses systemd user services and requires user lingering. From a persistent global CLI installation:
maka runtime-host service install \ --root "$HOME/.maka/runtime-host" \ --project-root "projects=$HOME/Projects" maka runtime-host service status --json
Use the remote Host guide for user-service prerequisites, client credentials, SSH profiles, and experimental direct-peer access. For its one-command npx setup path, select the complete maka-agent@nightly package rather than the placeholder latest line. Unlike service install, runtime-host setup falls back to OpenRC when the systemd user-service preflight fails: openrc_system when run as root, or openrc_user otherwise.
Before uninstalling the global package, remove the service installed above with an explicit expected target. Obtain the values from that installation:
<root-path>: service.config.rootPath in maka runtime-host service status --json.<root-id>: rootId in <root-path>/.maka-storage-root.json.<service-id>: the ID in the Host unit name maka-runtime-host-<service-id>.service, listed by systemctl --user list-unit-files 'maka-runtime-host-*.service'; do not use the update unit.Replace the placeholders with those values, then run:
maka runtime-host service uninstall \ --expected-service-id '<service-id>' \ --expected-root-path '<root-path>' \ --expected-root-id '<root-id>'
Only uninstall the global package after service removal succeeds; service removal preserves workspace data.
detectLinuxSandboxCapability() checks executable /usr/bin/bwrap, advertised --seccomp support, and a real namespace probe. A package being installed is insufficient if the host forbids the required namespaces. See the capability probe and Runtime sandbox ownership. Do not solve a failed probe by disabling the sandbox; diagnose its reported capability failure and host policy.--no-sandbox because hosted runners cannot configure Electron’s SUID helper; those fixture flags are not Desktop installation guidance.maka-cu executor only on macOS. Linux returns no native Computer Use tools. #3891 tracks the Linux AT-SPI/X11 backend and #3896 tracks platform abstraction. Installing accessibility packages does not activate an unimplemented backend.These are the checked-in verification routes, not a claim that every Linux distribution or desktop session has been tested:
| Route | Evidence and boundary |
|---|---|
| CLI package validation | Installed package smoke on Linux x64 / Node 22.19 and 24, and Linux arm64 / Node 24; real Eval on Linux x64 / Node 24 |
| Desktop nightly and release | Native x64 and arm64 packaging and xvfb-run -a npm run verify:linux |
| Linux release verifier | Opens both payloads, checks resource/dependency closure, peer ELF architecture, deb identity and updater marker, and feed digests; launches the extracted AppImage renderer, not an installed deb |
| Verifier regression tests | Cross-platform fixture tests for ELF mismatches, package verification, and feed integrity; not a Linux installation smoke |
| Main CI | Bubblewrap namespace preparation, Runtime Linux sandbox smoke, and selected Desktop E2E under Xvfb |
| Linux sandbox tests, command smoke, and filesystem-worker smoke | Policy coverage plus actual Linux-only execution paths; Linux-only cases cannot establish sandbox behavior when skipped on another OS |
Install a supported Node version, the root packageManager version of npm (currently 11.19.0), Git, and ripgrep. Install the system libraries required by Electron on your distribution; headless renderer tests also need Xvfb. Install dependencies at the repository root:
git clone https://github.com/apache/maka.git cd maka npm ci npm run dev
npm run dev builds the workspace libraries and launches Desktop with renderer HMR. For independent data per checkout, use npm run dev:worktree; see development profiles. Direct Peer/Peer Mesh development additionally needs Rust stable 1.98 or newer and a platform linker. Released packages already carry their native peer and do not require a Rust toolchain.
For a full build and focused checks:
npm run build npm --workspace @maka/runtime run test:dist node --test scripts/verify-linux-harness.test.mjs
Linux packaging must run on the architecture being packaged; the packaging script rejects cross-platform or mismatched-architecture hosts. See CONTRIBUTING.md for the remaining checks before submitting a PR.