AI Agent Guidelines

These guidelines describe how to use AI agents, coding assistants and other autonomous tools responsibly on REANNZ HPC systems. They are advice, not policy. The Acceptable Use Policy still applies to everything an agent does under your account.

These guidelines do not cover AI or machine learning as the research workload itself.

Principles¶

You are responsible for anything an agent does under your account, in the same way you are responsible for any other process you run.
Understand the basics of operating an autonomous agent safely, such as the risks of supply chain attacks and prompt injection.
Agents should follow the same shared-system etiquette expected of any other user process.
Take reasonable precautions to protect the platform, other users and REANNZ when operating an agent.

Data and privacy¶

Most AI agents send your prompts, the files they read and the output of the commands they run to the provider's servers for processing, which are usually overseas. This happens whether the agent runs on your own computer or on the cluster.

Only let the agent read code and data that its owner has approved for sharing with a third party (see the Acceptable Use Policy), and follow any data conditions agreed for your project (see the Access Policy). Personal or health information, Māori data, and data under ethics, contract or export conditions often cannot be shared.
Project directories are shared. Start the agent in a directory that holds only your own work, so that it does not read other project members' files.
Some software licences do not allow the source code to be shared with third parties. Check the licence conditions of any third-party code before the agent reads it.
Check your account's privacy settings with the provider to see how long your conversations are kept and whether they are used to train models.

Which account to use¶

Ask yourself: would the agent keep working, or be able to start, if you closed your laptop or logged out? If so, it needs a service account.

You may run an agent under your own account when you started it yourself, in a terminal or editor you are using, on the cluster or on your own computer, and you are there to approve what it does. This includes an agent on your own computer that runs commands through a login session you opened. Leaving it waiting for your approval while you step away is fine.

An agent needs a service account when it:

runs in a batch job, scrontab, cron or CI, or in an agent's non-interactive mode,
keeps working in tmux, screen or another detached session after you log out,
can open its own connections to the cluster, for example with your SSH key or from a scheduled or cloud-hosted agent.

Running such an agent under your own account breaks item 12 of the Acceptable Use Policy, which does not allow automated tools to log in with your credentials, or use your login session when you are not present.

Service accounts¶

A service account is a separate user on the cluster for one application, such as an agent. It limits what the agent can reach, and how much harm it can do if something goes wrong.

To request a service account, Contact our Support Team.

Credentials and access¶

Do not let an agent read your passwords, SSH keys or tokens, wherever it runs. Anything the agent reads is sent to the provider. Use the agent's own settings to block access to files such as ~/.ssh, and keep credentials out of the directories it works in.
If an agent reads or prints a password, SSH key or token for REANNZ systems, treat it as exposed and report it, as required by the Acceptable Use Policy. Contact our Support Team.
An agent on your own computer will not see guidance installed on the cluster, so give it these guidelines yourself.
Do not expose an MCP server or open a reverse tunnel from a REANNZ HPC system outward. This includes tools such as ngrok, cloudflared, VS Code tunnels and remote-control features of AI tools. The Acceptable Use Policy does not allow tunnels that let connections from outside reach the cluster without logging in. An agent on your workstation connecting in to a service on the cluster is fine, but not the other way around. Tunnels within the cluster, such as forwarding a port from a compute node to a login node, are fine.

Working on the cluster¶

Approve what the agent does. Review commands that change or delete files, cancel or submit jobs, or install software before they run, and do not use a mode that skips approval for them. Letting read-only status checks such as squeue --me run without approval is fine.
When polling commands that use shared resources (filesystem operations, squeue, sacct), leave generous delays between calls, for example sleep 60 between squeue --me calls.
Run only one agent session at a time, unless support has agreed to more.
Use squeue --me and ps -u $USER to keep the agent's view limited to your own work.
Under the Acceptable Use Policy, REANNZ can stop any process that disrupts the service, including agent processes.

Best Practice¶

Do¶

Scope status checks to your own work: squeue --me, sacct -j <jobid>, ps -u $USER.
Poll on the order of tens of seconds apart rather than in a tight loop.
Submit jobs in small, bounded batches, job-arrays or dependency chains (sbatch --dependency=afterok:...) instead of many independent submissions.
Review job scripts before they are submitted. Check the resources requested (--time, --mem, --ntasks, GPUs), because every job uses your project's allocation and Fair Share.
Point file operations (find, grep, du) at specific known paths rather than whole shared parent directories.
Run CPU or memory heavy work as a job, not on the login node. Compiling with a few cores on the login node is fine. I/O heavy work slows down any node it runs on. The login node is preferable for it, but take care not to degrade its performance.
Give an agent a narrow working directory rather than broad filesystem access.
Commit your work with git before asking the agent for large changes, so you can review and undo them.
Review the packages or dependencies an agent proposes to install before it installs them, and pre-install where practical.

Don't¶

watch -n 1 squeue or while true; do squeue; sleep 1; done, sub-second polling of the scheduler.
sacct --allusers -S <date> full-cluster accounting queries.
Unscoped recursive find/grep -r over /nesi/project, /home or similar shared filesystems.
for i in {1..N}; do sbatch job.sh; done speculative bursts of job submissions while iterating.
top/ps aux refreshed continuously and unfiltered across all users.

Support¶

REANNZ does not provide support for third-party AI tools. Before raising a support ticket, verify any commands an agent has generated against the relevant documentation, and check that nothing has been hallucinated. Agents can look up this documentation themselves, starting from the index at https://docs.nesi.org.nz/llms.txt.

An unofficial AI skill for responsible operation of the REANNZ HPC can be found at nesi-support-skill.

Research Integrity¶

We recommend that use of AI in research conducted on REANNZ HPC systems follows the Royal Society guidelines.