Skip to content

Support Arch Linux (pacman) installs in install.sh via existing release tarballs #2123

Description

@dt-lindberg

Problem Statement

install.sh only knows how to install on Linux via dpkg (Debian/Ubuntu) and rpm (Fedora/RHEL/openSUSE).
Arch Linux uses pacman and has neither natively, so curl -LsSf .../install.sh | sh has no install path at all on Arch or other pacman-based distros.

Proposed Design

Add a third Linux install path, install_linux_tarball(), gated specifically on has_cmd pacman inside linux_package_method() (might work for other package managers as well, but I can only confirm for Arch).

The new path consumes artifacts the release pipeline (.github/workflows/release-tag.yml) already builds, checksums, and publishes on every release, but that install.sh doesn't use today:

  • openshell-<arch>-unknown-linux-musl.tar.gz - the CLI, statically linked against musl, built with --features bundled-z3 (no runtime Z3 dependency).
  • openshell-gateway-<arch>-unknown-linux-gnu.tar.gz - the gateway, also bundled-z3 (CI asserts via ldd that it does not depend on libz3), with a glibc >= 2.28 floor verified by tasks/scripts/verify-glibc-symbols.sh.

Flow, mirroring install_linux_rpm()'s existing shape:

  1. Download both checksum manifests (openshell-checksums-sha256.txt and openshell-gateway-checksums-sha256.txt - these are genuinely separate artifacts produced by separate steps in the release workflow).
  2. find_tarball_asset(checksums, arch, package) discovers the exact filename, matching find_rpm_asset()'s signature rather than taking a pre-built filename.
  3. Loop over file|checksums pairs to download and verify both the CLI and gateway tarballs (mirrors the existing for _package_file in ... loop in install_linux_rpm()).
  4. Fetch the systemd user unit (deploy/deb/openshell-gateway.service) directly from the tagged commit on raw.githubusercontent.com, since a curl | sh install has no repo checkout to read it from, and publishing would require untestable CI changes.
  5. tar -xzf + as_root install inline (without helper function) - unlike install_deb_package/install_rpm_packages, which exist specifically to branch over competing front-ends (apt vs dpkg; dnf vs yum vs zypper vs rpm), there's no equivalent choice for a plain tarball, so a wrapper is redundant.

What this supports: Arch Linux and pacman-based derivatives, any architecture the release pipeline already publishes tarballs for.

What this does not support: distros without dpkg, rpm, or Gentoo, Slackware) — these continue to hit the existing hard error, unvalidated and out of scope for this change. Also out of scope: registering the package with pacman's own database (see Alternatives).

Alternatives Considered

  1. Trick detection into the dpkg path (pacman -S dpkg then dpkg -i openshell.deb). Gets as far as downloading the .deb, but fails on Pre-Depend s: init-system-helpers (>= 1.54~), a Debian-only meta-packagedpkg trigger scripts - it doesn't exist and can't be installed on Arch.
  2. Force past the dependency check (dpkg --force-depends -i), when my Claude agent suggested this I decided to explore better options (what this proposed feature has become). Claude wanted to manually download/checksum the .deb, then replicate whatever install.sh normally does. Works, but it's forcing a foreign distro's package manager to bypass its own dependency checks on a system it was never built for - fragile.
  3. Build from source. Proved viable by hand (cargo build --release -p openshell-cli -p openshell-server, skipping openshell-driver-vm since the Docker driver ships compiled directly into openshell-gateway). Rejected as the shipped fix because it takes ~10 minutes per install versus seconds for downloading the already-published tarballs, there's just no reason to waste compute doing this.
  4. AUR package (yay -S openshell, a real PKGBUILD). This is the more "native" long-term answer for Arch users and would integrate with pacman -Q/-R/updates, unlike a tarball installed outside pacman's database. Not proposed here because it's a separate artifact living outside this repo on, needing its own ongoing maintenance loop. Someone could investigate this if interested.

Agent Investigation

Validated end to end on a real Arch Linux machine:

  • Removed the earlier dpkg workaround package (pacman -R dpkg) to restore a genuine Arch state before testing.
  • Ran the modified install.sh against the live v0.0.74 GitHub release. It resolved the tarball path via the new pacman detection, downloaded and checksum-verified both tarballs, fetched the unit file from the tag, installed everything, and enabled/started the gateway under systemctl --user.
  • Hit the pre-existing "breaking upgrade" guard, because it detected the repo's dev wrapper script (scripts/bin/openshell) on PATH and read it as a prior install. Confirmed there was no real prior state (~/.config/openshell didn't exist, no systemd unit existed yet) before bypassing with OPENSHELL_ACK_BREAKING_UPGRADE=1 - a false positive from the dev environment (mise's [env] _.path puts scripts/bin first inside the repo checkout), not a defect in the new path, and not something that affects real users installing from outside a repo checkout.
  • The gateway came up correctly and connected to the Docker driver. openshell status reported Connected, version 0.0.74.

Known follow-ups not covered by this proposal:

  • No CI coverage yet for the new path - test-release-canary should grow an Arch container job exercising it.
  • Install docs (docs/) don't mention the tarball path yet.
  • An AUR package remains a separate, unimplemented follow-up (see Alternatives above).

I have a working, validated diff to install.sh for this already. Happy to open a PR if this is interesting.

Checklist

  • I've reviewed existing issues and the architecture docs
  • This is a design proposal, not a "please build this" request

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions