Remote Environments & VS Code

By the end of this lesson, you will have a working development environment set up — whether that’s VS Code on your laptop, VS Code connected to a remote server, or a cloud-based Codespace. You’ll also understand where your commands run, which prevents real confusion later.

Why this lesson exists

Here’s the reality: most LLM CLI tools run best in a Linux environment. But most of you aren’t sitting in front of a Linux computer. You’re on a Mac laptop, a Windows machine, a university lab workstation, or a government-issued device.

That’s fine. You have several ways to get to a Linux shell, and this lesson covers all of them. This is not a detour — Linux is where cloud infrastructure, CI/CD pipelines, and production servers live. The commands you learn here transfer directly to every professional development environment you’ll encounter. Windows-native support for these tools is improving (see Module 6 for the current state), but WSL gives you the most consistent experience across all four tools.

The mental model: local vs remote

Before we set up anything, internalize this concept. It’s the single most important idea in this lesson:

When you type a command, it runs wherever your terminal is connected to — not necessarily on the machine you’re looking at.

Think of it like a phone call. When you call a friend and say “turn on the TV,” the TV that turns on is in their house, not yours — even though you’re the one speaking. SSH works the same way: you type on your keyboard, but the commands execute on the remote machine.

The key insight: if you’re SSH’d into a server, ls shows files on that server, not your laptop. This is why the “Where Am I?” check matters:

whoami      # What user?
hostname    # What machine?
pwd         # What directory?

Run these whenever you’re unsure. It takes 2 seconds and prevents real confusion.

Option 1: VS Code — The recommended cockpit

VS Code (Visual Studio Code) is a code editor that gives you a file explorer, a built-in terminal, and the ability to connect to remote machines — all in one window. It’s the single best tool for this course, regardless of your background.

Why VS Code?

• See your files AND type commands in the same window
• Works on Mac, Windows, and Linux
• Connect to remote servers with the Remote SSH extension — edit files on a server as if they were local
• Built-in terminal that matches your environment (WSL on Windows, bash on Mac/Linux)
• Port forwarding — VS Code often auto-detects local servers and can forward ports with one click, letting you view remote web servers in your local browser

Install VS Code

1. Go to code.visualstudio.com
2. Download for your OS and install
3. Open it — you’ll see a welcome tab

Open the integrated terminal

Press Ctrl+` (backtick — the key above Tab) or go to View → Terminal. A terminal panel appears at the bottom. This is where you’ll type all your commands.

On Windows with WSL: VS Code automatically detects WSL. In the terminal dropdown (the + icon), select Ubuntu (WSL) or set it as your default terminal profile in settings.

Worked example: your first VS Code session

Here’s what a typical first session looks like:

1. Open VS Code

2. Press Ctrl+` to open the terminal

3. Run the “Where Am I?” check:

   whoami      # Your username
   hostname    # Your machine name
   pwd         # Your current directory

4. Create a project folder:

   mkdir ~/ai-training && cd ~/ai-training

5. Open this folder in VS Code’s file explorer:

   code .

   The code . command opens the current folder in VS Code. Now you can see your files in the sidebar and type commands in the terminal — all in one place. Alternatively, you can use File -> Open Folder in VS Code and select ~/ai-training.

   💡Windows/WSL users

   Make sure you have the WSL extension installed in VS Code before running code . from inside WSL. Without it, the folder may open in the wrong context.

Option 2: SSH — Connecting to a remote server

If your instructor has given you access to a remote Linux server (university cluster, cloud VM, training environment), you connect to it using SSH (Secure Shell).

The mental model for SSH

SSH is like making a phone call to another computer. Once connected, everything you type runs on that remote computer, not yours. When you “hang up” (disconnect), the remote computer keeps existing — your files are still there, ready for next time.

Connecting from your terminal

ssh yourname@server.example.edu

You’ll be asked for your password (or it’ll use your SSH key if configured). Once connected, you’re now running commands on that remote machine.

Verify you’re connected:

hostname    # Should show the server's name, not your laptop
pwd         # Should show your home directory on the server

Connecting from VS Code (recommended)

This is the best way to work remotely — you get the full VS Code experience (file explorer, editor, terminal) while all commands run on the server:

1. Install the Remote - SSH extension in VS Code (search “Remote SSH” in the Extensions panel)
2. Press Ctrl+Shift+P → type “Remote-SSH: Connect to Host”
3. Enter yourname@server.example.edu
4. VS Code opens a new window connected to the remote server
5. Open a folder, open the terminal — you’re working on the server with the full VS Code experience

ssh -i ~/.ssh/agency-key username@dev-server.agency.gov -p 2222

SSH without VS Code

If VS Code isn’t available, you can SSH from any terminal:

ssh yourname@server.example.edu

To view web content you generate on the server, use port forwarding:

ssh -L 8080:localhost:8080 yourname@server.example.edu

This maps port 8080 on the server to port 8080 on your laptop. Start a web server on the remote machine, then open localhost:8080 in your local browser.

Keep your session alive

If you close your laptop or lose network, your SSH session dies and interactive processes usually stop (unless they were started with tmux, screen, or nohup). Two solutions:

• tmux — a terminal multiplexer that keeps your session alive:

  tmux                    # Start a new session
  # ... do your work ...
  # Press Ctrl+B, then D to detach (session keeps running)
  tmux attach             # Reconnect later

• VS Code Remote — reconnects automatically when your network comes back

Setting up SSH keys (optional but recommended)

Typing your password every time you SSH becomes slow and repetitive. SSH keys let you connect without a password:

# On your LOCAL machine (not the server), run:
ssh-keygen -t ed25519 -C "your-email@example.com"
# Press Enter to accept the default file location
# Optionally set a passphrase (adds security)

# Copy your key to the server:
ssh-copy-id yourname@server.example.edu

After this, ssh yourname@server.example.edu connects without asking for a password.

Option 3: Google Cloud Shell — Free Browser Terminal

Google Cloud Shell gives you a free Linux terminal in your browser at shell.cloud.google.com. It’s the fastest way to get a zero-install terminal for practicing commands.

When to use it

Cloud Shell is ideal for practicing the terminal commands from Module 3 — ls, cd, mkdir, cat, and everything else — without installing anything. It works on any machine with a browser, including Chromebooks and lab computers.

Setup

1. Go to shell.cloud.google.com
2. Sign in with your Google account
3. A terminal appears — you’re ready to type commands

Limitations

• 20-minute idle timeout — your session disconnects after inactivity (reconnect anytime)
• 50 hours per week — more than enough for learning
• 5 GB persistent home directory — files in ~/ survive between sessions
• Packages installed outside ~/ may not persist across sessions

Cloud Shell is a terminal practice sandbox, not a full development environment. For full project development with CLI tool installation, use Codespaces (next section). See the Cloud Sandbox Cheat Sheet for detailed specs.

Option 4: GitHub Codespaces — Full Dev Environment in Your Browser

GitHub Codespaces gives you a complete Linux development environment in your browser. This is not a limited experience — it is a real Linux machine with a real terminal, running real VS Code, where you can install and run everything in this course.

What it is

A cloud-hosted Ubuntu environment with VS Code, a terminal, file explorer, and pre-installed tools like Node.js and git. You get a real Linux shell with full internet access — no local installation needed. It looks and works exactly like the desktop VS Code app, and you can install Claude Code, Gemini CLI, Codex CLI, and Copilot CLI just like you would on any local Linux machine.

How to use it

1. Go to github.com/codespaces
2. Click “New codespace”
3. Choose a blank template or your instructor’s template repository
4. Wait ~30 seconds — a full VS Code opens in your browser

You now have a Linux terminal at the bottom. Install tools exactly as you would on any Linux machine:

node --version    # Node.js is pre-installed
npm --version     # npm too
whoami            # Shows your Linux user (often 'codespace')

Option 5: WSL (already set up)

If you followed the Windows instructions in Lesson 2, you already have WSL. You can:

• Open Ubuntu from the Start menu
• Type wsl in any terminal
• Use the Ubuntu profile in Windows Terminal
• Set WSL as your default terminal in VS Code

WSL is a real Linux environment. Every command in this course works natively.

Option 6: Your Own Cloud Environment

Your laptop is fine for learning, but for real projects you may want a persistent Linux environment in the cloud — always on, more powerful, accessible from anywhere.

The options

University students: check if your school provides free Azure or AWS credits — many do through programs like Azure for Education or AWS Academy.

The AI shortcut

Once you have a cloud account, you can use browser AI (ChatGPT, Claude, Gemini) to walk you through provisioning. Try a prompt like:

I have an Azure account. Walk me through creating an Ubuntu 22.04 VM
I can SSH into for development. I want the cheapest option that can
run Node.js and AI CLI tools.

The AI will give you step-by-step instructions including which VM size to pick, how to configure networking, and how to set up SSH access.

Connect with VS Code Remote

Once your VM is running, connect to it with the same VS Code Remote SSH workflow from earlier in this lesson — just point it at your cloud VM’s IP address:

ssh yourname@your-vm-ip-address

Which option should I use?

The clipboard problem

Copying and pasting between your local machine and a remote terminal can be tricky. Here’s a reference for the most common terminals:

API key tip: When pasting API keys into a terminal prompt that hides input (like a password field), you won’t see anything appear. That’s normal — it’s hiding the text for security. Just paste and press Enter.

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Environment variables and API keys

Every AI CLI tool needs an API key, and the way you provide it is through environment variables. An environment variable is like a sticky note your terminal can read — you set it once, and every program in that terminal session can see it.

# Set an API key for the current session
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Verify it's set
echo $ANTHROPIC_API_KEY
# sk-ant-your-key-here

Important: This key will disappear when you close the terminal. If you open a new window tomorrow, you will need to run the export command again. We’ll cover how to save keys permanently in a later lesson.

For now, just know that export is how you set environment variables, and the terminal uses them to pass information (like API keys) to programs.

Preflight checklist

Before moving on, confirm these work in your chosen environment:

whoami                  # Shows your username
hostname                # Shows your machine name
echo "Hello!"           # Prints text
ls                      # Lists files
pwd                     # Shows current directory

If all five work, your environment is ready. You’ve completed this environment setup lesson and are ready for the next module.

Key takeaways

• VS Code is your recommended cockpit — it combines a file explorer, text editor, and terminal in one window.
• Commands run wherever your terminal is connected to: your laptop (local), WSL (Linux on Windows), or a remote server (SSH).
• Always run whoami and hostname to confirm where you are, especially when working with remote servers.
• SSH connects you to remote machines. VS Code Remote SSH gives you the best of both worlds — a visual editor with a remote terminal.
• GitHub Codespaces is a full Linux development environment in the browser — a great starting point if you want zero setup.
• Environment variables (set with export) are how you pass API keys to AI CLI tools.
• Use tmux to keep remote sessions alive when you disconnect.

What’s next

You now have a working terminal, you can navigate the filesystem, manage files, and connect to remote environments. That’s the complete foundation. In the next module, we’ll put this foundation to work by installing and configuring your first AI CLI tools.