@@ -8,7 +8,8 @@ Use this path when:
88- the container is ephemeral or cache-backed
99- you only have a setup script and optional maintenance script
1010- ` hack global install ` is too heavy or not applicable
11- - you want tickets, integrations, docs, and repo-local CLI workflows without the full local host stack
11+ - you want env resolution, host exec, agent integrations, and repo-local CLI workflows without the
12+ full local host stack
1213
1314## Published slim image
1415
@@ -74,9 +75,16 @@ hack host exec -- printenv DATABASE_URL
7475hack host exec --scope api -- bun test
7576```
7677
77- CI uses this exact contract in ` scripts/portable-container-smoke.sh ` : it mounts ` examples/basic `
78- into the slim image, removes the local ` .hack.secret.key ` , injects ` HACK_ENV_SECRET_KEY ` , and
79- verifies both ` hack env list ` and ` hack host exec ` resolve the committed env correctly.
78+ CI exercises this contract in ` scripts/portable-container-smoke.sh ` : it copies ` examples/basic `
79+ into a temp fixture, seeds values with ` hack env add ` , removes the local ` .hack.secret.key ` ,
80+ mounts the fixture into the CI-built slim image, injects ` HACK_ENV_SECRET_KEY ` , and verifies both
81+ ` hack env list ` and ` hack host exec ` resolve the committed env correctly.
82+
83+ Scripts and agents in containers should also set ` HACK_NO_INTERACTIVE=1 ` (or pass
84+ ` --no-interactive ` ): commands then fail fast with ` E_INTERACTIVE_REQUIRED ` instead of blocking on
85+ a prompt that can never be answered. Set ` NO_COLOR=1 ` for log-clean output, and use the ` --json `
86+ envelope (` {ok, data | error: {code, message}} ` ) on ` up ` /` down ` /` restart ` /` doctor ` for CI
87+ assertions.
8088
8189## What slim mode does
8290
@@ -103,15 +111,21 @@ curl -fsSL \
103111 | bash
104112```
105113
106- The installer downloads the latest Hack release tarball, installs the binary into ` ~/.hack/bin ` ,
107- and writes a thin ` hack ` wrapper with these defaults:
114+ The installer resolves the latest release tag, downloads the platform tarball, installs the
115+ binary and bundled assets under ` ~/.hack/ ` (override with ` HACK_INSTALL_BIN ` ), and writes a thin
116+ ` hack ` wrapper with these defaults:
108117
109118- ` HACK_EXECUTION_MODE=codex `
110119- ` HACK_DAEMON_DISABLE_DOCKER_EVENTS=1 `
111120- ` HACK_SETUP_SYNC_MODE=warn `
121+ - ` HACK_ASSETS_DIR ` pointed at the installed assets
122+
123+ For reproducible CI, pin the release with ` HACK_INSTALL_TAG ` or ` HACK_INSTALL_VERSION ` (and
124+ ` HACK_RELEASE_BASE_URL ` for mirrors) instead of tracking ` latest ` .
112125
113126If you are already inside a container built from ` hackdance/hack:slim ` , Hack and Bun are already
114- available and you can skip the installer entirely.
127+ available with the same three mode defaults baked into the image env, and you can skip the
128+ installer entirely.
115129
116130## Recommended setup script
117131
@@ -120,7 +134,7 @@ When you are not using the slim image:
120134``` bash
121135set -euo pipefail
122136
123- mise install bun@1.3.5
137+ mise install " bun@$( awk ' /^bun /{print $2} ' .tool-versions ) "
124138export PATH=" $HOME /.local/share/mise/shims:$PATH "
125139
126140bun install
@@ -144,7 +158,7 @@ When you are not using the slim image:
144158``` bash
145159set -euo pipefail
146160
147- mise install bun@1.3.5
161+ mise install " bun@$( awk ' /^bun /{print $2} ' .tool-versions ) "
148162export PATH=" $HOME /.local/share/mise/shims:$PATH "
149163
150164bun install --frozen-lockfile || bun install
@@ -167,15 +181,18 @@ bash scripts/maintain-codex-slim.sh
167181
168182## Good fit for slim mode
169183
170- - ` hack tickets `
171184- ` hack env list `
172185- ` hack host exec `
173186- ` hack host shell `
174187- repo-local docs, specs, and agent setup
175188- command and config surfaces that do not require the machine-wide runtime stack
189+ - ` hack tickets ` , if the project opts in — the extension is disabled by default; run
190+ ` hack tickets setup ` once (it works even while the extension is disabled and enables it)
176191
177192If the repo uses the modern env overlay model, provide secret decryption material with
178- ` HACK_ENV_SECRET_KEY ` instead of relying on a local ` .hack.secret.key ` file:
193+ ` HACK_ENV_SECRET_KEY ` instead of relying on a local ` .hack.secret.key ` file. (On a developer
194+ machine you rarely need this: linked worktrees inherit the key through the git common dir — the
195+ env var is for CI, containers, and detached checkouts. See [ Env & secrets] ( ../env.md ) .)
179196
180197``` bash
181198export HACK_ENV_SECRET_KEY=" ..."
@@ -207,11 +224,10 @@ child shell after env injection.
207224
208225## Not available in slim mode
209226
210- - ` hack global install `
211- - ` hack global up `
212- - ` hack global status `
213- - ` hack global logs `
214- - explicit Loki-backed log paths such as ` hack logs --loki `
227+ The machine-wide ` hack global ` surface (install, up, down, status, trust, ca, cert, logs, and
228+ logs-reset) is slim-gated, along with explicit Loki-backed log paths such as ` hack logs --loki ` .
215229
216- When you need full remote runtime orchestration instead of repo-local agent workflows, use the
217- [ remote node container image] ( remote-node-container.md ) instead.
230+ When you need full remote runtime orchestration instead of repo-local agent workflows, the
231+ [ remote node container image] ( remote-node-container.md ) exists — but note that the entire
232+ remote/node/gateway/dispatch surface is unsupported experimental in v3 (hidden behind
233+ ` hack help --all ` ), not a supported product path.
0 commit comments