Claude Cowork on Linux

No macOS, no VM required.

Quick Start · How It Works · Manual Setup · Troubleshooting

Overview

Claude Cowork is a special Claude Desktop build that works inside a folder you point it at—it reads, writes, and organizes files there while it runs a plan. Cowork is currently a macOS-only preview backed by a sandboxed Linux VM; this repo reverse-engineers and stubs the macOS-native pieces so Cowork can run directly on Linux (x86_64)—no VM and no macOS required. The stub translates VM paths to host paths so Cowork points at the right files on Linux.

How it works:

Step	Description
Stubbing	Replace macOS-only native modules (@ant/claude-swift, @ant/claude-native) with JavaScript
Direct Execution	Run the Claude Code binary directly (no VM needed—we're already on Linux!)
Path Translation	Convert VM paths to host paths transparently
Platform Spoofing	Send macOS headers so the server enables the feature

Status

• Unofficial research preview: This is reverse-engineered and may break when Claude Desktop updates.
• Linux support: Currently targets Linux x86_64. Wayland: auto-detected via $WAYLAND_DISPLAY / $XDG_SESSION_TYPE (Ozone backend).
• Access: Requires a Claude account. The installer auto-downloads the Claude Desktop DMG; no macOS machine needed.
• Tests: 215+ test cases across 18 test files validating IPC, path translation, security, and session persistence.

Compatibility

Known caveats:

• Wayland compositors that don't implement the GlobalShortcuts portal (GNOME) won't have global hotkey support -- set a custom shortcut in your DE settings instead.
• If gnome-keyring or another SecretService provider isn't running, the launcher falls back to --password-store=basic (credentials stored on disk, not in a keyring).
• The /sessions root symlink requires sudo once during install. If your distro restricts root symlinks differently, point it manually: sudo ln -s "$HOME/.config/Claude/local-agent-mode-sessions/sessions" /sessions.

Run ./install.sh --doctor (or claude-desktop --doctor) after install to validate your environment.

Requirements

• Linux x86_64 (tested on Arch Linux, kernel 6.18.13)
• Node.js 18+ / npm
• Electron (system package or npm global)
• asar (npm install -g @electron/asar)
• p7zip (to extract the macOS DMG; openSUSE uses 7zip instead)
• bubblewrap (sandbox isolation)
• Python 3.11+ (optional, for enable-cowork.py patching — the installer uses Node.js to download DMGs)
• Claude Pro (or higher) subscription for Cowork access
• Secret service provider (optional) -- gnome-keyring, KDE Wallet, or KeePassXC for secure credential storage. Without one, the launcher falls back to --password-store=basic.

Quick Start

Method 1: install.sh (recommended)

git clone https://github.com/johnzfitch/claude-cowork-linux.git
cd claude-cowork-linux
./install.sh          # auto-downloads the latest DMG via Node.js
claude-desktop

Method 2: AUR (Arch Linux)

yay -S claude-cowork-linux       # auto-downloads the latest DMG

Method 3: curl pipe

bash <(curl -fsSL https://raw.githubusercontent.com/johnzfitch/claude-cowork-linux/master/install.sh)

The installer automatically downloads the latest Claude Desktop DMG using Node.js (scripts/fetch-dmg.js). You can also provide a DMG manually:

./install.sh ~/Downloads/Claude-*.dmg
# or
CLAUDE_DMG=~/Downloads/Claude-1.1.4010.dmg ./install.sh

[!IMPORTANT] This repo does not include Anthropic's proprietary code. The installer downloads it directly from Anthropic's CDN.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Claude Desktop (Electron)                   │
├─────────────────────────────────────────────────────────────────┤
│  @ant/claude-swift (STUBBED)                                    │
│  ├── vm.setEventCallbacks() → Register process event handlers   │
│  ├── vm.startVM() → No-op (we're already on Linux)              │
│  ├── vm.spawn() → Delegates to session orchestrator             │
│  ├── vm.kill() → Kills spawned processes                        │
│  └── vm.writeStdin() → Writes to process stdin                  │
├─────────────────────────────────────────────────────────────────┤
│  @ant/claude-native (STUBBED)                                   │
│  ├── AuthRequest → Opens system browser (xdg-open)              │
│  └── Platform helpers → Minimal compatibility shims             │
├─────────────────────────────────────────────────────────────────┤
│  stubs/cowork/ — Orchestration Layer (15 modules)               │
│  ├── session_orchestrator.js   → Coordinates spawn lifecycle   │
│  ├── asar_adapter.js            → Asar IPC API compatibility    │
│  ├── process_manager.js         → Process lifecycle & I/O       │
│  ├── resume_coordinator.js      → Session resume logic          │
│  ├── sessions_api.js            → Session CRUD operations       │
│  ├── session_store.js           → In-memory session state       │
│  ├── transcript_store.js        → Transcript persistence        │
│  ├── file_registry.js           → Working directory tracking    │
│  ├── file_watch_manager.js      → File change detection         │
│  ├── stream_protocol.js         → JSON-RPC stream parsing       │
│  ├── credential_classifier.js   → Token leak prevention         │
│  ├── eipc_channel.js            → EIPC message protocol         │
│  ├── ipc_tap.js                 → IPC channel discovery         │
│  ├── dirs.js                    → XDG directory resolution      │
│  └── file_identity.js           → Path normalization            │
├─────────────────────────────────────────────────────────────────┤
│  Claude Code Binary                                             │
│  └── Resolved from ~/.local/bin, mise/asdf shims, PATH, etc.   │
│      (launch.sh replaces macOS Mach-O binary with Linux symlink)│
└─────────────────────────────────────────────────────────────────┘

Path Translation

The stub translates VM paths to host paths:

Mount Symlinks

When you select a folder in Cowork, the stub creates symlinks to make it accessible at the expected VM path:

~/.config/Claude/local-agent-mode-sessions/sessions/<session-name>/mnt/
├── <folder>  → /home/user/path/to/selected/folder (symlink)
├── .claude   → ~/.config/Claude/local-agent-mode-sessions/.../session/.claude (symlink)
├── .skills   → ~/.config/Claude/local-agent-mode-sessions/skills-plugin/... (symlink)
└── uploads/  (directory for file uploads)

The additionalMounts parameter from Claude Desktop provides the mapping between mount names and host paths.

[!NOTE] The Claude Code binary expects /sessions to exist. install.sh creates /sessions as a symlink into ~/.config/Claude/local-agent-mode-sessions/sessions (requires sudo once) so you don't need a world-writable root directory.

How It Works

The app sends these headers to Anthropic's servers:

'Anthropic-Client-OS-Platform': 'darwin'
'Anthropic-Client-OS-Version': '14.0'

This makes the server think we're on macOS 14 (Sonoma), enabling Cowork features.

The platform-gate function (minified name changes per build — xPt() in v1.1.3963, wj() in older builds) checks if Cowork is supported. enable-cowork.py finds it automatically and replaces it to unconditionally return `