fix: build the azkaban bundle as UID 1000 #84

Merged

claudiomaradonna merged 2 commits from docs/azkaban-env-alignment into master 2026-11-11 16:45:31 +01:00

Conversation 0 Commits 2 Files changed 4 +31 -29

motoko commented 2026-11-11 16:43:48 +01:00

Collaborator

Copy link

Why

Dockerfile.azkaban gives coding agents run in azkaban the tools this
site needs. #83 landed an earlier revision of it, without the changes
its review asked for: the bundle installed as root, and global npm
packages went to /usr/local/npm-global, which the agent's Bash
sandbox cannot write, so the Setup command's npm install -g terser
failed inside the sandbox. This pull request brings the reviewed
revision.

It also aligns CONTRIBUTING.md with how azkaban reads settings today.
The guide said to copy azkaban's env.claude.example to .env.claude
at the repository root for personal mounts and settings; azkaban now
reads launcher settings from an identity's files under
~/.azkaban/identities/, and a project .env.claude that holds an
AZKABAN_ name stops the launch, so a contributor following the guide
could not launch.

Refs #83

What changed

Before, the image installed the bundle as root and put npm globals
where the sandboxed agent could not install. Now the bundle installs as
UID 1000, and npm globals, terser included, live in the client user's
~/.local, so the Setup command runs inside the sandbox.

Before, CONTRIBUTING.md sent launcher settings to a project
.env.claude. Now it sends them to the identity's env.claude,
env.codex, or env.opencode, and keeps the project .env.claude for
ordinary container variables. The section also gets the reviewed
wording: bump notes for the Ruby and Node images live in the
Dockerfile's comments, and a Gemfile change is said to rebuild the
bundle without a new approval.

The ignore files drop the "Claude jail" headings and the unused .ai/
rule; .env.claude stays ignored by .gitignore's .env.* rule and by
.dockerignore.

How to verify

1. Have azkaban installed with its Claude client and a clone of this
   repository.
2. On master: git switch --detach origin/master, claude ., approve
   the file, then in the session ! npm install -g terser fails with a
   permission error on /usr/local/npm-global when run by the agent
   through its sandboxed Bash.
3. On the branch: git switch --detach origin/docs/azkaban-env-alignment,
   claude ., approve the changed file, then in the session:
   • ! ruby -v && node -v && which terser && echo $NPM_CONFIG_PREFIX
     prints ruby 4.0.7…, v24.x, /home/claude/.local/bin/terser,
     and /home/claude/.local;
   • ! bundle install && npm install -g terser ends without error;
   • ! make build && .agents/hooks/shellcheck.sh repo builds _site/
     and prints shell check: … files clean;
   • ask the agent to run npm install -g terser: it succeeds inside
     its sandbox.
4. git switch master afterwards.

Checks run: .agents/hooks/shellcheck.sh repo on each commit, clean;
git check-ignore -v .env.claude prints .gitignore:28:.env.*. Not
yet run: steps 2 and 3, which need azkaban on the host; this session
has no container engine.

Considerations

$HOME in the Dockerfile's COPY and ENV lines expands from the
client image's ENV HOME, which azkaban's client stage sets; step 3's
echo $NPM_CONFIG_PREFIX confirms it.

## Why `Dockerfile.azkaban` gives coding agents run in azkaban the tools this site needs. #83 landed an earlier revision of it, without the changes its review asked for: the bundle installed as root, and global npm packages went to `/usr/local/npm-global`, which the agent's Bash sandbox cannot write, so the Setup command's `npm install -g terser` failed inside the sandbox. This pull request brings the reviewed revision. It also aligns CONTRIBUTING.md with how azkaban reads settings today. The guide said to copy azkaban's `env.claude.example` to `.env.claude` at the repository root for personal mounts and settings; azkaban now reads launcher settings from an identity's files under `~/.azkaban/identities/`, and a project `.env.claude` that holds an `AZKABAN_` name stops the launch, so a contributor following the guide could not launch. Refs #83 ## What changed Before, the image installed the bundle as root and put npm globals where the sandboxed agent could not install. Now the bundle installs as UID 1000, and npm globals, terser included, live in the client user's `~/.local`, so the Setup command runs inside the sandbox. Before, CONTRIBUTING.md sent launcher settings to a project `.env.claude`. Now it sends them to the identity's `env.claude`, `env.codex`, or `env.opencode`, and keeps the project `.env.claude` for ordinary container variables. The section also gets the reviewed wording: bump notes for the Ruby and Node images live in the Dockerfile's comments, and a `Gemfile` change is said to rebuild the bundle without a new approval. The ignore files drop the "Claude jail" headings and the unused `.ai/` rule; `.env.claude` stays ignored by `.gitignore`'s `.env.*` rule and by `.dockerignore`. ## How to verify 1. Have azkaban installed with its Claude client and a clone of this repository. 2. On `master`: `git switch --detach origin/master`, `claude .`, approve the file, then in the session `! npm install -g terser` fails with a permission error on `/usr/local/npm-global` when run by the agent through its sandboxed Bash. 3. On the branch: `git switch --detach origin/docs/azkaban-env-alignment`, `claude .`, approve the changed file, then in the session: - `! ruby -v && node -v && which terser && echo $NPM_CONFIG_PREFIX` prints `ruby 4.0.7…`, `v24.x`, `/home/claude/.local/bin/terser`, and `/home/claude/.local`; - `! bundle install && npm install -g terser` ends without error; - `! make build && .agents/hooks/shellcheck.sh repo` builds `_site/` and prints `shell check: … files clean`; - ask the agent to run `npm install -g terser`: it succeeds inside its sandbox. 4. `git switch master` afterwards. Checks run: `.agents/hooks/shellcheck.sh repo` on each commit, clean; `git check-ignore -v .env.claude` prints `.gitignore:28:.env.*`. Not yet run: steps 2 and 3, which need azkaban on the host; this session has no container engine. ## Considerations `$HOME` in the Dockerfile's `COPY` and `ENV` lines expands from the client image's `ENV HOME`, which azkaban's client stage sets; step 3's `echo $NPM_CONFIG_PREFIX` confirms it.

motoko added 2 commits 2026-11-11 16:43:51 +01:00

fix: build the azkaban bundle as UID 1000 ... e8b392b4ee

The Gemfile, which the agent can edit, is Ruby that bundle install
evaluates, and a change to it rebuilds the ruby stage without a new
approval; installing as UID 1000 keeps it from writing the rest of
/usr/local, which the final stage copies over the client image.
Global npm packages move to the client's ~/.local, the only place the
agent's Bash sandbox may write, so the Setup command runs there.

docs(contributing): align with azkaban identity settings ... f0ce68249b

azkaban reads launcher settings from an identity's env.claude under
~/.azkaban/identities/; a project .env.claude may hold container
variables only, and an AZKABAN_ name there stops the launch. Also
brings the reviewed wording of the azkaban section, and drops the
Claude jail headings and the unused .ai/ rule from the ignore files.

claudiomaradonna merged commit f0ce68249b into master 2026-11-11 16:45:31 +01:00

claudiomaradonna deleted branch docs/azkaban-env-alignment 2026-11-11 16:45:38 +01:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

unitoo/website!84

No description provided.