Status: unsupported experimental. These surfaces are source-available but outside the supported v3 product contract. They are hidden from default hack --help (see hack help --all) and print a warning when invoked.

This is a beta workflow. Start with Core docs if you are new to hack, and use Beta workflows for the rest of the remote path.

Use the published node-runtime container to spin up a remote node with minimal host setup.

Beta: multi-node execution is still being validated and is not part of the core local-dev path.

Recommended public image:

• hackdance/hack:latest

Companion portable base image for managed containers:

• hackdance/hack:slim

The container bundles:

• hack CLI binary
• docker CLI + docker compose plugin
• bootstrap entrypoint that can initialize a project, enable gateway, and emit an enrollment bundle

The slim image keeps only the portable baseline (hack, Bun, Git/SSH/curl, and slim-mode defaults) for Codex, CI, and other managed container workflows. It is not a remote-node replacement.

1. Start the runtime container on the remote host:

docker run -d \
  --name hack-node \
  --restart unless-stopped \
  -p 7788:7788 \
  -v hack-node-home:/var/lib/hack \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e HACK_NODE_NAME="aws-node-1" \
  -e HACK_NODE_ENDPOINT="https://node.example.com" \
  -e HACK_NODE_GIT_REPO="git@github.com:<org>/<repo>.git" \
  -e HACK_NODE_LABELS="aws,ec2,linux" \
  -e HACK_NODE_ENROLL_PATH="/var/lib/hack/enrollment/node.bundle.json" \
  hackdance/hack:latest

2. Fetch enrollment bundle from the remote host:

ssh <remote-host> 'docker exec hack-node cat /var/lib/hack/enrollment/node.bundle.json' > node.bundle.json

3. Register node on controller:

hack node add --bundle node.bundle.json --default
hack node status --watch

When HACK_NODE_GIT_REPO points to a private repo, credentials must be available inside the container.

Common approaches:

• SSH deploy key:
  • mount key material into the container (-v ~/.ssh:/root/.ssh:ro) and pre-populate known_hosts.
• HTTPS token:
  • provide a credential helper/config in the image or mount git credential files.

If credentials are missing, workspace bootstrap clone fails and dispatch cannot prepare branch workspaces.

Container entrypoint behavior (default):

1. Creates node workspace directory.
2. Optionally clones repo (HACK_NODE_GIT_REPO).
3. Initializes project via hack init --auto --no-discovery when .hack/ is missing.
4. Enables project gateway and global gateway extension.
5. Applies gateway bind/port/allowWrites config from env vars.
6. Optionally writes enrollment bundle (HACK_NODE_ENROLL_PATH).
7. Clears daemon pid/socket state in persisted home volumes.
8. Starts hack daemon start --foreground.

• Branch-scoped dispatch expects a git workspace. For containerized nodes, set HACK_NODE_GIT_REPO (recommended) or initialize git manually in the project dir.
• Reusing hack-node-home across container restarts is supported; startup clears stale daemon pid/socket files before launching hackd.

Local image build:

bun run build:node-runtime-image --tag hack-node-runtime:dev

build:node-runtime-image compiles the hack binary inside a Linux Docker build stage, so the image is portable even when built from macOS hosts.

Publish multi-arch image:

bun run build:node-runtime-image \
  --push \
  --platform linux/amd64,linux/arm64 \
  --tag hackdance/hack:latest

Build the slim managed-container image locally:

bun run build:slim-runtime-image --tag hack-slim-runtime:dev

Publish the slim image:

bun run build:slim-runtime-image \
  --push \
  --platform linux/amd64,linux/arm64 \
  --tag hackdance/hack:slim

GitHub Actions workflow:

• .github/workflows/release-node-runtime-image.yml