usage

prerequisites

You need access to the Tufts HPC cluster before using tccp. Request access here if you haven't already. The Tufts HPC documentation is a good reference for the cluster itself.

getting started

You need to be on the Tufts network (campus WiFi or Cisco AnyConnect VPN). On campus WiFi, you'll need to approve a Duo push when you connect. The VPN avoids this.

# save credentials (one time)
$ tccp setup

# set up your project
$ cd my-ml-project
# create tccp.yaml (see settings page for reference)

# start a session
$ tccp start

# attach to the persistent shell
$ tccp shell

tccp setup saves your Tufts username and password. Then create a tccp.yaml in your project root (the only required field is container). tccp start allocates a compute node, pulls your container, syncs your files, and starts a persistent shell. tccp shell attaches you to it.

tccp.yaml

Lives in your project root. The only required field is container. See settings for the full reference.

container: pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime
init: "pip install -r requirements.txt"
gpu: a100
time: 4h
output: output/
ports: [6006]

the workflow

tccp gives you a persistent shell on a compute node inside your container. The basic loop is:

  1. tccp start — allocate a node and set everything up
  2. tccp shell — get a shell, run your code interactively
  3. Edit code locally, press Ctrl+S to sync changes and reattach
  4. tccp stop when done — pulls output and releases the node
Terminal $ tccp start Requesting a100 on gpu... Allocation 48291 submitted Running on c0178 Container image cached (NFS) Synced 42 files Running init: pip install -r requirements.txt Shell session ready Session started on c0178 $ tccp shell tccp> python train.py --epochs 50

shell controls

Inside tccp shell, you're in a normal bash session on the compute node, inside your Singularity container with GPU access.

keyaction
Ctrl+SDetach from shell, sync code changes from laptop, reattach. This is the fast edit-sync-test loop.
Ctrl+DExit shell normally. The dtach session ends. Job allocation stays alive for reuse.

If your laptop sleeps or WiFi drops, the shell session survives. Just run tccp shell again to reattach.

port forwarding

Declare ports in your config and they're forwarded to localhost automatically during tccp shell. No SSH tunnel setup needed.

ports: [6006, 8888]

Then open http://localhost:6006 for TensorBoard, http://localhost:8888 for Jupyter, etc.

file sync

tccp syncs your project files to the compute node on tccp start and whenever you press Ctrl+S or run tccp sync.

output

The output/ directory (or whatever you set in config) is bind-mounted from NFS into your container. Files written there persist immediately and are pulled back to your laptop on tccp sync or tccp stop.

project structure

A typical tccp project:

my-project/
  tccp.yaml              # project config
  requirements.txt       # installed by init command
  .gitignore
  train.py               # your scripts
  eval.py
  data/                  # rodata — bind-mounted from NFS
    train.csv
  output/                # synced back from cluster

expected timing

StageFirst runRe-runs
SLURM allocation10–120sn/a (new allocation each start)
Container pull5–15 min0s (cached)
File sync2–30s (full)1–3s (incremental)
Init commandvariesvaries
dtach launch1–2s1–2s
Total~5–20 min~30s–2 min

The first run is slow because the container must be pulled. After that, it's cached (on NFS if cache-containers: true, or on compute /tmp by default). Subsequent tccp start calls mainly wait for SLURM allocation.

good to know

v