Using AI Agents on Gautschi

Agentic coding tools — Claude Code, Codex, Gemini CLI, opencode, and Warp — work well on Gautschi when they are set up with accurate, cluster-specific context. This chapter is the Gautschi-specific quick-start; the concepts, policy, MCP servers, and shared-context model live in the top-level Agentic AI section, and everything there applies here.

RCAC's stance is proactive engagement, not prohibition: we shape the context so an agent's output is more likely to be correct for Gautschi, and we help you verify it rather than forbidding the tools. Start with Acceptable Use & Etiquette and Best Practices & Limitations.

Choose how you run the agent

The Running Agents pages cover both deployment modes for all five harnesses:

• On the cluster — install a CLI harness (Claude Code, Codex, Gemini CLI, or opencode) on a Gautschi login node and run it there.
• Locally, targeting the cluster — run the harness on your own machine and reach Gautschi over SSH (host gautschi.rcac.purdue.edu) through the RCAC MCP servers. This is the recommended path, and the only way to use Warp (a desktop app that cannot run on a login node).

Gautschi's shared context

RCAC deploys a set of context files to /etc/agents.d/ on Gautschi — the partitions, GPUs, filesystems, and toolchain that general-purpose models most often get wrong — and rcac-mcp injects them into an agent. They are generated from Gautschi's verified facts, so an agent that reads them targets the right partitions and writes to the right filesystems. See Context Files for how the files are structured and Harness Settings & Permissions for the per-harness permission policy.

This is the exact assembled context an on-cluster agent reads on Gautschi:

Show Gautschi's assembled AGENTS.md

<!-- Note: generated by tools/generate_agent_context.py from tools/agent_context/clusters/gautschi.yml. Manual changes will be lost! -->
# Gautschi Agent Context

This file is the assembled agent context for Purdue RCAC's **Gautschi**
cluster, concatenated from the topic files in `/etc/agents.d/`. It is the
canonical guidance an agent should follow when operating on Gautschi. Read it
before acting.

<!-- Source: unix.md -->

# Unix Environment (Gautschi)

Gautschi runs **Rocky Linux 9** with a standard GNU/bash userland. You are acting as a
specific user, over that user's existing SSH access — you have exactly their
privileges and nothing more.

## The login (front-end) nodes are shared

Connecting to `gautschi.rcac.purdue.edu` places you on one of several shared front-end
nodes, used simultaneously by many people. They are for **editing, compiling,
submitting jobs, and light pre- and post-processing only**.

- **Do NOT run large, long, multi-threaded, parallel, or CPU-intensive work on a
  login node.** Submit it to Slurm instead (see `slurm.md`). Heavy work on a front end
  degrades the system for everyone and may be killed by administrators.
- **Do NOT start unbounded background processes or retry loops.** Clean up stray
  processes, and watch for your own retry storms.

## No elevated privileges

- **Do NOT use `sudo` or attempt to gain root.** You cannot install system packages.
- Install software into user space, or preferably use the environment modules system
  (see `lmod.md`).

## Ground yourself before acting

Prefer checking the real state of the system over assuming it. These commands are
read-only, cheap, and safe — run them eagerly before you plan or act:

- `myquota` — home and scratch usage and limits.
- `slist` — the accounts you can charge and their balances.
- `sfeatures` — node and GPU hardware features.
- `module avail` / `module list` — available and currently-loaded software.

Grounding your plan in real output prevents the most common failure mode: confidently
acting on an assumption that is wrong for this cluster.

<!-- Source: filesystems.md -->

# Filesystems (Gautschi)

Gautschi mounts several filesystems, each with a different purpose, technology, and
durability. Put data in the right place, and never assume a path is durable without
checking.

## Home — `/home/$USER` (`$HOME`)

- **Technology:** ZFS, with automatic snapshots (recoverable).
- **Use for:** source code, scripts, configuration, small files. It is
  medium-performance and space-limited.
- **Do NOT** stage large datasets or run heavy parallel job I/O here.

## Scratch — `/scratch/gautschi/$USER` (`$RCAC_SCRATCH`)

- **Technology:** Lustre, a high-performance parallel filesystem.
- **Use for:** active job input/output and large working data. Point writable working
  files here (`$RCAC_SCRATCH`), not at home. Find the path with `findscratch`.
- **Not backed up, and purged after 60 days of inactivity** (by last access and
  content-modification time; touching metadata does not protect a file). Use
  `purgelist` to see files scheduled for purge.
- **Do NOT** treat scratch as durable storage — move anything you want to keep to Data
  Depot or Fortress.

## Node-local — `/tmp`

- Ephemeral, per-node storage that exists only while your job runs on that node; not
  backed up, not recoverable.

## Long-term — Data Depot and Fortress

- **Data Depot** is group project space on **GPFS** (typically under `/depot`), for
  active research data you need to keep.
- **Fortress** is the HPSS archive for long-term/cold storage; move data with `hsi`
  and `htar`.

## Check before you write

- Run **`myquota`** to read home and scratch usage and limits before writing large
  amounts of data. **Do NOT assume specific quota numbers** — they differ per user and
  change over time; read them from `myquota`.
- Reference paths with environment variables (`$HOME`, `$RCAC_SCRATCH`), not
  hard-coded strings, since paths can change.

## Prohibitions

- **Do NOT** store secrets, credentials, or sensitive/regulated data in world-readable
  paths.
- **Do NOT** perform bulk or recursive deletes (`rm -rf`) without confirming with the
  user first.

<!-- Source: lmod.md -->

# Software Modules — Lmod (Gautschi)

Software on Gautschi is provided through **environment modules** (Lmod), not the
system package manager.

## Finding and loading software

- `module avail` — list available modules.
- `module spider <name>` — search for a package and see its versions and
  prerequisites.
- `module load <name>/<version>` — load a specific version; `(D)` marks the default.
- `module list` — show what is currently loaded; `module purge` clears everything.

Load the same modules inside your job scripts that you used interactively, so batch
jobs run in the environment you tested.

## Recommended toolchain

The recommended compiler and MPI stack is **GCC 14.1.0 with OpenMPI**. Check
`module avail` for the exact versions available.

## Prohibitions

- **Do NOT** install software with `apt`, `yum`, `dnf`, or `sudo` — you do not have
  root, and system package managers are not the mechanism here. Use modules, or install
  into user space.
- **Do NOT invent module names or versions.** Verify a package and version exist with
  `module spider` (or `module avail`) before claiming it is available or writing it
  into a job script.
- For Python, prefer the `anaconda` modules and user environments rather than modifying
  a base installation.

<!-- Source: slurm.md -->

# Slurm Scheduler (Gautschi)

All real computation on Gautschi runs as **Slurm** jobs. Never run compute on a login
node (see `unix.md`) — submit it here.

## Every Gautschi job needs four things

A job request must specify **resources**, an **account**, a **QOS**, and a
**partition**. On Gautschi you MUST explicitly set **both the account
(`-A`/`--account=`) and the partition (`-p`/`--partition=`)**; also set the QOS
(`-q`/`--qos=`) and always a time limit (`--time`).

- Discover the accounts you can charge (and their balances) with **`slist`** — do not
  guess an account name.
- Set a realistic `--time`; memory is allocated in proportion to the cores you request.

## Partitions

| Partition | For | Notes |
|-----------|-----|-------|
| `cpu` | CPU jobs (192-core nodes) | QOS `normal` or `standby`; up to 2 weeks (`standby` max 4 h) |
| `ai` | GPU jobs (8× H100 per node) | QOS `normal` or `preemptible`; up to 2 weeks |
| `smallgpu` | Small GPU jobs (2× L40S per node) | up to 24 h |
| `highmem` | Large-memory jobs (1.5 TB nodes) | up to 24 h; job must use more than 48 cores |
| `profiling` | Hardware performance profiling | whole-node; up to 24 h |

## QOS and charging

- **`normal`** — the default; normal priority, charged against your account.
- **`standby`** — access to idle resources at low priority, **not charged**, max 4
  hours. Request it with **`-q standby`** (it is a QOS, **not** an account).
- **`preemptible`** — `ai` partition only; cheaper GPU-hours, but jobs can be preempted
  (killed) to make room for `normal` jobs — checkpoint your work.

## Common commands

`sbatch` (submit a batch script), `squeue -u $USER` (your jobs), `scontrol show job
<id>` (job detail), `scontrol hold`/`release`, `scancel <id>` (cancel), `sinteractive`
(interactive job), `srun` (launch tasks).

## Prohibitions

- **Do NOT** use `--partition=a10` — it is not a Gautschi partition. The valid GPU partitions are `ai` and `smallgpu`.
- **Do NOT** write `-A standby` or `#SBATCH -A standby` — `standby` is a QOS
  (`-q standby`), not an account.
- **Do NOT** emit flags for other schedulers (PBS/Torque `#PBS`, LSF `#BSUB`) — this is
  Slurm.
- **Do NOT** invent partition or QOS names; the valid sets are listed above.
- **Do NOT** submit jobs without a `--time` limit, and **do NOT** `scancel` jobs you do
  not own or run bulk cancellations without confirming with the user.

<!-- Source: policies.md -->

# Policies and Safety (Gautschi)

You are acting as a specific user on shared, audited research infrastructure.
Everything you do is attributable to that user and charged to their allocation.

## Acceptable use

- Use of Gautschi is bound by Purdue IT's Acceptable Use Policy and RCAC's resource
  policies. Stay within the user's approved allocations and project scope.

## Data handling

- **Do NOT** place sensitive, regulated, or export-controlled data on the cluster
  without prior approval, and **do NOT** store any sensitive data in world-readable
  locations.

## Secrets and credentials

- **Do NOT** read, print, or transmit private keys, API tokens, or passwords, and
  **do NOT** write them into files, prompts, or your own context. Treat anything under
  `~/.ssh` and any `.env`-style file as off-limits unless the user explicitly directs
  otherwise.

## Resource stewardship

- No heavy compute on login nodes; submit through Slurm with time limits (see
  `slurm.md`). Watch allocation balances with `slist` — a runaway resubmission loop can
  exhaust an allocation quickly.

## Destructive operations require confirmation

- **Confirm with the user before any destructive or irreversible action:** `rm -rf`,
  mass file moves, permission changes on shared paths, or bulk `scancel`.

## Containers are not a sandbox here

- Gautschi uses **Apptainer** (not Docker). RCAC's Apptainer configuration
  **auto-mounts `/home`, `/depot`, and `/scratch`** into containers, and those mounts
  are writable — running inside a container does **not** protect the user's real files
  from being edited or deleted. Do not assume container isolation.

## Getting help

- Verify AI-generated commands before running them. Report incorrect or harmful AI
  output to **rcac-help@purdue.edu**.

The cluster-side permission policy for Claude Code allow-lists slist/myquota, denies rm -rf/sudo, and points writable scope at Gautschi's scratch:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(myquota:*)",
      "Bash(slist:*)",
      "Bash(sfeatures:*)",
      "Bash(module list:*)",
      "Bash(module avail:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Read(./.env)",
      "Read(~/.ssh/**)"
    ],
    "additionalDirectories": ["/scratch/gautschi"]
  },
  "disableBypassPermissionsMode": "disable"
}

Important

Do NOT run large, long, multi-threaded, parallel, or CPU-intensive jobs on a front-end login host. Always use Slurm to submit your work as a job — this applies to anything heavy an agent does on your behalf, exactly as it does to you.

---

Back to the Gautschi User Guide.