Using Your Desktop¶

For everyone

Every eLab account can use a desktop — this is the guide to start with. What else you can do depends on the roles your account holds; the home page lists each role and its guide.

Signing in¶

Go to https://<your-elab-address>/portal and sign in with your eLab account. The portal is where you start, stop, and schedule desktops and see your remaining credits.

Starting a desktop¶

Choose a desktop type: CPU (general analysis) or GPU (deep learning and other GPU-accelerated work).
Click Launch. A CPU desktop is usually ready in a couple of minutes. A GPU desktop can take around ten minutes from cold — the platform is provisioning dedicated GPU hardware for you.
When it's ready, the desktop opens in your browser tab.

One desktop runs at a time. Stop it from the portal when you finish — credits are drawn while the desktop runs, whether or not you are connected.

What is installed on each desktop type is listed in Tools on the Desktop, and how to install Python and R packages in Installing Packages.

Your eLab team sets which image each desktop type starts from. If your account holds the image-manager role, a Your desktop image panel lets you choose a different one for your own desktops — see Choosing Your Own Image.

Idle desktops stop themselves¶

A desktop that is left alone is shut down automatically so it does not spend your credits for nothing. The rule is deliberately generous: the desktop must have seen no keyboard or mouse input for twelve hours and be doing nothing — CPU (and GPU, where fitted) below 10% — for the whole of that time. A long-running computation keeps a desktop alive even with nobody at the keyboard; only a desktop that is both untouched and idle is stopped.

Your files are safe either way: the home directory persists, and the next launch picks up where you left off. If you are going to leave a job running overnight, this is nothing to worry about. If you are going to leave a desktop idle overnight, stop it yourself and save the credits.

If it doesn't start¶

The status tells you which of two things is happening. Waiting for a machine means one is being prepared for you — normal, and worth the few minutes it usually takes. Waiting for capacity means none has been free for a while: everyone's desktops may be using the hardware the eLab has, and yours starts as soon as one frees up.

Either way you are not being charged. Credits are drawn only once the desktop is running, so a desktop that never starts costs you nothing.

If nothing has happened after about half an hour the portal stops waiting, removes the desktop and tells you so on your dashboard — again without using any of your credits. That message is worth reading before you try again: if it says there is no spare capacity, a second attempt will most likely queue behind the same shortage, and the eLab team are the people who can tell you when more will be available.

Schedule a start

You can schedule a desktop to start at a set time (for example, before a morning workshop) so it's warm when you arrive. Credits are drawn from the scheduled start, connected or not, and booking a GPU desktop shows the same warning as starting one, asking you to confirm.

The git service¶

Where your eLab offers it, a Gitea git service runs inside the platform at https://<your eLab address>/git — open it in your desktop's browser and sign in with the same eLab account you use everywhere else. It is reachable only from inside eLab desktops, not from the internet, so clone and push from a desktop terminal:

git clone https://<your eLab address>/git/<owner>/<repo>.git

The first git push opens a browser window for the usual eLab sign-in; after that your desktop remembers you for the working session.

Use Sign in with OpenID Connect on the Gitea login page; there are no separate git accounts or passwords.

The full desktop image also carries a Git shortcut on the desktop and in the applications menu that opens the service directly.

Your credits and budget¶

Desktop time draws on your project's budget through credits. You start with a balance of credits, and every desktop draws them down at its own rate for as long as it runs: each launch button shows its rate in credits per hour, and the dashboard tells you roughly how many hours your balance buys on each kind of desktop. A GPU desktop costs more per hour than a CPU desktop, so the portal shows a warning and asks you to confirm before it starts one. Cancel is the default, so pressing Enter leaves it unstarted.

Nothing is drawn while a desktop is waiting for a machine, only once it is running, and stopping it stops the drain. If you run short, your eLab administrator can add credits; if the project's budget is running ahead of plan, the portal may scale everyone's remaining credits down, and it says so on your dashboard when it does.

Your files¶

Home directory — your personal working space. It persists across desktop sessions and restarts; anything you leave there will be waiting next time.
/imports — your own approved airlock imports, read-only, one directory per request. Only you can see them — see Importing & Exporting Data.
/shared — read-only content shared with everyone in the eLab, placed there by your eLab team.
/review-ro — visible only to airlock reviewers: files currently under review, mounted read-only for tool-based checking.

In a teaching eLab, the staff responsible for course data can see and change everyone's home directory, so they can mark work, fix something that will not run, or put a file where you will find it. Treat your home as visible to your course team rather than private to you. This does not apply in a secure-data eLab, where nobody can reach another person's home at all.

Desktops themselves are disposable — install-into-home or request additions through your operator rather than relying on system-level changes surviving a restart.

Material published for you¶

Your eLab team makes data and material available in two ways. Content everyone only needs to read or analyse — a curated dataset, reference data, documentation — appears in /shared. Material you need to edit — a template analysis, notebooks, assessment files — is delivered instead: a copy is placed in your home directory so that you can work on it. /shared holds the read-only original; your copy is yours.

A delivered copy arrives automatically when you start a desktop. If you are told something new is available while you are already working, use the Get materials icon on your desktop, or run:

elab-materials            # fetch anything new
elab-materials --list     # what has been published, and what you already have

Your edits are never overwritten or deleted by this. If material is revised, files you have changed are left alone (or saved beside the new version as …yours-<date>, if your team chose that), and only untouched files are refreshed. If material is withdrawn, anything you have edited stays. If you want a clean copy of something you have changed, elab-materials --again <name> puts one beside your own rather than over it.

If your eLab spans more than one site¶

Some eLabs run desktops at more than one site (for example, one per region) behind a single portal. There is only ever one address to sign in at, and your dashboard tells you which site your desktops run at. Nothing else changes: you launch, connect, stop and book from the same page, and your credits are one balance wherever your desktop runs. The desktop itself opens in a browser tab at its own site's address, which is why the Connect button may take you to a different address than the portal's.

If another site is switched off or can't be reached when you first launch a desktop, the portal checks whether any of your files are there before starting yours, and your dashboard says "Checking whether any of your files are on another site" meanwhile. The desktop starts by itself once the check completes.

Occasionally the eLab team will move a group of users to another site to balance capacity. When that happens to you:

Your dashboard names the new site the next time you sign in.
The first time you launch a desktop there, the site first copies your home directory across from the site you came from. Your dashboard says "Your files are being transferred from your previous site", and the desktop starts by itself once the copy finishes. This can take a few minutes for a large home directory. You do not need to launch again.
Your account, roles, credits and bookings are unchanged, and your files arrive as they were.

Airlock requests are handled by the site where they were made, so finish any request in progress before a move where you can, or ask the eLab team about it afterwards. The Airlock link at the top of the portal always points at your current site's airlock.

If your site cannot be reached, the dashboard says so. A desktop that is already running carries on, but nothing can be started or stopped from the portal until the site is back.

Working with the desktop¶

If the desktop shows a connection error, retry once before raising a ticket — transient reconnects usually recover immediately.

Moving files in and out¶

How you do this depends on your eLab:

Secure-data eLabs switch off the clipboard and file transfer. Files move in and out only through the airlock, where every transfer is reviewed — see Importing & Exporting Data.
Teaching eLabs let you move files directly between your own computer and your home directory, and copy and paste text, with no request or review.

In a teaching eLab, everything happens in the desktop's browser tab:

Open the menu. Press Ctrl+Alt+Shift (Control+Option+Shift on a Mac); press it again to close it. On a touchscreen, swipe right from the left edge of the screen.
Upload. Drag files from your computer onto the desktop window. They land in your home directory, and a notice shows the progress. To put them in a particular folder instead, open the file browser (step 3), go to that folder and click Upload Files.
Download. In the menu, click the file system listed there to open the file browser. Double-click a folder to open it, and double-click a file to download it; it arrives like any other browser download.
Copy and paste text. Text you copy inside the desktop appears in the menu's clipboard box, where you can copy it out. Text you type or paste into that box can be pasted inside the desktop. Some browsers keep the two clipboards in step by themselves once you allow it.

Worth knowing:

The file browser shows only your home directory. To download something from /shared, copy it into your home first, for example with cp /shared/<file> ~/ in a terminal.
A folder cannot be downloaded in one go. Zip it into a single file first, for example zip -r project.zip project in a terminal, and download that.
Transfers go through your browser, so they suit everyday files; very large ones are slow.
Someone watching a screen share cannot move files in or out.

How much memory you have¶

Your desktop has a fixed memory limit, for example 20 GiB. Tools such as top, free, the system monitor and Python's psutil report the whole machine your desktop runs on instead. That can be far more memory than your limit, plus swap space your desktop cannot use. To see your own limit and how much of it you are using, run this in a terminal:

echo "limit:  $(( $(cat /sys/fs/cgroup/memory.max) / 1024**3 )) GiB"
echo "in use: $(( $(cat /sys/fs/cgroup/memory.current) / 1024**3 )) GiB"

A program that needs more than your limit is stopped: in Jupyter, the kernel dies and restarts. Work on large data in chunks, or ask your administrator whether a larger desktop is available.

Showing your screen to someone¶

When you need help with something on your desktop, you can let one colleague watch your screen instead of describing it. Nobody can look at your desktop unless you invite them — there is no way for an administrator to attach to your session.

With your desktop running, choose Share my screen (view only) on the portal. You get a link to send to the person helping you, by whatever means you normally contact them. While a share is active the portal shows that you are sharing, and once someone opens the link it shows who is watching.

What the person can and cannot do:

They see your screen, live.
They cannot type, click or control anything.
They cannot copy text out, or move files in or out.

The link is deliberately limited. It works once — after one person opens it, it stops working, so a link that gets forwarded or seen by someone else is useless. It expires after 10 minutes if nobody uses it. And whoever opens it must sign in to the portal first, so only members of this eLab can ever view your screen, and the platform records who did.

Choose Stop new viewers when you are finished. This is worth understanding precisely: it stops the link being opened again, but it does not disconnect someone who is already watching. Once a person has opened the link their viewing session is their own, and it continues until they close it or it times out. The only way to end an active view immediately is to stop your desktop.

So if a name you did not expect appears, revoking the link is not the remedy — stop your desktop, and tell the eLab administrators. Sharing also ends by itself when your desktop stops.

Because your screen may show confidential data, treat a share link like the data itself: send it to the one person who needs it, and finish the session once they have seen what they need.