Claude Cowork on Linux: running the macOS-only preview without a VM
Run Claude Desktop’s Cowork mode natively on Linux — no macOS or VM required
At a glance
- What is it?
- johnzfitch/claude-cowork-linux stubs out the macOS-native modules in Claude Desktop so Cowork mode runs on Linux x86_64. It is an unofficial research preview that depends on a specific Claude Desktop build.
- Who is it for?
- Adopt it if you are on Linux x86_64, already pay for Claude Pro or higher, and want Cowork's folder-scoped file work without a macOS machine or a VM. Skip it if you need Windows, an untested distro, or a supported product with a stability guarantee, since the README calls this an unofficial research preview that may break when Claude Desktop updates.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What claude-cowork-linux actually solves
Cowork is a Claude Desktop build that operates inside one folder you point it at. It reads, writes and organizes files there while it works through a plan. In Anthropic's packaging it is a macOS-only preview, and the macOS build leans on a sandboxed Linux VM underneath. So the joke writes itself: the feature already runs Linux, just not the Linux you are sitting at.
This repository removes that dependency. According to the README, it reverse-engineers and stubs the macOS-native pieces so Cowork runs directly on Linux x86_64, with no VM and no macOS host. The audience is narrow and obvious: Linux desktop users who already hold a Claude Pro subscription or higher, who want the folder-scoped agent behaviour, and who are unwilling to keep a Mac or a virtual machine around to get it. If you only use Claude Code in a terminal, this is not aimed at you.
Stubs, path translation and a spoofed platform header
The mechanism is four moves, and the README lays them out plainly. First, stubbing: the macOS-only native modules @ant/claude-swift and @ant/claude-native are replaced with JavaScript implementations. Second, direct execution: the Claude Code binary runs as-is, because the host is already Linux. Third, path translation: VM paths are converted to host paths, so Cowork resolves the files you actually pointed it at rather than paths that only exist inside a sandbox image. Fourth, platform spoofing: the client sends macOS headers so the server enables the feature.
That last step is the one worth pausing on. The feature gate is server-side and keyed on what the client claims to be. Nothing in the README suggests a supported configuration flag; it is a header. When Anthropic changes how that gate works, the port has to change with it, which is exactly why the project ships a COMPAT.md tested-versions matrix and pins a Claude release. The path translation layer is the other piece with real surface area: any place the upstream code assumes a VM root is a place the translation can be wrong, and the test suite reflects that, with the README citing 571 test cases across 36 test files covering IPC, path translation, security and session persistence, plus four shell suites for the patch passes, compat pins, launcher stub sync and install-script static analysis.
Installing claude-cowork-linux and running it once
The recommended path is the installer script. It prompts before downloading the Claude Desktop asar so you can confirm the version it is about to pull. Clone, run the installer, launch.
git clone https://github.com/johnzfitch/claude-cowork-linux.git
cd claude-cowork-linux
./install.sh # prompts before downloading the Claude Desktop asar
claude-desktopOn Arch Linux there is an AUR package, which skips the clone entirely.
yay -S claude-cowork-linuxIf you already have a DMG, you can hand it over instead of letting the installer fetch one, either as a positional argument or through an environment variable.
./install.sh ~/Downloads/Claude-*.dmg
# or
CLAUDE_ARCHIVE=~/Downloads/Claude-1.6259.1.dmg ./install.shAfter install, validate the environment before you trust it. The README points at a doctor mode on both the installer and the launcher.
./install.sh --doctorA piped install is non-interactive, and the script refuses to download without an explicit confirmation flag; the README shows --force for that case. The dependencies are not exotic but they are not zero either: Node.js 18+ and npm, Electron, asar via npm install -g @electron/asar, p7zip (7zip on openSUSE), bubblewrap for sandbox isolation, and optionally Python 3.11+ for enable-cowork.py. The installer itself uses Node.js to download DMGs. Fedora users may additionally need p7zip-plugins for DMG extraction.
The /sessions symlink and other things that break
The install needs sudo once, to create a root symlink at /sessions pointing into your home directory. The README gives the manual equivalent for distros that restrict root symlinks: sudo ln -s "$HOME/.config/Claude/local-agent-mode-sessions/sessions" /sessions. That is an unusual requirement for a desktop application, and it is the first thing to check if sessions fail to appear.
Credentials are the second soft spot. Without a running SecretService provider such as gnome-keyring, KDE Wallet or KeePassXC, the launcher falls back to --password-store=basic, which means credentials land on disk rather than in a keyring. The README states this fallback rather than warning against it, but the difference matters if you share the machine.
Global hotkeys are the third. Wayland compositors that do not implement the GlobalShortcuts portal, GNOME being the named example, get no global hotkey support, and the README tells you to set a custom shortcut in your desktop environment settings instead. NixOS is listed as untested, with a note that Electron plus bwrap sandboxing may need extra configuration. And the overarching caveat sits in the status section: this is an unofficial research preview that may break when Claude Desktop updates.
NixOS and the Nix flake path
NixOS cannot use install.sh directly, and the README explains why in concrete terms: the package-manager branch runs imperative nix-env -iA, and the npm electron it would otherwise install is a prebuilt ELF that will not run on NixOS. The flake builds the app against electron_41 from nixpkgs instead.
nix run github:johnzfitch/claude-cowork-linuxThe derivation extracts and patches the pinned Claude release at build time, then a wrapper mirrors the tree into $XDG_DATA_HOME/claude-cowork-linux, which is writable, and runs the upstream launch.sh with dependencies on PATH. The pinned version lives in nix/package.nix, and claudeVersion, claudeUrl and claudeHash can be overridden to track a different release. A nix develop shell is also provided with everything install.sh needs, for people who prefer the manual installer flow. Note the trade-off: on NixOS you are not following the same code path as Arch users, so a bug report from one does not necessarily reproduce on the other.
When this is the wrong tool
There is no Windows story here, and the README does not pretend otherwise. If your team is on Windows, this project has nothing for you.
More subtly, if you need a supported product with a stability guarantee, this is the wrong layer. It depends on a pinned Claude Desktop release, and the tested-versions matrix in COMPAT.md exists precisely because that pin moves. An upstream change to the platform gate, the native module names, or the VM path assumptions can break the port until a new release lands. The recent release history shows the pattern: v5.0.0 in May 2026, v5.1.0 in June, v5.2.0 in July, with the last push to the repository on 2026-09-04. That is a project tracking someone else's release cadence, not setting its own.
It is also the wrong tool if you are not on x86_64. The README targets Linux x86_64 and says so in the requirements, so ARM machines are out of scope. And if you have no Claude Pro or higher subscription, the port will not get you Cowork access; the account requirement is upstream of everything this repository does.
How it compares to running Cowork in a VM
The obvious alternative is the arrangement Anthropic already ships: run the macOS build, or run Cowork inside the sandboxed Linux VM it is backed by, and leave the host alone. That approach is boring and it works, because you are not translating paths or spoofing headers. The cost is the VM itself: another system to install, keep updated and give resources to, plus whatever friction comes with a macOS host if you do not own one.
This project inverts that trade. You give up the sandbox boundary between the agent and your real filesystem, and in exchange you get direct access to the folder you pointed Cowork at, with no VM layer. The README frames the direct execution as a benefit, and on a Linux host it genuinely is simpler. But the isolation story changes: bubblewrap is listed as a requirement for sandbox isolation, which suggests the project is aware of the gap and addresses it at the launcher level rather than inheriting it from a VM. If your threat model depends on the agent never touching the host directly, the VM arrangement is the more conservative choice, and this port is not a drop-in replacement for it.
Licence and the cost of keeping up
The repository is MIT licensed, and the LICENSE file sits at the top level alongside PKGBUILD, flake.nix and the stubs directory. MIT covers the code in this repository. It does not cover Claude Desktop, the DMG the installer downloads, or the Claude Code binary it runs; those come from Anthropic under their own terms, and the README describes the app as an unofficial research preview rather than anything Anthropic supports. Nothing here is legal advice, but the distinction between the MIT-licensed wrapper and the proprietary application it patches is the one that matters if you are evaluating this for a workplace.
Upgrade cost is the recurring expense. The project pins a Claude release, publishes a tested-versions matrix in COMPAT.md, and ships compat pins among the shell test suites. When Claude Desktop moves, someone has to re-verify the stubs, the path translation and the platform headers before the port follows. For an individual on Arch who updates deliberately, that is a manageable chore. For a fleet, it means every Claude Desktop release is a potential support ticket, and the README offers no rollback procedure, so the version you install is the version you are on until a new release of this project lands.
Editorial conclusion
Adopt it if you are on Linux x86_64, already pay for Claude Pro or higher, and want Cowork's folder-scoped file work without a macOS machine or a VM. Skip it if you need Windows, an untested distro, or a supported product with a stability guarantee, since the README calls this an unofficial research preview that may break when Claude Desktop updates. Before committing, run ./install.sh --doctor, then confirm the Claude Desktop version in COMPAT.md matches the one the installer would download.
Frequently asked questions
Is there a Claude Cowork for Linux?
Yes, unofficially. johnzfitch/claude-cowork-linux reverse-engineers and stubs the macOS-native modules so Cowork runs directly on Linux x86_64 with no VM and no macOS host. The README describes it as an unofficial research preview that may break when Claude Desktop updates.
Is Claude Cowork a VM?
Upstream, Cowork is a macOS-only preview backed by a sandboxed Linux VM. This project removes that VM on Linux by running the Claude Code binary directly, since the host is already Linux, and translating VM paths to host paths.
Do I need Claude Cowork?
The README frames Cowork as operating inside a folder you point it at, reading, writing and organizing files there while it runs a plan. If that folder-scoped workflow is not something you want, the port adds nothing, and it requires a Claude Pro or higher subscription regardless.
What is the claude cowork linux alternative to running a VM?
The alternative this project offers is direct execution on the host: no VM, no macOS, with bubblewrap listed as a requirement for sandbox isolation and the /sessions root symlink created once during install. The trade is that you lose the VM boundary between the agent and your real filesystem.
What have you used Claude Cowork for?
The README describes Cowork as reading, writing and organizing files inside a folder you point it at while it runs a plan. It does not list specific use cases beyond that folder-scoped file work.
Community notes