Trellis Tools · Walkthroughs

Walkthroughs › HPC Terminal

HPC Terminal

Start the big job, close the laptop, pick it up anywhere

A terminal on the lab's HPC machines, in the browser. Save a connection once and open it from a link; log in with your password, start the alignment, close the page, and come back to it from home with what it printed meanwhile. Scripts and whole sessions go into your Lab Notebook under the day they ran. The heavy work runs on the HPC machine; the suite only carries the keystrokes.

Versions Screens from 15 November 2026, with Trellis 2.54.0 and HPC Terminal 0.2.0. Yours are under About in the tool's own header. If yours are newer, a screen here may have moved on; if they are older, something on this page may not be there yet.

Before you start

  1. Have Trellis 2.53 or later running (install). The HPC Terminal is part of the suite and appears on its home page.
  2. An administrator adds the lab's HPC machine once: on the HPC Terminal page, under The lab's machines (chapter 5).
  3. Have an account on that machine, with its user name and password, and a one-time code if it asks for one.
  4. The HPC machine must accept SSH from the Trellis server. If it only allows the institute's network or VPN, ask its administrators to allow the server.

The screens here use a demo cluster login node, hpc01, and the demo account ada: none of it is a real lab's data.

1

Save a connection

Who you log in as, on which machine: saved once, opened from a link.

  1. On the Trellis home page, click HPC Terminal.
  2. Under Your connections, choose the Machine and type Your user name there.Only the machines an administrator has added are on the list. Give the connection a name if you like; otherwise it is called user@machine.
  3. Leave Keep my work in tmux on the machine and Record each session in my notebook when it ends ticked, unless you have a reason not to (chapters 3 and 4).
  4. Click Save the connection.It appears in the list with Open and Copy link. The link opens the terminal and connects: bookmark it, or put it on a notebook page.

Your password is never part of a connection. It is asked in the terminal each time, goes to the machine, and is not kept anywhere.

HPC Terminal
Your sessions and connections, each a click from the terminal.
2

Log in

As with any SSH client, but the password goes in a box of the page's own.

  1. Click Open, or the connection's link.The terminal says Connecting to ada@hpc01 … and the machine asks for your password.
  2. Type or paste it into the Password box above the terminal, and press Enter.The box sends exactly what you typed, with your browser's own handling of the keyboard and your password manager. If the machine asks for a one-time code next, the box asks for that too.
  3. You are on the machine. With tmux on, a green bar at the bottom says [trellis]: that is the tmux session your work runs in.

Three wrong answers end the attempt, and after five refused logins in ten minutes the terminal makes you wait a few minutes. Many HPC machines also turn an address away for a while after failed logins, so if a log-in suddenly cannot connect, wait a few minutes.

Ctrl-C at the password gives up the log-in. End session closes the connection at any time.

The password box
The machine asks; you answer in the page's own box.
On the machine
Logged in, inside tmux, with the job script on screen.
3

Leave it running, come back

The point of it: start the work here, look in on it from anywhere.

  1. Start the work. For anything long, give it to the machine's scheduler: sbatch jobs/align-T2.sh, then squeue -u ada to watch it.Most HPC centres stop long work run straight on a login node.
  2. Close the page, or the laptop.The session carries on, on the Trellis server, however long you are away. It only ends when you end it, or it ends on the machine.
  3. Later, from any computer signed in to Trellis, open the connection's link again, or Open it under Your sessions.The terminal first shows what the session printed while you were there and while you were away (its last 12,000 lines or so), then carries on live.

The page locks after 5 minutes away. With no key pressed and no mouse moved for five minutes, a terminal page lets go of the session, clears the screen and signs you out of Trellis, so a computer left unattended is not a way onto the lab's machines. It warns you 30 seconds before. The session does not stop: sign in again and you are back in it.

tmux keeps your work through anything. If the Trellis server is restarted or updated, its connections end, but the work in tmux carries on on the HPC machine: opening the link logs you in again and puts you back in the same tmux session. tmux's own history (Ctrl-b then [, q to stop) holds what scrolled past.

One browser at a time. Opening the session somewhere else takes it over; the first browser is told, and given the other's address. If that was not you, end the session and tell an administrator.

4

Into the notebook

What you ran, kept under the day you ran it.

  1. Recorded for you. When a session ends — you end it, it ends on the machine, or the server restarts — what it showed becomes a page under today in your Lab Notebook, with the text attached as a file.A session still running at midnight gets that day's part written under that day and carries on; each day's page says where it continues. The terminal says when it has been recorded.
  2. A script, by hand: Save a script to the notebook…, then pick the file on the machine.The folder opens at your home directory; click into folders, or type a path. The script is shown, the page title is filled in, and the day is the one the session started; the day the file was last changed is offered too. Add a note, and Save to the notebook.
  3. The session's text, by hand: Save the session’s text…, at any time, under a day you choose.

What goes in a record: whatever the machine showed. Passwords and one-time codes are never shown, so never recorded. Colours and progress bars are tidied away; a full-screen program (an editor, top) comes out jumbled. Turn recording off for a connection where data you would not keep in a notebook is printed.

If the notebook cannot be reached, the terminal says so and the text stays in the session, to save by hand.

Save a script to the notebook
A job script picked on the machine, ready for today's page.
5

For administrators and lab leads

The lab's machines, the networks they are on, and who is connected.

  1. Add a machine (administrators): under The lab's machines, give a name, its host name or address and SSH port, and Add the machine.The terminal reads the machine's host key and shows its fingerprint. Compare it with the one the machine's administrators give (ssh-keygen -lf on its host key); if it differs, remove the machine. Every connection is checked against that key, and a machine answering with another is not logged in to.
  2. Allow its network. The terminal only reaches machines on the networks the suite allows — the lab's HPC subnet, such as 192.168.2.0/24; until set, private networks only, never the internet.From Trellis 2.55, administrators set these on the dashboard, under HPC Terminal, with a note for each, and a change counts at once. Before that, and as an outer limit the dashboard cannot go beyond, they are set on the server in .env (TERMINAL_ALLOWED_NETWORKS, TERMINAL_NETWORK_LIMIT).
  3. See open sessions. An administrator sees everyone's, under Everyone's open sessions; a lab lead or lab admin sees their labs' members', under Open sessions in your labs.Who is connected to which machine, since when, and whether a browser has it open and from which address — never what is on their screen. End closes a session's connection; its owner sees who ended it, and what runs in tmux carries on.
  4. A machine reinstalled? Read its key again shows the key it gives now beside the old one, to accept after checking it.
HPC Terminal · as an administrator
Who is connected, and the machines with their host keys.
6

What is kept, and who sees what

A terminal onto the lab's machines deserves care: here is what it does, and does not, do.

  • Kept: the lab's machines and their host keys, and each member's connections (user name, machine, name), in the terminal's own database, backed up every night with the rest of the suite.
  • Never kept: passwords, one-time codes, private keys. No SSH agent is used.
  • Held while a session is open: its recent output, in memory, for coming back to it. Gone when it closes.
  • Nothing runs on the Trellis server. The terminal only reaches the machine you connect to, and only within the allowed networks. It runs on a Docker network of its own, shared only with the proxy and the notebook, read-only and with no privileges.
  • Logged for whoever looks after the server: who started a session on which machine, each time a browser opens it and from which address, each step of a log-in (the question, never the answer), and how it ended.

For a limit that holds even if the service were compromised, the server's firewall should let the terminal's container out only to the same networks. The terminal's README has the rule for a Linux server.

Where next