A distributed compiler cache that a regulated security team will actually approve. Sandboxed remote compilation · per-tenant KVM boundary · auditable by row.
⚠️ Work in progress. hpcc is under active development and has not been audited.
Do not rely on it for security-sensitive or production workloads yet.
Quick start
git clone https://github.com/aarani/hpcc.git
cd hpcc && go build && go install
# wrap a compiler invocation
hpcc wrap cc -c hello.c -o hello.o
# or wire into a Makefile
make CC="hpcc wrap cc" CXX="hpcc wrap c++"
# start the daemon (foreground; supervise with systemd / launchd)
hpcc start
Server quick start
Bring up the distributed pieces — one scheduler, N workers, M clients
— without hand-editing TOML. hpcc init writes the configs for you;
the generated files validate immediately.
Scheduler. Needs a TLS cert clients can trust (public CA or your
org's internal CA) and one tenant's IdP coordinates:
The command prints a freshly-generated worker_token; copy it.
Workers (Linux / Firecracker). On each worker host, paste the
token from above and point at the scheduler. TLS material is
self-signed and minted in place — the scheduler pins by SHA-256
fingerprint at registration, so a real CA isn't needed worker-side:
hpcc init worker \
--scheduler scheduler.internal:9091 \
--token <paste from init scheduler> \
--public-addr worker-1.internal:9092
# Host prerequisites:
#
# # firecracker + jailer — no distro package; grab the upstream
# # tarball. arm64 hosts: swap x86_64 → aarch64 in URL + filenames.
# FC=v1.15.1
# curl -fsSL https://github.com/firecracker-microvm/firecracker/releases/download/${FC}/firecracker-${FC}-x86_64.tgz \
# | sudo tar -xz -C /tmp
# sudo install /tmp/release-${FC}-x86_64/firecracker-${FC}-x86_64 /usr/bin/firecracker
# sudo install /tmp/release-${FC}-x86_64/jailer-${FC}-x86_64 /usr/bin/jailer
#
# # microvm kernel + agent ship with every hpcc release. Pin HPCC
# # to whichever release you installed; K=6.1 is the recommended
# # kernel (5.10 ships as the alternative); A=amd64 or arm64.
# HPCC=v0.1.0-alpha; K=6.1; A=amd64
# sudo mkdir -p /var/lib/hpcc
# sudo curl -fsSL -o /var/lib/hpcc/vmlinux \
# https://github.com/aarani/hpcc/releases/download/${HPCC}/vmlinux-${K}-${A}
# sudo curl -fsSL -o /var/lib/hpcc/hpcc-agent-linux-${A} \
# https://github.com/aarani/hpcc/releases/download/${HPCC}/hpcc-agent-linux-${A}
hpcc worker
The generated worker.toml points at the standard paths above; if you
have firecracker installed somewhere else, edit
[runtime.firecracker] to match. For a zero-isolation dev box, pass
--runtime really_really_dangerous (never production).
Workers (Windows / Hyper-V). Same paste-the-token flow, with the
hcsshim runtime selected:
hpcc init worker `
--scheduler scheduler.internal:9091 `
--token <paste from init scheduler> `
--public-addr worker-win-1.internal:9092 `
--runtime runhcs-wcow-hypervisor
# Host prerequisites (the init command tells you exactly these):
# Install-WindowsFeature Hyper-V -IncludeManagementTools # reboot once
# Start-Service vmcompute # HCS
# # containerd listening on \\.\pipe\containerd-containerd
# # hpcc-agent.exe staged at C:\ProgramData\hpcc\hpcc-agent.exe
hpcc worker
Hyper-V isolation is the production value — each container runs in
its own utility VM, the kernel boundary a regulated security review
recognises. For hosts without nested virt (GitHub-hosted CI runners,
dev laptops), edit runtime.hcsshim.isolation = "process" in the
generated file; you lose the kernel boundary, so this is dev-only.
Clients. On each developer machine, point the client at the
scheduler and authenticate against the tenant IdP:
Then point your build at hpcc wrap cc / hpcc wrap c++ as in the
client Quick start above. The daemon falls back to local execution on
any remote failure and prints a red warning, so a misconfigured client
never blocks a build.
Why?
ccache, sccache, and distcc all assume the worker is trusted
shared-kernel infrastructure. That assumption ends the conversation in
a regulated enterprise. hpcc inverts it: every compile runs in a
per-tenant Firecracker microVM (Linux) or Hyper-V-isolated container
(Windows), the worker has no NIC, the container image digest is the
toolchain identity, and every job lands a single audit row.
Package bootstrap holds first-run helpers shared by `hpcc init scheduler` and `hpcc init worker`: generating a worker-token suitable for the scheduler<->worker shared secret, and minting a self-signed TLS leaf for components whose peer pins by fingerprint (the worker).
Package bootstrap holds first-run helpers shared by `hpcc init scheduler` and `hpcc init worker`: generating a worker-token suitable for the scheduler<->worker shared secret, and minting a self-signed TLS leaf for components whose peer pins by fingerprint (the worker).
Package dispatch implements the daemon's remote-compile path: read the cached JWT written by `hpcc auth login`, authenticate against the scheduler, route each compile to a worker, and dial the worker directly to invoke Compile.
Package dispatch implements the daemon's remote-compile path: read the cached JWT written by `hpcc auth login`, authenticate against the scheduler, route each compile to a worker, and dial the worker directly to invoke Compile.
README
¶
Documentation
Source Files
Directories
¶