IDEAL Lab IT & Research Computing Passport

This is the IDEAL Lab's practical onboarding for GitHub, Python, research data, AI coding agents, Blade, and Euler. You can read this page on GitHub before installing Git, Obsidian, Python, or an editor.

The main systems have separate jobs:

You do not need to understand or configure all of them now. The local Passport selects only the relevant topics and introduces each one before use.

[!NOTE] For the 2026 semester, this handbook remains in IDEALLab/onboarding-IT, while the official exercises and launcher run in the maintainer-owned soheylm-passport-sandbox GitHub group. Despite its name, this is the active semester deployment. Students continue with their personal GitHub accounts and do not join that group. Each generated public learning record belongs to the student's own GitHub account.

New To The Lab? Start Here#

[!IMPORTANT] Use one starting guide only. Open the illustrated first-contact guide, then run the real guide locally with gh passport start. Do not begin by browsing folders or cloning this handbook.

The illustrated guide starts by showing how to open a terminal and run a command on Windows, macOS, or Linux. A terminal is a text application; PowerShell, zsh, and Bash are shells inside it that read commands. If those words are new, use that guide rather than starting with the command blocks below. On macOS and Linux, open the application named Terminal; it starts zsh or Bash for you. Do not look for a separate Bash application. The text-only first-contact guide gives the same sequence when JavaScript is unavailable. The original linear mastery path remains available for reference and points readers back to the current Passport.

The abbreviated first-contact sequence is below for readers who already know how to use a terminal. Run one step at a time.

1. Check the active GitHub account before changing any login:

gh auth status --active --hostname github.com

If it names the intended personal account, continue at step 3. If no account is active, continue at step 2. If the intended account is already stored but a different account is active, use the account-switch instructions in the first-contact guide.

2. Only when no intended account is active, sign in through the browser and repeat the status check:

gh auth login --hostname github.com --web --git-protocol https
gh auth status --active --hostname github.com

Continue only when the status command names the intended account.

3. Install the tested Passport launcher:

gh extension install soheylm-passport-sandbox/gh-passport --force --pin v0.12.1

This command is needed for the first installation. Future compatible launcher updates appear inside the local Passport as Update and reopen. The update keeps the current lesson, draft answers, and GitHub submissions.

4. Start the local Passport:

gh passport start

After you confirm what will be public, the launcher creates or safely reuses:

• a local browser interface with one current lesson;
• a resume record stored only on your computer;
• a public learning record in your own GitHub account containing only generated answers and fictional exercise files;
• a separate visible practice folder when a lesson needs real files.

The learning record is public. Your GitHub username is necessarily visible because it owns the record. Beyond that public identity, use only fictional exercise values and results with private information removed. Never submit credentials, ETH usernames or email addresses, student numbers, other private identifiers, real logs, screenshots with private information, research data, or confidential project details.

Returning Later#

Moving to another computer or operating system? Follow Continue On Another Computer to resume the same Passport and recheck this computer without changing completed grades.

Open PowerShell on Windows or a terminal on macOS/Linux. From any folder, run:

gh passport open

Do not reinstall, clone again, or search for a special working directory.

How Learning Is Recorded#

Every lesson ends with the same visible loop:

1. complete the assigned exercise;
2. use Check my work and correct any local finding;
3. review the generated public content and confirm it contains no sensitive data;
4. use Submit lesson once;
5. continue when the trusted automatic result appears.

The launcher manages the background learning record. The Git lesson introduces each Git concept and command only when you need it; no Git knowledge is assumed before then.

The supervisor and reviewer act asynchronously. Nobody must remain online while a learner works.

Lessons Match Your Work#

Everyone completes the universal safety core. gh passport start asks which activities apply and adds any earlier lessons they require automatically.

Degree and job title do not determine your lesson list.

Five Rules That Prevent Most Incidents#

1. Never share an ETH password, token, SSH private key, recovery code, or confidential personal data with another person or an AI tool.
2. Never add datasets, saved model states (checkpoints), generated results, local secret files such as .env, personal settings, or real system logs to Git history unless the project explicitly requires and protects them.
3. Check the machine and shell label before pasting a command.
4. On Euler, request the smallest reasonable CPU, memory, GPU, and time; use the accounting checks taught in the Euler lessons before increasing resources.
5. Review every AI-generated diff and command. Work performed under your account remains your responsibility.

If Blocked#

Run read-only diagnostics from any folder:

gh passport doctor

Keep the exact non-secret error. Do not change SSH keys, permissions, PowerShell policy, antivirus settings, or Git settings unless the linked recovery guide explicitly tells you to. Use the symptom-based troubleshooting index or the asynchronous help link shown on the local progress page.

Using An AI Agent On A Lab Project#

Give your assistant the lab context before it works on a research project. Follow Give your AI agent the lab context for the copy-paste prompts, project setup, and checks. Use this after your relevant Git and AI lessons; it is not another Passport starting guide.

Reference After Onboarding#

Maintainers#

Curriculum, site, and generated artifacts are versioned here. Public exercises live in soheylm-passport-sandbox/passport-exercises; the cross-platform launcher lives in soheylm-passport-sandbox/gh-passport; trusted assignments, checks, operations, and completion records live in private soheylm-passport-sandbox/onboarding-control. The active identities are defined once in platform/deployment.json; generated repositories and launcher builds must match that profile.

See architecture, deployment, and release qualification. Human-only claims remain explicitly separated in the pilot checklist.