Agentic Coding Best Practices

Agentic Coding Best Practices

LLM coding agents — Claude Code, Cursor, Codex CLI, OpenCode, Copilot and others — work well at CSAIL, but our SSH environment does not behave the way these tools assume. They expect to open a connection whenever they want one, directly with no user interaction. Ours requires a DUO second factor and a jump host, and an agent that does not know this will retry until the machine it is running on gets blocked.

This page is written for two readers: you, and the agent you are running. The last section is a block you can paste into your project so the rules reach your tooling directly.

TIG has no position on which agent you use. We do want to make sure the agents you choose work smoothly with the quirks of our environment and don’t overwhelm shared resources.

Set up your SSH connection before you start your agent

This is the single most important thing on this page. Establish your jump host connection by hand, authenticate through DUO, and then start your agent.

If you have not already, set up the recommended client SSH configuration for your platform:

• CSAIL Linux is configured this way by default
• Linux
• macOS
• Windows

That configuration sends everything through jump.csail.mit.edu with GSSAPIAuthentication and a multiplexed ControlSocket, so only the first connection needs DUO. Every later connection — including the ones your agent makes, and connections to different hosts — reuses the socket that is already open.

jump.csail.mit.edu only proxies connections; you cannot log into it directly. To open the socket, SSH to any CSAIL host through it and answer the DUO prompt:

ssh login.csail.mit.edu

Leave that session open, then confirm the socket is live before you start working:

$ ssh -O check jump.csail.mit.edu
Master running (pid=31337)

Once you see Master running, start your agent. It will connect without ever seeing a DUO prompt.

If you move between networks — closing a laptop at home and opening it in Stata, for example — the existing socket breaks and new sessions hang before connecting. Remove it and reconnect:

rm ~/.ssh/cm_socket/*

This is always safe to run; it just means the next connection will need DUO again.

When SSH fails, stop — do not retry

An agent that cannot connect will usually assume the failure is transient and try again. At CSAIL — and most other places, honestly — that trips security safeguards and gets you locked out.

Repeated failed SSH connections trigger sshguard, which blocks the source address — the machine your agent is running on, not your account. The first block lasts 2 minutes. Every subsequent block is twice as long as the one before it.

Caught immediately, this clears itself quickly. Left running, doubling does what doubling does, and you are locked out for hours or days.

To get unblocked, stop the failing process first. Kill the agent, or whatever else is retrying, and confirm nothing is still attempting to connect. Then email help@csail.mit.edu. Asking us to clear a block while the agent is still hammering away will get you re-blocked for longer almost immediately.

What an agent should do instead, when an SSH connection fails:

• Stop. Do not retry the same connection.
• Do not try a different CSAIL host, and do not fall back to password authentication.
• Tell the user the jump host connection needs to be re-established, and wait for them to do it.

A human answering a DUO push takes a few seconds. An agent working around it can cost the whole office an afternoon.

Where your agent may run

Run the agent on your laptop

Your laptop drives the agent; CSAIL systems run the jobs. This is the right answer in almost every case. Write and edit code locally, sync it to the cluster, and use the login node only to submit your jobs.

If you don’t need direct access to your data storage from your agent (only your code needs access whiel executign remotely) this is the most convenient work flow.

Run the agent on your workstation

CSAIL Ubuntu workstations have access to the same NFS and AFS storage systems as our compute clusters, and are generally the ideal place to develop if you have one.

If you are not in the lab you can ssh in to your workstation and use it as a private compute node. This has good access to data and is usually private or lightly shared so you don’t need to contend with others use.

Run on group compute nodes

Many research groups own their own compute servers. Ask within your group whether you have access to private compute resources and whether they are appropriate for agentic work.

Similar to the workstation model but usually with faster data access and more raw power but with more people sharing that power. Dependent on the particualr group you are in if any reosurces of this class are available, ask your lab mates.

Schedule to run on a cluster compute node

If your group doesn’t have dedicated compute resources or a workstation available to you, and you need to run closer to CSAIL storage systems, you can use the Slurm queueing system to schedule time on a shared compute node.

Allocate a compute node and attach to it. Any Slurm node on which you have a running job will let you SSH in directly for as long as the job lasts. Slurm nodes are reachable only through the jump host, so establish that connection first:

$ salloc --partition tig-cpu --qos tig-main --time 01:00:00
salloc: partition tig-cpu, qos tig-main
salloc: Granted job allocation 665460
salloc: Nodes groenig-5 are ready for job

Point your agent or remote editor at that node — groenig-5 in this example. Prefer a CPU partition unless your interactive work actually needs a GPU; there is no reason to hold an idle GPU while you edit files. See SSH to compute nodes.

Not on the Slurm login nodes

Not on the public login servers

login.csail.mit.edu is for computationally non-intensive work — reading mail, editing a file, compiling something small. Agents are very greedy with their indexing, and if run in the wrong place (the top level of AFS or a large NFS file tree) they can overwhelm the login node and make it unresponsive for everyone.

Be kind to shared resources

Please be kind to your fellow researchers here. Agents generate a lot of small file operations, and over NFS that amplifies into real slowdowns for everyone sharing the filesystem. Keeping agents on your own hardware keeps the shared resources available for the work that can only happen there.

Long runs: keep your credentials alive

Kerberos tickets and AFS tokens expire by default. When they do, an agent in the middle of a long task sees something that looks exactly like an authentication failure — and starts the retry loop described above.

If you expect an agent session or a compute job to outlive your tickets, wrap it with one of TIG’s renewal tools — longtmux, longjob, longsession, or standard krenew/k5start. All of them live in /usr/local/csail/bin. See the Guide to Long-Running and Uninterrupted Sessions for which one fits your case.

Storage: where agents read and write

Agents index whole directory trees and take locks on the files they touch. Where that work lands matters wherever your agent is running, not just on the cluster.

• Prefer NFS for an agent’s working tree. It handles the many-small-operations pattern agents produce better than AFS, and there are no tokens to expire mid-task. The tradeoff is reach: NFS is available only on TIG-managed systems on the CSAIL network, and cannot be mounted on a laptop or from off site.
• AFS provides better security and off site access, at a cost. The AFS client installs on your own machine and works over any internet connection, and AFS access control is much stronger than NFS’s. The costs are tokens that expire, ACLs that have to be right, and slower going for tools that index a tree or take a lock. These are tradeoffs, not prohibitions: agents run in AFS perfectly well when they are scoped properly.
• Scope the agent to the project it is working on. Start it in a working copy of that project so it never tries to index your whole home directory — or worse, something higher up the tree. This is what separates an agent that works fine in AFS from one that makes VS Code fail there; see the .vscode-server notes. The same applies to a large NFS trees.
• Node-local scratch is the fastest storage available, but it is reachable only from that machine and is deleted on reboot or sooner. Point sandboxes, caches and build trees at it or at local /tmp, on slurm nodes you start with a local home directory of /tmp/home/$USER which is usually the best place for slurm jobs to write locally. Always remember to write anything you want to keep back to NFS or AFS.

On Slurm specifically, AFS tokens are not forwarded into jobs at all, so files in your AFS home are simply not there while the job runs. Use NFS, and write job output there with --output=. See Storage in Slurm.

Data handling and secrets

Every prompt an agent sends to a hosted model is a disclosure. Decide deliberately what is allowed to leave, rather than letting an agent’s default context gathering decide for you.

• MIT classifies data as Low, Medium or High risk — see Data Security. Low risk data needs no approval, so any service you choose is fine.
• Parley is the only LLM API approved for Medium risk data. No other service is approved for it, so if your data is Medium risk, Parley is the option.
• High risk data should never be on CSAIL research systems at all, and must never be sent to any model.
• Unpublished results, subject data, and anything covered by a data use agreement deserve an explicit decision before they go anywhere near a hosted model.
• Agents read broadly. Use your tool’s ignore mechanism to keep ~/.ssh, Kerberos keytabs, .env files, API keys and other credentials out of the agent’s context, and keep secrets out of the repository in the first place.

Model access: Parley

MIT provides Parley, a generative AI platform that runs inside MIT’s environment. The models it reaches are covered by an Institute licensing agreement, and MIT data is not used to train external AI systems.

Parley offers a web chat interface an API.

Tell your agent the rules

Most agents read a Markdown file at the root of your project when a session starts — AGENTS.md for Codex, OpenCode and a growing number of other tools, CLAUDE.md for Claude Code. Some tools also read a user-level file that applies to every project. Putting the CSAIL constraints there means the agent knows them before it tries its first connection.

Paste this into that file:

## CSAIL environment rules

### SSH
- SSH to any *.csail.mit.edu host is proxied through jump.csail.mit.edu and
  requires DUO multi-factor authentication.
- The user must establish this connection by hand before you start work.
  You cannot answer a DUO push. Do not attempt to authenticate yourself.
- Before relying on SSH, you may verify the shared connection with:
      ssh -O check jump.csail.mit.edu
  "Master running" means you are good to go.

### If an SSH connection fails, STOP
- Do NOT retry the connection.
- Do NOT try a different CSAIL host.
- Do NOT fall back to password authentication or public-key authentication.
- Repeated failed connections trip sshguard, which blocks this machine's IP
  address for 2 minutes, then doubles the block on every repeat. This affects
  everyone sharing the address, not just this user.
- Instead: tell the user the jump host connection needs to be re-established
  (`ssh login.csail.mit.edu`, answer DUO, leave the session open) and wait.
- The same applies to expired Kerberos tickets or AFS tokens: report it,
  do not retry.

### Where you may run
- Prefer running on this local machine. Sync code to CSAIL and submit jobs
  there; do not move yourself onto shared CSAIL hosts.
- NEVER run on slurm-login.csail.mit.edu. It is for job submission only and a
  reaper script kills editor and agent processes there.
- NEVER run on login.csail.mit.edu. It is for lightweight interactive use only.
- If work must happen next to cluster data, ask the user to allocate a node
  (`salloc --partition tig-cpu --qos tig-main --time 01:00:00`) and connect to
  that node instead.

### Storage
- Write code, data and results to NFS when it is available; otherwise use a
  local working tree or a scoped project directory in AFS.
- Work inside the project directory you were started in. Do not index, scan,
  or bulk-write a home directory or anything above it.
- Put sandboxes, caches and build artifacts in local /tmp.
- AFS tokens expire, and are not available inside Slurm jobs at all; files in
  AFS will not be there while a job runs.

### Secrets
- Never read, print, commit, or transmit ~/.ssh contents, Kerberos keytabs,
  .env files, or API keys.
- Do not send unpublished research data or data under a use agreement to a
  hosted model without asking the user first.

Trim it to what applies to your project. An agent that never touches Slurm does not need the Slurm rules, but the SSH section is worth keeping in any project that reaches lab systems at all.

Getting help

As always, email help@csail.mit.edu if you have any questions or need assistance. If you’re unsure whether an issue is a TIG issue or an MIT issue, ask anyway — we’re happy to point you at the right place.

For Parley accounts, keys and credits, email parley-support@mit.edu.