Skip to content

README-Codespace.md

Latest commit

 

History

History
145 lines (107 loc) · 5.21 KB

README-Codespace.md

File metadata and controls

145 lines (107 loc) · 5.21 KB
Raw

Running this workshop in GitHub Codespaces

This is the recommended way to take the workshop. Everything runs in the cloud; nothing is installed on your machine.

Cost

GitHub's free tier includes 120 core-hours per month for personal accounts. A 4-core Codespace consumes 4 core-hours per hour of use, so this 3-hour workshop costs about 12 of your 120 free core-hours. You will not be charged.

Step by step

  1. Go to the workshop repository on GitHub.

  2. Click the green Code button, then the Codespaces tab, then "..." → New with options...

  3. Set Machine type to 4-core / 16 GB RAM / 32 GB storage. This matters. The labs are timed for 4 cores, and Lab 4 needs the memory.

  4. Click Create codespace.

  5. Wait for the build. The first build takes 8-12 minutes because it:

    • installs CPU-only PyTorch and the training stack (~2-3 min)
    • pre-downloads distilgpt2, SmolLM2-360M-Instruct, and TinyLlama-1.1B (~4 GB total, ~3-5 min)

    You can watch progress by clicking "Building codespace" in the lower right, or View → Output → Dev Containers.

  6. You are ready when the terminal shows:

    >>> Model prefetch complete.

  7. Open labs.md from the file explorer and press Ctrl+Shift+V (Cmd+Shift+V on Mac) to render it as a preview. That is the document you follow for the whole workshop.

  8. Open a terminal with Ctrl+Shift+`. Your prompt should begin with (.venv). If it does not:

    source .venv/bin/activate

Optional: Codespaces secrets

Nothing in this workshop requires a token. Two are useful if you have them.

Set them at GitHub → Settings → Codespaces → Secrets → New secret, and grant this repository access in the secret's repository list. Codespaces injects them as ordinary environment variables — there is nothing to configure in the repo, and you should never put a token in devcontainer.json, which is committed.

Secret name What it does Needed?
HF_TOKEN Raises Hugging Face Hub rate limits, and unlocks gated models (Llama, Gemma) if you experiment beyond the labs. Picked up automatically by huggingface_hub — no code change. No. Useful when a whole class pulls from the Hub at once.
GROQ_API_KEY Enables the optional Lab 5 Step 6 comparison against llama-3.3-70b-versatile. Free tier is 30 requests/minute, which is plenty. Get one at console.groq.com. No. That step skips cleanly without it.

An already-running Codespace will not see a new secret. Stop it and start it again (not just reload the browser window) after adding one.

To confirm they arrived:

echo "HF_TOKEN      is ${HF_TOKEN:+set}${HF_TOKEN:-NOT set}"
echo "GROQ_API_KEY  is ${GROQ_API_KEY:+set}${GROQ_API_KEY:-NOT set}"

Verifying your environment before the workshop starts

Run this. It should print version numbers and no errors:

python -c "
import torch, transformers, peft, trl, datasets, bitsandbytes, lm_eval
print('torch       ', torch.__version__)
print('transformers', transformers.__version__)
print('peft        ', peft.__version__)
print('trl         ', trl.__version__)
print('bitsandbytes', bitsandbytes.__version__)
print('lm_eval     ', lm_eval.__version__)
print('cores       ', torch.get_num_threads())
"

And confirm the models are cached (this should complete in seconds, not minutes — if it starts downloading, the prefetch did not finish):

python -c "
from transformers import AutoTokenizer
for m in ['distilgpt2','HuggingFaceTB/SmolLM2-360M-Instruct','TinyLlama/TinyLlama-1.1B-Chat-v1.0']:
    AutoTokenizer.from_pretrained(m); print('cached:', m)
"

Keeping your work

Codespaces stop automatically after 30 minutes of inactivity and are deleted after 30 days. Your files persist across stops. To keep anything permanently, commit and push it, or download it via right-click → Download in the file explorer.

The out/ directory is gitignored — model artifacts are large and easily regenerated by re-running the labs.

Common Codespace issues

The build failed or timed out. Delete the Codespace and create a new one. Transient network failures during the model prefetch are the usual cause. If the container built but models are missing, just run bash scripts/prefetch_models.sh yourself.

"You have exceeded your Codespaces quota." Check your usage at github.com/settings/billing. Delete old Codespaces you are not using at github.com/codespaces.

nproc says 2, not 4. You were given a 2-core machine. Every training time in labs.md roughly doubles. You can delete the Codespace and recreate it with the 4-core option, or continue and expect longer waits.

Out of disk space.

rm -rf out/
df -h /workspaces

The three models plus the Python environment use roughly 10 GB.

code and code -d do nothing. That command only works inside the Codespace's own terminal, not in a local terminal connected over SSH. Make sure you are using the terminal panel in the browser or in the VS Code window attached to the Codespace.

(c) 2026 Tech Skills Transformations and Brent C. Laster. All rights reserved.