Skip to content

BUILDING.md

Latest commit

 

History

History
143 lines (101 loc) · 4.68 KB

BUILDING.md

File metadata and controls

143 lines (101 loc) · 4.68 KB

< Back to README

Building from Source

Prerequisites

  • Linux distribution (Debian/Ubuntu, Fedora/RHEL, or other)
  • Git
  • Basic build tools (automatically installed by the script)

Build Instructions

# Clone the repository
git clone https://github.com/aaddrick/claude-desktop-debian.git
cd claude-desktop-debian

# Build with auto-detected format (based on your distro)
./build.sh

# Or specify a format explicitly:
./build.sh --build deb       # Debian/Ubuntu .deb package
./build.sh --build rpm       # Fedora/RHEL .rpm package
./build.sh --build appimage  # Distribution-agnostic AppImage
./build.sh --build nix       # Nix derivation (patch only, used by flake)

# Build with custom options
./build.sh --build deb --clean no  # Keep intermediate files

# Build using a locally downloaded installer
# (useful when the bundled download URL is outdated)
./build.sh --exe /path/to/Claude-Setup.exe

The build script automatically detects your distribution and selects the appropriate package format:

Distribution Default Format Package Manager
Debian, Ubuntu, Mint .deb apt
Fedora, RHEL, CentOS .rpm dnf
NixOS nix nix
Arch Linux .AppImage (via AUR) yay/paru
Other .AppImage -

Installing the Built Package

For .deb packages (Debian/Ubuntu)

sudo apt install ./claude-desktop_VERSION_ARCHITECTURE.deb
# Or: sudo dpkg -i ./claude-desktop_VERSION_ARCHITECTURE.deb

# If you encounter dependency issues:
sudo apt --fix-broken install

For .rpm packages (Fedora/RHEL)

sudo dnf install ./claude-desktop-VERSION-1.ARCH.rpm
# Or: sudo rpm -i ./claude-desktop-VERSION-1.ARCH.rpm

For AppImages

# Make executable
chmod +x ./claude-desktop-*.AppImage

# Run directly
./claude-desktop-*.AppImage

# Or integrate with your system using Gear Lever

Note: AppImage login requires proper desktop integration. Use Gear Lever or manually install the provided .desktop file to ~/.local/share/applications/.

Automatic Updates: AppImages downloaded from GitHub releases include embedded update information and work seamlessly with Gear Lever for automatic updates. Locally-built AppImages can be manually configured for updates in Gear Lever.

For NixOS

The repository includes a Nix flake. Build and install directly:

# Build the package
nix build .#claude-desktop

# Build the FHS-wrapped variant (for MCP server support)
nix build .#claude-desktop-fhs

# Run without installing
nix run .#claude-desktop

For declarative NixOS installation, see the README.

Technical Details

How It Works

Claude Desktop is an Electron application distributed for Windows. This project:

  1. Downloads the official Windows installer
  2. Extracts application resources
  3. Replaces Windows-specific native modules with Linux-compatible implementations
  4. Repackages as one of:
    • Debian package (.deb): For Debian, Ubuntu, and derivatives
    • RPM package (.rpm): For Fedora, RHEL, CentOS, and derivatives
    • AppImage: Portable, distribution-agnostic executable
    • Nix package: For NixOS, via the included flake

Build Process

The build script (build.sh) handles:

  • Dependency checking and installation
  • Resource extraction from Windows installer
  • Icon processing for Linux desktop standards
  • Native module replacement
  • Package generation based on selected format

Automated Version Detection

A GitHub Actions workflow runs daily to check for new Claude Desktop releases:

  1. Uses Playwright to resolve Anthropic's Cloudflare-protected download redirects
  2. Compares resolved URLs with those in scripts/setup/detect-host.sh
  3. If a new version is detected:
    • Updates scripts/setup/detect-host.sh with new download URLs
    • Updates nix/claude-desktop.nix with new version, URLs, and SRI hashes
    • Creates a new release tag
    • Triggers automated builds for both architectures

This ensures the repository stays up-to-date with official releases automatically.

Manual Updates

If you need to build with a specific version before the automation catches it:

  1. Use a local installer: Download the latest installer from claude.ai/download and build with:

    ./build.sh --exe /path/to/Claude-Setup.exe

  2. Update the URL: Modify the claude_download_url assignments in scripts/setup/detect-host.sh (inside the detect_architecture case statement).