Lab 0: Linux Crash Course¶

Tasks¶

• Obtain a Linux Virtual Machine
  • Install a hypervisor on your computer
  • Create a new virtual machine in the hypervisor
  • Install a Linux distribution in the virtual machine
• Linux Basics
  • Command Line Interface (CLI)
  • Linux File System
  • Package Management
• Remote Access
  • Network Basics
  • SSH
• More on Linux
  • Users and Permissions
  • Environment Variables
• Git
  • Register a ZJU Git account
  • Configure Public Key
  • Clone a Repository
• AI Agent
  • What is an AI Coding Agent
  • Installation
  • Basic Usage
  • Skills and MCP

Before You Start¶

• Read this presentation or watch this video.
• Make sure you can access GitHub, Google and Stack Overflow.

Obtain a Linux Virtual Machine¶

OS and Kernel¶

An operating system (OS) is system software that manages computer hardware, software resources, and provides common services for computer programs. The operating system is a vital component of the system software in a computer system.

A kernel is a computer program that is the core of a computer's operating system, with complete control over everything in the system. It is the "lowest" level of the OS.

Linux¶

Linux is a family of open-source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds. Linux is typically packaged in a Linux distribution.

Linux is a popular choice for developers and system administrators due to its flexibility and open-source nature. Linux is also widely used in the HPC field due to its high performance and scalability.

Linux distributions¶

What is Linux distribution? A Linux distribution (or Linux distro) is essentially a collection of software packages and configurations that are used to create a complete Linux operating system. They both use the Linux kernel, but might have different out-of-the-box configurations and user applications.

There are many Linux distributions available, each with its own strengths and weaknesses. Here are some popular choices:

• Ubuntu: A popular choice for beginners due to its ease of use, large community support, and compatibility with many hardware devices.
• Debian: Known for its stability and security.
• Fedora: A community-driven Linux distribution sponsored by Red Hat.
• Arch Linux: A lightweight and flexible Linux distribution that follows the "rolling release" model.

In HPC and cloud computing, Debian is a popular choice due to its stability and security.

We recommend using Debian for this course.

Index of /debian-cd/
Parent directory/
13.5.0/                                            2026/05/17 03:43:13
13.5.0-live/                                       2026/05/17 03:43:13
current/                                           2026/05/17 03:43:13
current-live/                                      2026/05/17 03:43:13
project/                                           2005/05/24 00:50:12
ls-lR.gz                                           2026/05/27 01:12:01

Virtual Machine¶

A virtual machine (VM) is a software-based emulation of a computer. By running a VM on your computer, you can run multiple operating systems on the same hardware. This is useful for testing software, running legacy applications, and learning new operating systems.

Hypervisors are software that creates and runs virtual machines.

You can choose whatever hypervisor you like. In this course, we recommend using VMware Workstation Pro on Windows and Linux, or VMware Fusion on macOS. They are free for personal use since May 13, 2024.

Task 1.3: Create a new virtual machine and install Debian

Please read the installation instructions carefully.

If the following instructions don't mention a specific step, leave it as default.

Step 1 (Windows)Step 1 (macOS)Step 2Step 3Step 4Step 5

Select the downloaded Debian ISO image as the installation media. Create a new virtual machine.

Here is my configuration:

Select the downloaded Debian ISO image as the installation media. Create a new virtual machine.

Here is my configuration:

Run the virtual machine and install Debian. (We recommend to choose Install but not Graphical install.)

Please choose English as the language.

You can change hostname, domain name, etc. as you like.

Don't set a root password. Read the text on the screen carefully.

If you leave this empty, the root account will be disabled and the system's initial user will be given the power to become root using the sudo command.

So, if you set a root password, you will need to add yourself to the sudo group later manually.

Then set up your user account. Use the entire disk for the installation.

Configure the package manager. Choose enter information manually and set the mirror to mirrors.zju.edu.cn.

Notice in the Software selection step, you need to select SSH server and standard system utilities, and cancel the selection of any other options. The text at the bottom of the screen will tell you how to navigate the menu.

In the Configuring grub-pc step, should choose /dev/sda as the device for boot loader installation. Otherwise, you may not be able to boot into the system.

Installation finished. Usually you don't need to remove the installation media manually because the virtual machine will try to boot from the disk first.

After rebooting, you can log in with the user account you created.

Linux Basics¶

Command Line Interface (CLI)¶

Read The Linux command line for beginners - Ubuntu. Begin with section 1 and stop at section 5.

Linux File System¶

Watch Linux File System Explained!

The Advanced Packaging Tool (APT)¶

Unlike Windows, where you need to download software from the internet and install it manually (this can be dangerous), Linux distributions have package managers that allow you to install software from a central repository.

For Debian-based distributions, the package manager is called apt. You can use apt to install, update, and remove software packages. For example, to install the htop package, you can run:

sudo apt update
sudo apt install htop

The first command updates the local package list from the repository, and the second command installs the htop package.

You can edit the /etc/apt/sources.list file to change the repository mirror. Read SourceList - Debian Wiki to learn more about the sources.list file.

If you are finding a package, you can use pkgs.org to search for the package and find the repository.

Ign:1 cdrom://[Debian GNU/Linux 11.0.0 _Bullseye_ - Official amd64 DVD Binary-1 20210814-10:04] bullseye InRelease
Err:2 cdrom://[Debian GNU/Linux 11.0.0 _Bullseye_ - Official amd64 DVD Binary-1 20210814-10:04] bullseye Release
Please use apt-cdrom to make this CD-ROM recognized by APT. apt-get update cannot be used to add new CD-ROMs
Hit:3 <http://security.debian.org/debian-security> bullseye-security InRelease
Hit:4 <http://deb.debian.org/debian> bullseye InRelease
Hit:5 <http://deb.debian.org/debian> bullseye-updates InRelease
Reading package lists... Done
E: The repository 'cdrom://[Debian GNU/Linux 11.0.0 _Bullseye_ - Official amd64 DVD Binary-1 20210814-10:04] bullseye Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

deb cdrom:[Debian GNU/Linux 11.0.0 _Bullseye_ - Official amd64 DVD Binary-1 20210814-10:04] bullseye main

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package nvtop

deb http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://security.debian.org/debian-security bullseye-security main

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package htop

Types: deb
URIs: <https://mirrors.zju.edu.cn/debian/>
Suites: trixie trixie-updates trixie-backports
Components: main contrib non-free non-free-firmware

Types: deb
URIs: <https://mirrors.zju.edu.cn/debian-security/>
Suites: trixie-security
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Access the Virtual Machine using SSH¶

Network Basics¶

Do you know the following concepts?

• IP address
• MAC address
• Subnet mask
• Gateway
• Port
• Port forwarding

If you are not familiar with these concepts, watch the following video to learn more about network:

• IP、MAC、DHCP 与 ARP
• IP 与 NAT

Network in Virtual Machines¶

Watch this video to understand network in the virtual machines: 虚拟机网络模式.

ping IP_ADDRESS

PING 172.16.39.129 (172.16.39.129): 56 data bytes
64 bytes from 172.16.39.129: icmp_seq=0 ttl=64 time=5.485 ms
64 bytes from 172.16.39.129: icmp_seq=1 ttl=64 time=0.695 ms

SSH¶

Secure Shell (SSH) is a cryptographic network protocol for operating network services securely over an unsecured network. The best-known example application is for remote login to computer systems by users.

sudo apt update
sudo apt install openssh-server

ssh username@IP_ADDRESS

Now you can copy and paste commands to this terminal. You can also use the scp command to copy files between your computer and the virtual machine. You can also connect your VSCode to the virtual machine using the Remote-SSH extension, but don't rely on it too much.

More on Linux¶

Users and Permissions¶

Watch this video to learn about:

• Users and Groups: Linux Crash Course - Managing Users
• Permissions: Linux File Permissions in 5 Minutes | MUST Know!

Environment Variables¶

Read this article to learn about environment variables: How to Set and List Environment Variables in Linux.

Git¶

Git is a distributed version control system that is widely used in software development. It allows multiple developers to work on the same project simultaneously and track changes to the codebase over time.

Register a ZJU Git account¶

Configure Public Key¶

Task 5.2: Generate an SSH key and add it to your ZJU Git account.

Step 1Step 2Step 3

Follow this guide to generate an SSH key: Generating a new SSH key and adding it to the ssh-agent.

Please take care of your private key, don't share it with anyone. And for the public key, you can share it with anyone who needs it.

We strongly suggest you to use ed25519 algorithm instead of rsa for better security with shorter key length, unless you want to end up being like this when sharing your SSH public key:

Add the public key to your ZJU Git account:

Test the SSH connection, it should look like this:

$ ssh -T [email protected]
ssh -T [email protected]
Welcome to GitLab, @324010****!

Show the screenshot of your successful connection.

Install Git¶

sudo apt update
sudo apt install git

brew install git

git --version

git version 2.x.x

AI Agent¶

In the previous sections, you have been typing commands manually in the terminal: reading documentation, installing packages, editing configuration files, and running programs. This is the traditional workflow that every developer follows.

In recent years, a new kind of tool has emerged: AI coding agents. Unlike simple chatbots (such as ChatGPT's web interface) that only generate text responses, AI coding agents can directly interact with your computer. They read and write files, run terminal commands, search the web, and manage version control. They serve as intelligent assistants that understand your codebase and can take real actions on your behalf.

Introduction¶

A traditional chatbot takes your message and returns text. An AI coding agent combines a large language model (LLM) with a set of tools that allow it to interact with the real world:

When you give an AI coding agent an instruction like "fix the compilation error in my Makefile," it reads the Makefile, identifies the problem, edits the file, and runs make again to verify the fix works. This read-think-act loop is what distinguishes an agent from a chatbot.

flowchart LR
    A[You: natural language instruction] --> B[Agent: read files & context]
    B --> C[Agent: think & plan]
    C --> D[Agent: take action]
    D --> E[Agent: observe result]
    E -->|iterate| B
    E -->|done| F[Report back to you]

There are many AI coding agents available today, such as OpenCode, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, and Windsurf. They share the same core idea but differ in interface, model provider, and specific features. In this lab, we use OpenCode as a representative example. It is an open-source agentic AI coding agent that runs in your terminal.

Read the official getting started guide to get an overview: Intro - OpenCode Docs.

Get API Key¶

Our course provides free access to several LLM APIs (such as GLM and DeepSeek) that you can use with OpenCode. To get your API key, log in to our New API Platform with your ZJU Git account, and then go to the "Token Management" section to create a new API key.

Our New API platform supports two types of LLM protocol:

• OpenAI: https://clusters.zju.edu.cn/newapi/v1
• Anthropic: https://clusters.zju.edu.cn/newapi

clusters.zju.edu.cn can be accessed both in and out of campus network.

Installation¶

opencode --version

{
    "$schema": "https://opencode.ai/config.json",
    "model": "zjusct/glm-5.2",
    "provider": {
        "zjusct": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "ZJUSCT New API",
            "options": {
                "baseURL": "https://clusters.zju.edu.cn/newapi/v1",
                "apiKey": "<your-api-key>"
            },
            "models": {
                "glm-5.2": {},
            }
        }
    }
}

mkdir my-first-project
cd my-first-project

opencode

> Explain what the configure script does in this project.
> What dependencies does this Makefile need?
> What does the -O2 flag do in gcc?

> Add error handling to the main function in server.c
> Change the optimization flag from -O0 to -O2 in the Makefile
> Fix the linker path in Make.Linux_PII_FBLAS

> Compile this project and show me any errors.
> Run the test suite and summarize the results.
> Check if OpenMPI is installed correctly.

> Show me what changed since the last commit.
> Create a commit with a descriptive message for the current changes.
> What does the most recent commit do?

> I'm getting "undefined reference to dgemm_" when linking. What's wrong?
> The configure script says it can't find mpi.h. How do I fix this?

Slash Commands¶

During an OpenCode session, type / to see a list of available commands. They are the primary interface for controlling the agent's behavior. Here are the most useful ones:

You can also define your own custom commands by placing Markdown files in .opencode/commands/ or ~/.config/opencode/commands/. See Commands - OpenCode Docs for details.

Extending Agent: Skills and MCP¶

OpenCode is not limited to its built-in capabilities. It can be extended through Skills and MCP (Model Context Protocol).

Skills¶

A Skill is a Markdown file that teaches OpenCode how to perform a specific task. When the agent sees that a skill is available (by reading its description), it loads the corresponding skill file on demand and follows the instructions inside.

For example, you might create a skill called check-system-status that instructs the agent to check system resource usage and status. The skill file would look like this:

~/.config/opencode/skills/check-system-status/SKILL.md

---
name: check-system-status
description: Check system resources usage and status
---

When invoked, do the following:
1. Run `top -b -n 1` to get a snapshot of current system resource usage.
2. Run `df -h` to check disk space usage.
3. Summarize the results in a human-readable format, highlighting any potential issues (e.g., high CPU usage, low disk space).

After creating this file, you can ask the agent to "check the system status" in any OpenCode session and it will load the skill and execute these steps.

Skills can be stored in several locations:

OpenCode also discovers Claude-compatible paths (.claude/skills/) and .agents/skills/, so skills written for other agents work out of the box.

MCP¶

MCP (Model Context Protocol) is an open standard that allows AI agents to connect to external tools and services in a standardized way. An MCP server is a separate process that exposes a set of tools (APIs) that an AI agent can call. By adding an MCP server to OpenCode, you can give it access to new capabilities without needing to teach it through skills.

Adding an MCP server in your opencode.json (or opencode.jsonc):

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "filesystem": {
            "type": "local",
            "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
            "enabled": true
        },
        "my-remote-server": {
            "type": "remote",
            "url": "https://mcp.example.com/endpoint"
        }
    }
}

Managing MCP servers from the command line:

opencode mcp list                # List all configured servers and their auth status
opencode mcp auth <name>         # Authenticate with a remote server
opencode mcp logout <name>       # Remove stored credentials
opencode mcp debug <name>        # Diagnose connection and OAuth issues

Once an MCP server is added, its tools appear in your OpenCode session automatically. For instance, if you add a database MCP server, OpenCode gains the ability to run SQL queries when you ask questions like "show me all users who registered last week." Refer to a server by name in your prompt (e.g. use the filesystem tool) to nudge the agent toward using it.

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "github": {
            "type": "local",
            "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
            "enabled": true,
            "environment": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
            }
        }
    }
}

> Get the latest 5 issues in the repository torvalds/linux using GitHub MCP tools.
> Create a new repo called "my-awesome-project" under my GitHub account using GitHub MCP tools.

Codex CLI¶

If you want to use Codex CLI instead of OpenCode, you can read the following part.

Installation¶

Open a terminal on your machine and run the installer for your operating system:

macOS / Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

If you see any network error during installation, you can install Node.js and then run the following command to install Codex CLI:

npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

Close and reopen your terminal, then run:

codex --version

You should see a version number printed, like:

codex-cli 0.x.x

If you see that, installation succeeded.

Configuration¶

To use our New API Platform, you can edit the configuration file ~/.codex/config.toml and add the following content:

model_provider = "zjusct"

[model_providers.zjusct]
name = "zjusct"
base_url = "https://clusters.zju.edu.cn/newapi/v1"
wire_api = "responses"
experimental_bearer_token = "sk-xxxxxxx"  # your API key
requires_openai_auth = false

References¶

• How do you explain an OS Kernel to a 5 year old?
• Virtual machines in Azure