Try it

This page takes one project to the native backend and back. You need an Apple Silicon Mac. Read what works and known limits first, and use a project you can afford to break.

Nothing here changes your stable Hack. Stable hack, ~/.hack and your Compose projects keep working the whole time.

1. Install the candidateCopy Anchor Link

The native backend ships in v5 prereleases. Each prerelease has a fixed tag, v5.0.0-next.N. Download the installer from the release you want, read it, then run it:

curl --fail --location --proto '=https' --proto-redir '=https' --tlsv1.2 \
  https://github.com/hack-dance/hack/releases/download/v5.0.0-next.14/hack-next-install.sh \
  --output hack-next-install.sh
less hack-next-install.sh
sh hack-next-install.sh
"$HOME/.hack-next/bin/hack-next" --version

Everything goes into ~/.hack-next. The installer does not edit your PATH, start a virtual machine, or change DNS or certificate trust. Newer prereleases are on the releases page. For details, see Install a prerelease.

2. Prepare the runtimeCopy Anchor Link

The native backend needs its virtual machine software set up once per installed version. This step is manual today.

A hack-next install keeps each version in its own folder. The two paths you need are the native program and its private home:

V=5.0.0-next.14   # the version you installed; `hack-next --manager status` shows it
NATIVE="$HOME/.hack-next/versions/$V/bundle/hack-native"
NATIVE_HOME="$HOME/.hack-next/versions/$V/native-home"

Download the exact archives named in provider-pins.json, which sits beside hack-native in the bundle. Then download these four packages from the Alpine v3.19 main repository for aarch64, with exactly these names:

• iptables-1.8.10-r3.apk
• libmnl-1.0.5-r2.apk
• libnftnl-1.2.6-r0.apk
• libxtables-1.8.10-r3.apk

Their hashes are in the table under network tool packages, not in provider-pins.json.

Put them in a folder under your home folder, not under /tmp: Hack refuses a path that passes through a symbolic link, and /tmp is one on macOS. Hack also refuses the packages unless the folder and files are private to you, which is not how a download leaves them:

chmod 700 /absolute/private/pinned-apks
chmod 600 /absolute/private/pinned-apks/*.apk

Then prepare the runtime and check that this Mac can run it:

"$NATIVE" --candidate-root "$NATIVE_HOME" runtime prepare --archive /absolute/smolvm-archive.tar.gz
"$NATIVE" --candidate-root "$NATIVE_HOME" runtime prepare-engine --archive /absolute/docker-archive.tgz
"$NATIVE" --candidate-root "$NATIVE_HOME" runtime prepare-network-tools --directory /absolute/private/pinned-apks
"$NATIVE" --candidate-root "$NATIVE_HOME" runtime probe --profile development --json

Pass --profile development to runtime probe. Without it the probe checks a stricter research profile and can report "not admitted" on a Mac that runs projects fine. The native reference explains each command.

3. Check the projectCopy Anchor Link

Ask Hack whether the project can run on native before you start it:

"$HOME/.hack-next/bin/hack-next" doctor --path /absolute/project

hack-next selects the native backend by default. If the project uses a Compose feature that native does not support, doctor names it. Starting the project would refuse with E_NATIVE_PROJECT_UNSUPPORTED and change nothing. See Compose features that stay on Compose.

4. Run itCopy Anchor Link

"$HOME/.hack-next/bin/hack-next" up --path /absolute/project

Native up runs in the foreground and holds the project until you stop it. Add -d to run it in the background instead. From a second terminal, or after up -d:

"$HOME/.hack-next/bin/hack-next" ps --path /absolute/project
"$HOME/.hack-next/bin/hack-next" logs api --no-follow --path /absolute/project
"$HOME/.hack-next/bin/hack-next" down --path /absolute/project

Stop the project with hack down from another terminal, as above. In this prerelease, Ctrl-C may not stop a foreground project cleanly when it publishes ports. If you already pressed Ctrl-C, run hack down, and hack down --recover if it reports that the owner is gone. A fix is in progress.

Then check the application itself: sign in, load a page that reads data, restart, and confirm the data is still there. A green status alone does not prove the application works.

5. Switch back to ComposeCopy Anchor Link

You have two ways back.

Use stable Hack. Run hack up in the project as you always did. The native test did not touch your stable setup.

Run the same prerelease on Compose. Set one variable:

HACK_RUNTIME_BACKEND=compose "$HOME/.hack-next/bin/hack-next" up --path /absolute/project

On Compose the prerelease uses your normal Hack home, the same one stable Hack uses. Do not run both against it at once. Stop the stable daemon first; the order is in Stop stable hackd before a Compose run.

Data does not move between backends. A database you filled on native is not in your Compose volumes, and the other way round.

Remove itCopy Anchor Link

Stable Hack never depended on the candidate. To upgrade, roll back or stop using hack-next, see Upgrade, roll back and return to stable.

Source: v5 (next.14) · docs/native/try-it.md.