feat: add support for Nix via a flake

[octplane]

Providing a flake would allow Nix users to checkout the codebase and immediately be able to build and iterate on the application with minimal setup.

Writing that flake is pretty straightforward and I think it would also be a good basis to provide swamp via the usual Nix Package distribution system

I, or any agent, can provide the code if you want.

And thanks for swamp!

[stack72]

Hi @octplane

Thanks for opening the issue here - we don't plan to add things like devcontainers or nix flakes this early in the project for checking out and developing. But that being said, we 100% will ensure that there's a nix package available to provide swamp for installation

Paul

[keeb]

Implementation Plan: Nix Flake for Swamp

Context

Swamp compiles to a self-contained ~109MB ELF binary via deno compile. The binary embeds V8, the Deno runtime, all TS/JS deps, and skill files. It dynamically links only against glibc + libgcc (no exotic deps). The existing release workflow (.github/workflows/release.yml) already builds binaries for linux-x86_64, linux-aarch64, darwin-x86_64, darwin-aarch64, and windows-x86_64, uploads them to GitHub Releases with checksums, and uses CalVer versioning (YYYYMMDD.HHMMSS.0-sha.HASH).

Approach: Nix Flake with Pre-built Binaries

Add a flake.nix to the repo. Users install with nix profile install github:systeminit/swamp or use it in their NixOS/home-manager configs.

The flake fetches pre-built binaries from GitHub Releases (the same ones the release workflow already produces) and patches them with autoPatchelfHook to fix the dynamic linker paths for Nix.

Building from source with Deno inside the Nix sandbox is significantly more complex (no network access → need to pre-populate Deno's module cache via fixed-output derivation, no official buildDenoModule helper exists) and isn't worth it unless we want to submit to nixpkgs upstream.

Files to Create/Modify

File	Purpose
flake.nix	Nix flake defining the package for linux + darwin, x86_64 + aarch64
flake.lock	Auto-generated by nix flake lock
.github/workflows/release.yml	Add a job that updates flake hashes after release

flake.nix Structure

{
  description = "swamp - AI Native Automation CLI";

  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  outputs = { self, nixpkgs }:
    let
      version = "YYYYMMDD.HHMMSS.0-sha.HASH";  # Updated by CI

      # SHA256 hashes for each platform binary (updated by CI)
      hashes = {
        x86_64-linux = "sha256-AAAA...";
        aarch64-linux = "sha256-BBBB...";
        x86_64-darwin = "sha256-CCCC...";
        aarch64-darwin = "sha256-DDDD...";
      };

      supportedSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;

      binaryName = system: {
        "x86_64-linux" = "swamp-linux-x86_64";
        "aarch64-linux" = "swamp-linux-aarch64";
        "x86_64-darwin" = "swamp-darwin-x86_64";
        "aarch64-darwin" = "swamp-darwin-aarch64";
      }.${system};

    in {
      packages = forAllSystems (system:
        let pkgs = nixpkgs.legacyPackages.${system};
        in {
          default = pkgs.stdenv.mkDerivation {
            pname = "swamp";
            inherit version;
            src = pkgs.fetchurl {
              url = "https://github.com/systeminit/swamp/releases/download/v${version}/${binaryName system}";
              sha256 = hashes.${system};
            };
            nativeBuildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.autoPatchelfHook ];
            buildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.glibc pkgs.gcc.lib ];
            dontUnpack = true;
            installPhase = ''
              install -Dm755 $src $out/bin/swamp
            '';
            meta = with pkgs.lib; {
              description = "AI Native Automation CLI";
              homepage = "https://github.com/systeminit/swamp";
              license = licenses.agpl3Plus;
              platforms = supportedSystems;
              mainProgram = "swamp";
            };
          };
        });
    };
}

CI Integration

Add a job to the release workflow that runs after the release is created:

1. Fetches the published binaries and computes their nix hash (SRI format)
2. Updates flake.nix with the new version and hashes via sed
3. Commits and pushes the updated flake back to main

  update-flake:
    name: Update Nix Flake
    needs: release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: main
      - uses: cachix/install-nix-action@v30
      - name: Update flake with new version and hashes
        env:
          VERSION: ${{ needs.release.outputs.version }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REPO="${{ github.repository }}"
          BASE="https://github.com/${REPO}/releases/download/v${VERSION}"
          for pair in \
            "x86_64-linux:swamp-linux-x86_64" \
            "aarch64-linux:swamp-linux-aarch64" \
            "x86_64-darwin:swamp-darwin-x86_64" \
            "aarch64-darwin:swamp-darwin-aarch64"; do
            sys="${pair%%:*}"
            bin="${pair##*:}"
            curl -fsSL -o "/tmp/${bin}" "${BASE}/${bin}"
            hash=$(nix hash file --sri "/tmp/${bin}")
            sed -i "s|${sys}\" = \"sha256-.*\"|${sys}\" = \"${hash}\"|" flake.nix
          done
          sed -i "s|version = \".*\"|version = \"${VERSION}\"|" flake.nix
          nix flake lock --update-input nixpkgs
      - name: Commit updated flake
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add flake.nix flake.lock
          git commit -m "nix: update flake to v${VERSION}"
          git push

The release job needs to output the version:

  release:
    outputs:
      version: ${{ steps.version.outputs.version }}

Caveats

• Flake lags by one commit — After a release, the flake update commit follows. This is the standard pattern.
• Self-update won't work — swamp update can't write to the Nix store. Users update via nix profile upgrade.
• macOS hashes on Linux CI — nix hash file just hashes bytes, so computing darwin hashes on a Linux runner works fine.
• Optional runtime deps — git and tar are used at runtime but aren't bundled. Nix users are expected to have them.

[keeb]

I added that for later when we come back to it.