Skip to content

Commit 47ca25a

Browse files
roodboiclaude
andcommitted
docs(guides): refresh managed-environments guide for the v3 surface
Audit fixes: tickets opt-in (setup enables it; removed from the intro promise), smoke-script mechanics corrected (temp fixture + CI-built image), installer described accurately (two-stage, pinning knobs, HACK_ASSETS_DIR, image env defaults), remote-node pointer marked unsupported experimental. Added --no-interactive/NO_COLOR/--json guidance for container scripts, worktree key-inheritance cross-link, full slim-gated global list, and bun version read from .tool-versions instead of a hardcoded pin. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 99e08fd commit 47ca25a

1 file changed

Lines changed: 34 additions & 18 deletions

File tree

docs/guides/codex-managed-environments.md

Lines changed: 34 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -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
7475
hack 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

113126
If 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
121135
set -euo pipefail
122136

123-
mise install bun@1.3.5
137+
mise install "bun@$(awk '/^bun /{print $2}' .tool-versions)"
124138
export PATH="$HOME/.local/share/mise/shims:$PATH"
125139

126140
bun install
@@ -144,7 +158,7 @@ When you are not using the slim image:
144158
```bash
145159
set -euo pipefail
146160

147-
mise install bun@1.3.5
161+
mise install "bun@$(awk '/^bun /{print $2}' .tool-versions)"
148162
export PATH="$HOME/.local/share/mise/shims:$PATH"
149163

150164
bun 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

177192
If 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
181198
export 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

Comments
 (0)