Using agents in the cluster¶

AI-powered agents are a powerful tools. They are increasingly being used as assistants for development, debugging, and job submission. However, if left unchecked with large enough privileges, they pose a risk to the user. An agent operating without constant human supervision can decide to delete data, submit malicious jobs, submit unnecessary jobs, or search for exploits. Therefore, sciCORE requires a controlled use of these tools. To that end, users can use the following grading levels to estimate the degree of risk, from lowest to highest, they are willing to take:

• L0: Run your agent outside of the cluster, sandboxed on a laptop or desktop with no access to your real data.
• L1: Run a sandboxed version of the agent on the cluster to develop code and prepare SLURM scripts. Instruct it not to submit jobs; a human reviews and submits them.
• L2: Run a sandboxed version of the agent on the cluster, and authorize it to develop code, prepare SLURM scripts, and submit jobs autonomously.
• L3: Run an unchecked agent.

Levels L1 and L2 use the same sandbox protection. They differ in who submits jobs: a human at L1, or the agent at L2. At L1, the instruction not to submit jobs is a behavioral expectation, not a technical restriction. The agent still has access to the sandbox’s mediated SLURM interface, which constrains job operations in both workflows.

sciCORE recommends operating at L0 or L1 by default. L2 is acceptable when autonomous job submission is needed and the recommended sandbox configuration described below is used. L3 workflows are not supported on sciCORE infrastructure.

Sandboxing agents in the cluster¶

A sandbox is an isolated environment that limits which files, credentials, system resources, and commands a program can access. When an agent runs in a sandbox, it operates with the same restrictions even if it attempts an unsafe action or follows malicious instructions contained in a file or external source. This reduces the potential impact of a mistake or compromise.

Sandboxing does not make an agent harmless. An agent can still modify or delete files inside writable directories, submit incorrect or unnecessarily expensive jobs when SLURM access is enabled, and produce scientifically incorrect results. Users must therefore expose only the files and credentials required for the task, keep backups, and review the agent’s work.

Recommended tool: agent-sandbox¶

sciCORE recommends agent-sandbox for running agents on the cluster. It is designed for HPC environments and provides profiles for commonly used coding agents.

With the Bubblewrap backend, agent-sandbox:

• gives the agent write access to its project directory while making unrelated paths read-only or inaccessible;
• hides sensitive files and environment variables, including SSH keys and cloud credentials;
• applies kernel-enforced filesystem and process restrictions; and
• provides a mediated SLURM interface that validates commands, limits job operations to the configured scope, and ensures submitted jobs remain sandboxed on compute nodes.

agent-sandbox is a best-effort isolation layer, not a guarantee of security. In particular, it does not fully isolate network access. For both L1 and L2 use, users should follow the project’s security guidance and use the sciCORE-supported configuration provided below.

Installing agent-sandbox¶

Run the following commands on the cluster:

git clone https://github.com/katosh/agent_sandbox.git
cd agent_sandbox
make install
export PATH="$HOME/.local/bin:$PATH"
agent-sandbox --version

After installation, download the sciCORE sandbox configuration linked here and copy it to the agent-sandbox configuration directory:

mkdir -p "$HOME/.config/agent-sandbox/"
cd "$HOME/.config/agent-sandbox/"
wget https://git.scicore.unibas.ch/scicore/agent_sandbox_config/-/raw/main/sandbox.conf

Go back to the directory of your local clone of the agent_sandbox repository and run:

bash test.sh --quick --backend bwrap

You should see that all tests pass (or are skipped).

Test the boundaries manually¶

Create a directory for testing, f.e.:

mkdir -p "$HOME/sandbox-test"

Start a terminal inside the sandbox:

cd "$HOME/sandbox-test"
agent-sandbox --backend bwrap -- bash

Run these pre-checks inside the sandbox:

echo "$SANDBOX_ACTIVE"
echo "$SANDBOX_BACKEND"
pwd
command -v sbatch
type -a sbatch

The output should report the following, with $HOME replaced by your actual home directory path:

1
bwrap
$HOME/sandbox-test
$HOME/.local/lib/agent-sandbox/chaperon/stubs/sbatch
sbatch is $HOME/.local/lib/agent-sandbox/chaperon/stubs/sbatch

Test that unsupported SLURM options are blocked:

sbatch --uid="$(id -u)" --wrap=true

The command should be blocked.

Verify sandboxed SLURM submission:

sbatch --wrap='
echo "sandbox=$SANDBOX_ACTIVE"
echo "backend=$SANDBOX_BACKEND"
test ! -e "$HOME/.ssh" && echo "SSH hidden on compute node"
pwd
hostname
'

After the job finishes, inspect slurm-<job-id>.out in the submission directory ($HOME/sandbox-test). It should report sandbox=1, identify the bwrap backend, and SSH hidden on compute node.

These checks confirm selected aspects of the setup; they are not a complete security assessment. If the expected checks fail, resolve the failure before using the agent.

Leave the sandbox:

exit

You are now back in your normal cluster shell.

Codex¶

Check whether the Codex CLI is already installed:

codex --version

If the command is not found, install Codex using the official installer:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Run codex --version again to verify the installation. The first time Codex starts, follow its prompt to sign in with ChatGPT or another available sign-in method.

Change to the project directory that Codex should work on, then launch it inside agent-sandbox:

agent-sandbox --backend bwrap -- codex --yolo

The --yolo option disables Codex’s own command approvals and built-in sandbox. It is used here because the surrounding Bubblewrap-based agent-sandbox provides the external security boundary.

OpenCode¶

OpenCode installation¶

Check whether OpenCode CLI/TUI is already installed:

opencode --version

If the command is not found, install opencode using the recommended curl recipe:

curl -fsSL https://opencode.ai/install | bash

Run opencode --version again to verify the installation. If the command is still unavailable, open a new shell so that changes made by the installer to your shell configuration take effect.

agent-sandbox configuration for OpenCode¶

You need to ensure that the folder containing the OpenCode executable is mounted (the default expects a system-wide installation, which is not possible on sciCORE).

To do this, first check where is the OpenCode executable:

which opencode

Then, modify the agent-sandbox’s OpenCode configuration file ~/.local/lib/agent-sandbox/agents/opencode/config.conf and locate the AGENT_REQUIRED_READABLE_PATHS assignment. Preserve its existing entries and add the directory containing your OpenCode installation. For an installation under ~/.opencode, add this immediately after the existing assignment:

AGENT_REQUIRED_READABLE_PATHS+=("$HOME/.opencode")

Adjust the path to match your installation.

Finally, change to the project directory that OpenCode should work on, then launch it inside agent-sandbox: Recent OpenCode versions need writable space in the sandbox’s temporary home directory. Override sciCORE’s HOME_ACCESS="restricted" setting for the OpenCode session:

HOME_ACCESS=tmpwrite agent-sandbox --backend bwrap -- opencode

Gemini¶

Gemini CLI installation¶

We recommend the Anaconda recipe to install Gemini CLI

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

Then test it by running

gemini --version

agent-sandbox configuration for Gemini¶

Configuring agent-sandbox for usage with gemini is done by ensuring the folder containing the gemini executable is mounted (the default expects a system-wide installation, which is not possible on sciCORE), as well as the setting of an environment variable.

To do this, first check where gemini executable sits:

which gemini

1. Modify file ~/.local/lib/agent-sandbox/agents/gemini/config.conf. Locate the AGENT_REQUIRED_READABLE_PATHS assignment. Immediately after it, add

       `AGENT_REQUIRED_READABLE_PATHS=("$HOME/anaconda3/envs/gemini_env")
   

   Replace this example path with the environment directory containing the executable found above.

2. Modify file ~/.local/lib/agent-sandbox/agents/gemini/overlay.sh. Locate the _AGENT_ENV_EXPORTS assignment. Immediately after it, add:

       _AGENT_ENV_EXPORTS+=("NODE_USE_ENV_PROXY=1")
   

Finally, change to the project directory that gemini should work on, then launch it inside agent-sandbox:

agent-sandbox --backend bwrap -- gemini

Claude Code¶

Claude Code installation¶

Run the installation steps from your normal cluster shell, outside the sandbox.

Check whether Claude Code is already installed:

claude --version

If the command is not found, install Claude Code using the official installer:

curl -fsSL https://claude.ai/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
claude --version

agent-sandbox configuration for Claude Code¶

A Claude Code profile is enabled by default.

Change to the project directory that Claude Code should work on, then verify that its executable is available inside the sandbox:

agent-sandbox --backend bwrap -- claude --version

If this succeeds, launch Claude Code:

agent-sandbox --backend bwrap -- claude

On the first launch, follow the displayed sign-in instructions. See the authentication documentation for supported account and provider options.

Troubleshooting executable access¶

If claude --version works outside the sandbox but the sandbox reports that the executable cannot be found, check its location from your normal cluster shell:

command -v claude
readlink -f "$(command -v claude)"

The native installer normally places the launcher in ~/.local/bin/claude, pointing to a version stored under ~/.local/share/claude/. Both locations must be readable inside the sandbox.

If these locations are not already exposed by your configuration, add the following to ~/.config/agent-sandbox/sandbox.conf:

HOME_READONLY+=(".local/bin" ".local/share/claude")

Adjust these paths if your installation uses different locations, then repeat the sandboxed version check.

Other agents¶

Refer to agent-sandbox documentation on adding new agents as well as the examples developed on this page.

Project configuration¶

agent-sandbox uses a system of configuration files to allow per-project overrides.

These files should sit in $HOME/.config/agent-sandbox/conf.d/ and be named <something>.conf.

They are read the general sandbox.conf file and can be used to complement some of the bash arrays declared there in order to, typically, mount more folders/files in read or write mode, or pass some environment variables.

By default all the conf.d files are read for each project, so it is advised to set some test which is used to apply them selectively project-by-project.

The two following sections demonstrate two ways of setting this up:

• based on the project folder name (this is similar to the examples shown in the documentation)
• using a bash variable

Granting access to an additional folder¶

Take the example of a project which needs read-access to data in /scicore/data/managed/.store/BLAST_FASTA_260817T191432/.

Presume that the project is in folder $HOME/projects/my_awesome_genomic_project

Create the file ~/.config/agent-sandbox/conf.d/genomic.conf:

# conf.d/genomic.conf
# config restricted to session with folder $HOME/projects/my_awesome_genomic_project
[[ "$_PROJECT_DIR" == $HOME/projects/my_awesome_genomic_project ]] || return 0

READONLY_MOUNTS+=(
    "/scicore/data/managed/.store/BLAST_FASTA_260817T191432"
)

This setup makes it so that any agent-sandbox session started in the $HOME/projects/my_awesome_genomic_project folder will be able to read data from the designated folder.

Granting access to conda environments¶

Several projects may need access to the same Conda environments. The following example enables that access when an environment variable is set.

Create the file ~/.config/agent-sandbox/conf.d/allow_conda.conf

# conf.d/allow_conda.conf
[[ "$SANDBOX_ALLOW_CONDA" == true ]] || return 0

## Adding the main location of conda environments.
## If you want to restrict to some environments only
## you can provide only their respective folders
HOME_READONLY+=("anaconda3" "mambaforge" "miniconda3")

These paths are relative to your home directory. Adjust them to match your installation and include only the directories the agent needs.

The configuration is activated if the bash variable SANDBOX_ALLOW_CONDA is set to true. For example:

export SANDBOX_ALLOW_CONDA=true
agent-sandbox --backend bwrap -- bash

Then, when inside the bubble-wrapped session, run conda env list to check what are the available conda environments.