ci: migrate GitHub Actions jobs to self-hosted Mac mini runners

.github/scripts/codecov-upload.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Pin-download the official macOS Codecov CLI and upload one lcov file.
+# codecov-action requires host `gpg` to verify its downloaded CLI; these Mac minis
+# do not have gpg. SHA256 of codecovcli_macos v11.3.1 matches cli.codecov.io.
+set -eu
+
+FILE=$1
+VERSION=v11.3.1
+EXPECTED_SHA256=ffb2b821551076b69d3267508b2d5dc10925c821c436521f2216f5ead62cb138
+DEST="$RUNNER_TEMP/codecov"
+BIN="$DEST/codecov"
+
+mkdir -p "$DEST"
+curl -fsSL "https://github.com/codecov/codecov-cli/releases/download/${VERSION}/codecovcli_macos" \
+  -o "$BIN"
+actual=$(shasum -a 256 "$BIN")
+actual=${actual%% *}
+if [ "$actual" != "$EXPECTED_SHA256" ]; then
+  echo "codecov CLI checksum mismatch: got $actual want $EXPECTED_SHA256" >&2
+  exit 1
+fi
+chmod +x "$BIN"
+
+"$BIN" upload-coverage \
+  -t "$CODECOV_TOKEN" \
+  --file "$FILE" \
+  --disable-search \
+  --fail-on-error \
+  --git-service github

.github/scripts/setup-bun-isolated.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# Install Bun canary into $RUNNER_TEMP so parallel jobs on the same Mac mini
+# do not overwrite a shared ~/.bun (oven-sh/setup-bun's default). The perf
+# gate records Bun.version per revision; a mid-job overwrite looks like an
+# environment mismatch and fails the compare.
+set -eu
+
+DEST="$RUNNER_TEMP/bun"
+mkdir -p "$DEST"
+curl -fsSL "https://github.com/oven-sh/bun/releases/download/canary/bun-darwin-aarch64.zip" \
+  -o "$DEST/bun.zip"
+unzip -o -q "$DEST/bun.zip" -d "$DEST"
+BIN="$DEST/bun-darwin-aarch64/bun"
+if [ ! -f "$BIN" ]; then
+  echo "bun binary missing after extract" >&2
+  exit 1
+fi
+chmod +x "$BIN"
+# The canary zip ships only `bun`. setup-bun also linked `bunx` (same binary).
+ln -sf bun "$(dirname "$BIN")/bunx"
+# Isolate bun's own home (install cache, etc.) from the shared ~/.bun.
+echo "BUN_INSTALL=$DEST/home" >> "$GITHUB_ENV"
+echo "$(dirname "$BIN")" >> "$GITHUB_PATH"
+"$BIN" --revision

.github/workflows/code_quality.yml

@@ -9,14 +9,16 @@ permissions:
 
 jobs:
   quality:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
 
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          # Bun 1.4 (the Rust rewrite) ships only as canary; the `canary` tag moves with each build.
-          bun-version: canary
+      # setup-bun writes ~/.bun, shared across runner instances on one Mac mini.
+      - name: Install Bun canary into runner temp
+        run: sh .github/scripts/setup-bun-isolated.sh
 
       - name: Install dependencies
         run: bun install --frozen-lockfile

.github/workflows/coverage.yml

@@ -1,6 +1,7 @@
 name: Coverage
 
 on:
+  pull_request:
   push:
     branches: [main]
   workflow_dispatch:
@@ -10,14 +11,16 @@ permissions:
 
 jobs:
   coverage:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
 
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          # Match the rest of CI while Bun 1.4 remains canary-only.
-          bun-version: canary
+      # setup-bun writes ~/.bun, shared across runner instances on one Mac mini.
+      - name: Install Bun canary into runner temp
+        run: sh .github/scripts/setup-bun-isolated.sh
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -30,12 +33,13 @@ jobs:
           bun test tests/ --coverage --coverage-reporter=lcov --coverage-dir=coverage
           test -s coverage/lcov.info
           # Bun writes SDK-relative source paths; coverage services need repository-relative paths.
-          sed -i 's|^SF:|SF:packages/hyperliquid/|' coverage/lcov.info
+          # Rewrite via $RUNNER_TEMP: BSD sed has no GNU `sed -i` in-place form.
+          sed 's|^SF:|SF:packages/hyperliquid/|' coverage/lcov.info > "$RUNNER_TEMP/lcov.info"
+          mv "$RUNNER_TEMP/lcov.info" coverage/lcov.info
 
+      # codecov-action requires host `gpg` for CLI integrity. These Mac minis do
+      # not have it; same pinned CLI + SHA256 check as lychee, same upload flags.
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: ./packages/hyperliquid/coverage/lcov.info
-          disable_search: true
-          fail_ci_if_error: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        run: sh .github/scripts/codecov-upload.sh ./packages/hyperliquid/coverage/lcov.info

.github/workflows/docs.yml

@@ -40,19 +40,21 @@ concurrency:
 
 jobs:
   docs:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
     timeout-minutes: 20
     env:
       # Project Pages is served from /<repository>; PR builds use the same paths.
       NEXT_PUBLIC_BASE_PATH: /${{ github.event.repository.name }}
       NEXT_TELEMETRY_DISABLED: "1"
 
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          # Match the rest of CI while Bun 1.4 remains canary-only.
-          bun-version: canary
+      # setup-bun writes ~/.bun, shared across runner instances on one Mac mini.
+      - name: Install Bun canary into runner temp
+        run: sh .github/scripts/setup-bun-isolated.sh
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -72,28 +74,53 @@ jobs:
         working-directory: apps/docs
         run: bun run build
 
+      # `--with-deps` is apt/sudo on Linux. Chromium's macOS deps ship with the OS.
       - name: Install browser for documentation checks
         working-directory: apps/docs
-        run: bunx playwright install --with-deps chromium
+        run: bunx playwright install chromium
 
       - name: Test production documentation interactions
         working-directory: apps/docs
         run: bun run test:browser
 
+      # lychee-action downloads only `*-unknown-linux-gnu` and uses GNU `install -t`.
+      # Same lychee v0.24.2 scan, installed into $RUNNER_TEMP for the Mac mini.
       - name: Check documentation links
-        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2
-        with:
-          args: >-
-            --root-dir .
-            --no-progress
-            --max-retries 3
-            --timeout 20
-            README.md
-            packages/hyperliquid/README.md
-            'apps/docs/content/docs/**/*.md'
-          fail: true
-          failIfEmpty: true
-          token: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -eu
+          LYCHEE_VERSION=v0.24.2
+          ARCHIVE=lychee-aarch64-apple-darwin.tar.gz
+          EXPECTED_SHA256=c9d3740ea2d891854d37116c9fba840f37b6e7c89d330e7db84ac333631c4977
+          DEST="$RUNNER_TEMP/lychee"
+          mkdir -p "$DEST"
+          curl -fsSL "https://github.com/lycheeverse/lychee/releases/download/lychee-${LYCHEE_VERSION}/${ARCHIVE}" \
+            -o "$DEST/$ARCHIVE"
+          actual=$(shasum -a 256 "$DEST/$ARCHIVE")
+          actual=${actual%% *}
+          if [ "$actual" != "$EXPECTED_SHA256" ]; then
+            echo "lychee archive checksum mismatch: got $actual want $EXPECTED_SHA256" >&2
+            exit 1
+          fi
+          tar -xzf "$DEST/$ARCHIVE" -C "$DEST"
+          LYCHEE="$DEST/lychee-aarch64-apple-darwin/lychee"
+          chmod +x "$LYCHEE"
+          report="$RUNNER_TEMP/lychee-out.md"
+          "$LYCHEE" \
+            --root-dir . \
+            --no-progress \
+            --max-retries 3 \
+            --timeout 20 \
+            --format markdown \
+            README.md \
+            packages/hyperliquid/README.md \
+            "apps/docs/content/docs/**/*.md" \
+            | tee "$report"
+          if grep -E 'Total[[:space:]]+\|[[:space:]]+0' "$report" >/dev/null; then
+            echo "No links were found. This usually indicates a configuration error." >&2
+            exit 1
+          fi
 
       - name: Upload GitHub Pages artifact
         if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
@@ -104,7 +131,7 @@ jobs:
   deploy:
     if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
     needs: docs
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
     timeout-minutes: 10
     permissions:
       pages: write
@@ -116,6 +143,9 @@ jobs:
       group: github-pages
       cancel-in-progress: false
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       # Enable Settings > Pages > Source: GitHub Actions before the first deployment.
       # Keeping Pages API calls here lets PR checks run before Pages is enabled.
       - name: Configure GitHub Pages

.github/workflows/perf.yml

@@ -12,9 +12,9 @@ jobs:
   # improve it, never regress it.
   #
   # WHY THIS MEASURES TWICE INSTEAD OF USING THE SDK'S tests/perf/results/baseline.json:
-  # the scenarios measure between 9 ns and 600 µs per unit. A GitHub-hosted runner is several times
-  # slower than a developer machine, so comparing a committed baseline (recorded on whatever machine
-  # last touched it) against a runner would flag nearly every scenario as a regression on every PR.
+  # the scenarios measure between 9 ns and 600 µs per unit. A CI runner (even this Mac mini) is
+  # not the machine that last recorded the committed baseline, so comparing that file against a
+  # runner would flag nearly every scenario as a regression on every PR.
   # The SDK's `.dev/perf/compare.ts` refuses such a comparison outright. So this job measures the base
   # commit and the head commit back to back on the SAME runner and compares those two reports.
   # The committed baseline stays useful for local runs (`bun run perf:gate`) on one machine.
@@ -35,18 +35,22 @@ jobs:
   # changes the workload being compared and is flagged for explicit review, not waved through.
   # If this job flaps, widen the threshold — do not add retries and do not drop the job.
   perf:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
 
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           # The base commit must be reachable so it can be checked out into a second worktree.
           fetch-depth: 0
 
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          # Bun 1.4 (the Rust rewrite) ships only as canary; the `canary` tag moves with each build.
-          bun-version: canary
+      # setup-bun writes ~/.bun, shared across runner instances on one Mac mini.
+      # Parallel canary installs overwrite each other; the perf compare then
+      # sees two Bun versions in one job and refuses the comparison.
+      - name: Install Bun canary into runner temp
+        run: sh .github/scripts/setup-bun-isolated.sh
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -67,6 +71,11 @@ jobs:
             exit 1
           }
           echo "Base: $BASE_REF -> $BASE_SHA"
+          # Self-hosted workspaces persist. A prior job can leave $RUNNER_TEMP/base
+          # registered after the directory was wiped; `worktree add` then fails.
+          git worktree prune
+          git worktree remove --force "$RUNNER_TEMP/base" 2>/dev/null || true
+          rm -rf "$RUNNER_TEMP/base"
           git worktree add "$RUNNER_TEMP/base" "$BASE_SHA"
           # Locate each revision independently: older commits keep the SDK at the repository
           # root, while workspace commits keep the same suite under packages/hyperliquid.

.github/workflows/publish_npm.yml

@@ -6,22 +6,24 @@ on:
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
 
     permissions:
       contents: read
       id-token: write
 
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       # npm publishes via OIDC trusted publishing (no token here), which needs npm >= 11.5.1.
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "24.x"
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          # Bun 1.4 (the Rust rewrite) ships only as canary; the `canary` tag moves with each build.
-          bun-version: canary
+      # setup-bun writes ~/.bun, shared across runner instances on one Mac mini.
+      - name: Install Bun canary into runner temp
+        run: sh .github/scripts/setup-bun-isolated.sh
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -34,15 +36,16 @@ jobs:
         id: tag
         run: |
           # The private workspace root has no release version; the SDK owns the published version.
-          VERSION=$(jq -r .version packages/hyperliquid/package.json)
-          # Extract tag (alpha, beta, rc) from version string if present
-          TAG=$(echo "$VERSION" | sed -n 's/.*-\(alpha\|beta\|rc\).*/\1/p')
-          # If no known tag found but version contains hyphen, use "prerelease"
-          if [[ -z "$TAG" && "$VERSION" == *-* ]]; then
-            TAG="prerelease"
-          fi
-          # Default to "latest" if no tag determined
-          echo "value=${TAG:-latest}" >> "$GITHUB_OUTPUT"
+          # bun instead of jq; case instead of GNU sed `\|` / bash `[[`.
+          VERSION=$(bun -e 'console.log(JSON.parse(await Bun.file("packages/hyperliquid/package.json").text()).version)')
+          case "$VERSION" in
+            *-alpha*) TAG=alpha ;;
+            *-beta*) TAG=beta ;;
+            *-rc*) TAG=rc ;;
+            *-*) TAG=prerelease ;;
+            *) TAG=latest ;;
+          esac
+          echo "value=$TAG" >> "$GITHUB_OUTPUT"
 
       - name: Publish package
         working-directory: ./packages/hyperliquid/dist

.github/workflows/security.yml

@@ -19,6 +19,10 @@ jobs:
       actions: read
       contents: read
       security-events: write
+    # Not migrated to the Mac mini runners. This reusable workflow pins
+    # `runs-on: ubuntu-latest` and a Linux container internally; we cannot set
+    # its runner. See docs/ci-runners.md.
+    #
     # SHA is the v2.3.8 tag target, verified via `gh api repos/google/osv-scanner-action/git/ref/tags/v2.3.8`.
     # The reusable workflow pins its own sub-actions and the osv-scanner container image by SHA internally.
     uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@9a498708959aeaef5ef730655706c5a1df1edbc2 # v2.3.8

.github/workflows/tests_offline.yml

@@ -8,14 +8,16 @@ permissions:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, ARM64]
 
     steps:
+      # Job-level env cannot use the runner context on these Mac minis.
+      - name: Point TMPDIR at runner temp
+        run: echo "TMPDIR=$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
-        with:
-          # Bun 1.4 (the Rust rewrite) ships only as canary; the `canary` tag moves with each build.
-          bun-version: canary
+      # setup-bun writes ~/.bun, shared across runner instances on one Mac mini.
+      - name: Install Bun canary into runner temp
+        run: sh .github/scripts/setup-bun-isolated.sh
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -25,7 +27,7 @@ jobs:
       #
       # Inside the SDK, `bun test tests/ -- --offline` also works: tests/_offline.ts recovers the raw command line
       # because `bun test` does not forward argv to test files. The env var is preferred here because
-      # it needs no such recovery — that path reads /proc/self/cmdline on Linux and is exercised only
-      # in CI, so relying on it would put the least-tested branch on the critical path.
+      # it needs no such recovery — that path reads /proc/self/cmdline on Linux or `ps` on Darwin
+      # and is the least-tested branch, so it stays off the CI critical path.
       - name: bun test (offline)
         run: bun run test:offline