Repository navigation
feat(bla): start a beamline coding agent as the agent service account - #38
Merged
Thomas A Caswell (tacaswell) merged 19 commits intoNov 13, 2026
Merged
Conversation
Garrett Bischof (gwbischof)
force-pushed
the
feat/bl-agent
branch
2 times, most recently
from
November 5, 2026 19:47
1e68686 to
a9ad778
Compare
Beamline staff do not run the bw* launchers as the agent account themselves. They run bl-agent through sudo, and it decides everything the agent sees: the AI gateway key, the NSLS-II API tokens, the writable directory and the agent to start. Only the agent name is taken from the command line, and only from a fixed list; no option is passed through, so a caller cannot widen the sandbox with --exec, --rw-path, --ro-path or --n2c-token. The calling user, the host and the agent go to syslog before the agent starts, so an action can be traced to a person even though the agent runs as a shared account. The gateway key is read from the file the n2c_agent role installs and passed as AIFAPIM_API_KEY, which every bw* wrapper already understands; bwclaude turns it into ANTHROPIC_FOUNDRY_API_KEY itself. N2SN_CREDS_DIR points at the tokens the root minter keeps, so the account needs no n2c-token session of its own. Assisted-by: opencode:claude-opus-4-8
Three things found by running it on AlmaLinux 8. sudo replaces PATH with its secure_path, which holds neither /opt/nsls2/scripts/bin nor /usr/local/bin, and the profile.d snippet that adds them is only read by a login shell, so exec'ing the wrapper by name always failed. Run it by absolute path, next to this script. hostname is not installed everywhere and the failure was swallowed, so the audit line said host= with nothing after it. Use HOSTNAME, and let a logger failure stop the run: no log line, no agent. The BL_AGENT_* path overrides were there to test on macOS. A launcher whose point is that the caller decides nothing should not read caller-controlled variables for credential paths, even though sudo scrubs them today. Assisted-by: opencode:claude-opus-4-8
Every other script in bin/ has a page in docs/ and a row in the README table; bl-agent had neither. Also write the account check the way bwrap_check_account does in the shared library, instead of a one-line short-circuit that says the same thing less clearly. Assisted-by: opencode:claude-opus-4-8
Found running the real wrappers on AlmaLinux 8. sudo's secure_path is /sbin:/bin:/usr/sbin:/usr/bin, so the wrapper could not find opencode, which npm installs in /usr/local/bin. The wrappers create their authoring directories under $HOME on the host before bind-mounting them in, and xfagent has no home: every run died on 'mkdir: cannot create directory /home/xfagent'. Point HOME at the tmpfs the host setup role mounts, and check it is writable first. HOME cannot be the caller's agent directory: a wrapper refuses to run where the working directory is $HOME or an ancestor of it, since that would mount the whole home tree. Assisted-by: opencode:claude-opus-4-8
Garrett Bischof (gwbischof)
force-pushed
the
feat/bl-agent
branch
from
November 5, 2026 20:01
a9ad778 to
8b7046c
Compare
Slide 10 of the plan: the agent reads the live profile collection and works on a clone in the agent directory. $HOME is a tmpfs in the sandbox, so the rest of the operator's home stays hidden and only this directory is mounted back, read-only. A host without one starts with a warning rather than failing: not every host that runs an agent has a profile collection, and the queue servers keep theirs somewhere else. Assisted-by: opencode:claude-opus-4-8
The agent directory, its ACLs and a home for the agent account were going to be an ansible role. They do not need to be: the caller owns their home, so bl-agent creates the agent directory and sets the ACLs as them, before re-running as the agent account. Both accounts get default entries on the agent directory. Without them a file the agent creates is owned by the agent account and unreadable to the person who has to review it, which is the whole hand-off in the plan. $HOME for the agent account is /tmp/bl-agent-<caller>: that account has no home and no XDG runtime directory, nothing kept there needs to outlive a reboot, and per-caller means two people sharing the account do not share a cache. Assisted-by: opencode:claude-opus-4-8
shfmt is configured with keep_padding, which indents a multi-line array one space further every time it runs, so the file never settles and the lint job cannot pass. One line avoids the construct entirely. The map is still the allow-list the usage text and the unknown-agent check read, both unchanged. Assisted-by: opencode:claude-opus-5
Found by exercising the launcher in a container:
--help and a bare run created the agent directory, set ACLs and needed
the sudo rule before they would print. Asking what the command is now
answers anyone and changes nothing.
An option in the agent's place was reported as a stray argument ('got:
bash' for --exec bash), and a typo still created a directory, because
the name was only checked after the re-run as the agent account. All
argument checking now happens first.
A symlinked agent directory was refused, but blamed the filesystem for
not supporting ACLs. It is now named for what it is, and checked again
as the agent account, which also closes the window where the caller
could swap the directory after the ACLs were set.
An unreadable gateway key printed bash's own error about the path before
ours.
Assisted-by: opencode:claude-opus-5
…ction A $HOME per session, under the directory the n2c_agent role makes on the tmpfs. Two agents started at once no longer race to create the same database, and two people sharing an operator account do not read each other's conversations. The cache stays per caller: it is most of the size and holds nothing personal. The profile collection is mounted read-write, so the agent edits and commits in the real repository. That needs an identity, which it had none of, and safe.directory, because the repository belongs to the caller and git refuses to work in someone else's. Both go in a gitconfig in $HOME, which the wrappers mount. The same ACLs the agent directory gets are applied to the profile collection, or the person is locked out of committing after the agent has. The agent cannot push: the sandbox has no GitHub credentials. It says so at startup and gives the command to publish afterwards. check_profile_collection refuses a link the caller cannot write. It catches a mistake, not a determined caller, who owns the link and can repoint it after the check; scoping the agent account per beamline is what would make that pointless. Assisted-by: opencode:claude-opus-5
The page still said HOME was /tmp/bl-agent-<caller> and that the profile collection was mounted read-only, both of which changed when the agent started committing. Adds what it gained since: the shared cache and why npm needs an .npmrc to use it, the ACLs on the profile collection and what goes wrong without them, the check on a caller-pointed symlink and what it does not cover, and the git identity the agent commits with. Assisted-by: opencode:claude-opus-5
Typing 'bla' is the whole command for the common case. An agent can still be named, and --help lists them with the default called out. The resolved agent is passed to the re-run as the agent account rather than the original arguments, so the two phases cannot disagree about which one was meant. Fixes a bug the default exposed: write_git_config ended its group with a test that is false when there is no profile collection, so the group's exit status looked like a write failure and the launcher died saying it could not write a file it had just written. Every earlier test had a profile collection. Assisted-by: opencode:claude-opus-5
The page is about the tool, so it is named for it; bla appears where a command is meant. Assisted-by: opencode:claude-opus-5
Drops the git identity, keeping safe.directory. git refuses every command in a repository owned by someone else, so that entry is still needed for the agent to run git status at all. Leaving the identity out makes a commit fail with "please tell me who you are" rather than succeed quietly. A guard against a mistake, not a boundary: anyone can pass git -c user.name. The startup message now says to review with git diff rather than to push commits that will not be there. Assisted-by: opencode:claude-opus-5
A profile collection usually lives on shared storage, where setfacl fails. The recursive attempt walked every file to achieve nothing -- 7845 of them on the SMI collection -- and left the caller none the wiser about why the agent could not change anything. It now checks the filesystem first and says what it found. The list matches the ansible compliance role's compliance_agent_acls_fstypes, so there is one definition of which filesystems take ACLs. Assisted-by: opencode:claude-opus-5
The base role already puts base_aifapim_host in /etc/profile.d for everyone else, and n2c_agent now writes the same value next to the key. When the gateway moved to aifapim.nsls2.bnl.gov, a baseline run fixed every other caller; a hardcoded constant here would have needed its own release and left the agent 404ing in the meantime. The constant stays as the fallback for a host the role has not reached. Assisted-by: opencode:claude-opus-5
There was a problem hiding this comment.
🔵 Needs a closer look
Binary masking is disabled on the stated bwrap 0.4.0 target, leaving SSH, sudo, and other intended-to-be-masked binaries executable.
No open issues 🎉
What changed in this PR
Adds bla as a controlled entry point for beamline staff to launch existing sandboxed coding agents under the xfagent service account.
Changes:
- Selects an allowlisted agent, defaulting to
opencode2, without forwarding caller options. - Configures credentials, shared workspace permissions, session homes, caches, and startup auditing.
- Documents usage, sandbox access, and the human review-and-commit workflow.
| File | Description |
|---|---|
| README.md | Adds bla to the script index with a documentation link. |
| docs/beamline-agent.md | Describes launcher usage, configuration, permissions, and auditing. |
| bin/bla | Implements account switching, session setup, and sandbox-wrapper launch. |
Review effort: Balanced
A tmpfs inside the sandbox would give the same isolation and the same reboot behaviour. The state is on the host so a session outlives the sandbox that wrote it and can be reopened later, which is a change to the launcher rather than to where every agent stores its data. Notes that each run still makes a new directory, so nothing reopens one yet. Assisted-by: opencode:claude-opus-5
The comments said staff run this as themselves. They do not: the sudoers rule names the beamline operator account, so that is who invokes it, and a session on ws2 confirms it -- the caller directory is xf12id and the agent directory is /home/xf12id/agent. A sysadmin running it as themselves works too, but it is not the normal path, and introduction.md tells people to use this instead of running an agent as themselves. The error for an empty SUDO_USER said 'run it as yourself', which asked for the wrong thing on a shared operator account. It now says to run it from the account they logged in with. Assisted-by: opencode:claude-opus-5
SCRIPT_DIR followed symlinks (readlink -f) but PROGRAM_NAME did not (basename of $0), so composing them gave a path that does not exist as soon as the two differ. Reproduced: a symlink at /usr/local/bin/ beamline-agent pointing at /opt/nsls2/scripts/bin/bla made the re-exec ask sudo for /opt/nsls2/scripts/bin/beamline-agent. Everything now comes from one readlink -f, so the re-exec asks for the path the sudoers rule actually names. It also fixes the audit line: logger -t used PROGRAM_NAME, so a symlink would have renamed the audit trail too. Assisted-by: opencode:claude-opus-5
The check read as fussiness because nothing said what it was for. It is not a permission check -- the agent account is already past sudo by then. SUDO_USER is the only thing that says whose home holds ~/agent and the profile collection, whose session directory to use, and whose name goes in the audit line, and the agent account's own home holds none of that. The message said 'cannot tell who you are', which sounds like an identity check. It now names the consequence instead. Assisted-by: opencode:claude-opus-5
Thomas A Caswell (tacaswell)
approved these changes
Nov 13, 2026
There was a problem hiding this comment.
🔵 Needs a closer look
Human assessment is needed because unpublished findings show that the target bwrap version leaves SSH and other intended-to-be-masked clients available, undermining the claimed sandbox restrictions.
No open issues 🎉
Review effort: Balanced
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
blastarts a beamline coding agent as the agent service account, so beamlinestaff do not run the
bw*wrappers as that account themselves.The launcher decides everything the agent sees — the AI gateway key, the
NSLS-II API tokens, the writable directories and which agent starts. Only the
agent name is taken from the command line, from a fixed list, and no option is
passed through, so a caller cannot widen the sandbox with
--exec,--rw-path,--ro-pathor--n2c-token.What a session gets
~/agent$HOME/run/nsls2/agent/home/<caller>/on tmpfs<caller> (beamline agent)/noreply@bnl.gov, plussafe.directoryAn audit line goes to the journal at every start, naming the caller, host,
agent and directory.
Resolved since the first draft
/opt/nsls2/scripts/bin/bla, matching this repo ratherthan the
/usr/local/binin the deck. The sudo rule in NSLS2/ansible#5025names that exact path.
--n2c-token all. The minter is the thing that decides what theagent should hold; naming them here would mean a change in two repos every
time the set moves.
Testing
Run against an AlmaLinux 8.10 container (bwrap 0.4.0, the version on the
workstations), as a non-privileged caller through the real sudo rule:
cwd=~/agent, and the re-exec passes the resolvedagent so the caller and agent phases cannot disagree.
(
CapEff=0)./etc/opencode/AGENTS.mdreach the sandbox.SUDO_USER, caller is root.shellcheckandshfmtclean.Known gap: masking a binary does not stop a library.
npm install ssh2andpyNfsClientboth reach the network without the masked client. The sandbox isa boundary for what the agent can write, not a guarantee about what it can
reach; the nftables allow-list in NSLS2/ansible#5025 is what constrains that.
Draft until it has run on a real beamline workstation, which needs
xfagentinn2sn-service-accounts.