How do I run hk entirely offline.

[dkowis]

With github's stability problems, if it's not behaving properly every time I make a commit, I get blocked with hk failing to operate. That's expensive, and not really suitable for an enterprise either (I'd love to use this at work.)

So, is there a way to do everything offline, so that I don't have to hit github for any of the configs?

[jdx]

Yes. hk itself caches the fully evaluated config under ~/.cache/hk, so an unchanged config normally does not invoke Pkl or contact GitHub on every commit. The remaining problem is a cold/invalidated hk cache (after editing hk.pkl, upgrading hk, clearing the cache, etc.).

Here are two ways to make that case work offline too. I tested both against hk 1.55.0 with HK_CACHE=0 and HTTP(S) pointed at a dead proxy, so the successful validation was not coming from hk's resolved-config cache.

1. Vendor the Pkl package into the repository

Run this once while GitHub is available. It detects the pinned version in hk.pkl, downloads that release package, changes the two package imports to local paths, saves the original as hk.pkl.before-vendoring, and validates the result:

#!/usr/bin/env bash
set -euo pipefail

version="${1:-$(sed -n 's|^amends "package://github.com/jdx/hk/releases/download/v\([^/]*\)/hk@[^#]*#/Config.pkl"$|\1|p' hk.pkl | head -n 1)}"
if [[ -z "$version" ]]; then
  echo "could not determine the hk package version from hk.pkl" >&2
  exit 1
fi

vendor_root=".hk/pkl/hk-$version"
tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/hk-pkl.XXXXXX")"
trap 'rm -rf "$tmp_dir"' EXIT

mkdir -p "$vendor_root"
curl --fail --location --silent --show-error \
  "https://github.com/jdx/hk/releases/download/v$version/hk@$version.zip" \
  --output "$tmp_dir/hk.zip"
unzip -oq "$tmp_dir/hk.zip" -d "$vendor_root"

rewritten="$tmp_dir/hk.pkl"
awk -v root="$vendor_root" '
  /^amends "package:\/\/github.com\/jdx\/hk\/releases\/download\/v[^/]+\/hk@[^#]+#\/Config.pkl"$/ {
    print "amends \"" root "/Config.pkl\""; next
  }
  /^import "package:\/\/github.com\/jdx\/hk\/releases\/download\/v[^/]+\/hk@[^#]+#\/Builtins.pkl"$/ {
    print "import \"" root "/Builtins.pkl\""; next
  }
  { print }
' hk.pkl > "$rewritten"

if cmp -s hk.pkl "$rewritten"; then
  echo "hk.pkl did not contain the expected package imports" >&2
  exit 1
fi
cp hk.pkl hk.pkl.before-vendoring
mv "$rewritten" hk.pkl
hk validate

Commit .hk/pkl/ and the updated hk.pkl. This is the strongest option: even a completely cold machine needs no network for hk's configuration. Rerun it when changing the pinned hk package version.

2. Use the Pkl CLI's persistent package cache

pklr does not currently persist downloaded packages, but the Pkl CLI does. This script preloads the exact package referenced by hk.pkl into Pkl's default ~/.pkl/cache and deliberately disables hk's cache during validation:

#!/usr/bin/env bash
set -euo pipefail

version="${1:-$(sed -n 's|^amends "package://github.com/jdx/hk/releases/download/v\([^/]*\)/hk@[^#]*#/Config.pkl"$|\1|p' hk.pkl | head -n 1)}"
if [[ -z "$version" ]]; then
  echo "could not determine the hk package version from hk.pkl" >&2
  exit 1
fi

package="package://github.com/jdx/hk/releases/download/v$version/hk@$version"
pkl download-package "$package"
HK_CACHE=0 HK_PKL_BACKEND=pkl hk validate

echo "Package cached. Set HK_PKL_BACKEND=pkl wherever hk hooks run."

Afterward, persist this in the environment that launches Git/hk (shell profile, dev environment, CI configuration, or directly in the hook command):

export HK_PKL_BACKEND=pkl

I separately tested option 2 from a genuinely cold Pkl cache: downloaded hk 1.54.1, disabled hk's own cache, blocked network access, and hk validate still succeeded. You need to preload each new pinned package version, and the cache must survive between runs; for ephemeral or air-gapped machines, option 1 is better.

AI-assisted — Tool: Codex; model: unavailable/unavailable; version: unavailable.