Docs · Getting started

Getting started

From nothing installed to your first graded run: three steps of setup, then the loop you will spend the course in.

1. Create a free account

Sign in with GitHub at sourceboot.com — that is the whole account setup. We use GitHub for identity only; no repository permissions are requested. Browse what there is to build at /courses. A course's first lab is free to read without an account, as is the welcome lab where a course has one; building them needs the free account.

2. Install the CLI

One static binary, macOS and Linux:

curl -fsSL https://sourceboot.com/install.sh | sh

It installs sboot to ~/.local/bin (override with SBOOT_INSTALL_DIR), checks the download against the release's published SHA-256 (and says so loudly if it cannot), and warns if the install dir is not on your PATH. Verify with sboot version. Uninstalling is deleting the binary. On Windows, download sboot.exe from the releases page instead — the install script is a Unix shell script.

3. Connect this machine

sboot login

It prints a short pairing code and a link, and opens the link if it can:

connect this machine to your SourceBoot account

  code    SJ4R-ZNR7

  open    https://sourceboot.com/account/connect?code=SJ4R-ZNR7
          # already signed in there? one click approves this machine

  waiting for approval … done

Approve it in the browser you are already signed in with and the CLI stores the token itself, 0600, in its own config directory. Nothing to copy, and sboot whoami confirms who you are afterwards.

If you would rather not use the browser round trip — CI, a headless box, a locked-down network — the token path still works: generate one on your account page and export it.

export SBOOT_TOKEN=<your token>

SBOOT_TOKEN always wins over a stored login, so it is also how you point one machine at a different account. A token is shown once, when it is minted — we store a hash, not the token — so if you lose it, rotate on the account page and reconnect any machines with sboot login.

4. Pick a course

sboot courses

The catalog with your progress on it, cached so it still answers offline after one sync. Bare sboot outside a workspace prints the same list plus the one next thing to do. The site's catalog is the same data with the lessons attached.

5. Start the course

The example on this page is Rust for Beginners; every course starts the same way, with its own id.

sboot start rust-for-beginners

This creates ./word-game-sb/ — the folder is named after what you finish with, not after the course id — and prints where everything went. What lands where:

  • Your source tree is yours. Every file you will edit lives under one directory — game/ in the word game, os/ in the OS courses, db/ in the SQLite course; the README in your repo names it. The rest of the repo is a pinned build config, a README, an MIT LICENSE, and a .gitignore for build artifacts.
  • sboot.toml marks the repo. It names the course, and it is how sboot finds your workspace from any subdirectory.
  • The tests and the grading engine are not in the repo. They live in the SourceBoot data directory on your machine, fetched per lab as you reach each one — so publishing the repo publishes your work and nothing else. sboot where prints every path involved, any time.

It also starts your history, and it never touches GitHub. git init runs inside the new folder, and if git has no name and email yet it asks for both once (they are saved for every commit you make on this machine) before making the first commit. Then one line: "when you want it on GitHub: sboot repo." Nothing in the course depends on running it — grading reads the files on your disk. See Your code.

Run it again and it repairs. If a download died half way, or a file went missing, sboot start <course> in the same place puts back only what is absent, never touches a file you have edited, and prints what it restored.

It finishes by naming the first lab, the command that grades it, and the page to read:

begin at lab 00 — The toolchain, and a game worth building:
  cd word-game-sb
  sboot test                  # grades 00-welcome
  https://sourceboot.com/courses/rust-for-beginners/stages/00-welcome

On a new machine, months from now: sboot resume <folder> — or sboot resume <git url> to clone your repo first. It restores the tests and the grading engine, then runs the first lab's checks, because the only honest answer to "does this machine still work" is a verdict from it.

6. Lab 0 — the welcome

Where a course has a 00 lab, that is the first one and it is always free: a short read about what the course is, how the two surfaces work, and what is yours — and then the loop itself, run once on the untouched starter tree. Its checks are your setup: they pass when the scaffold is intact and the toolchain actually built and ran it. So you get a green check before writing a line, and proof the machine is ready. It stays open afterwards, which makes it the page to re-read on a new machine.

cd word-game-sb
sboot test

Each command the checks run scrolls past first — cargo, rustup and clippy asked for their versions, then the build and the tests — and the verdict comes last:

  [PASS] the workspace is the one sboot unpacked — lantern/Cargo.toml names the crate every lab tests (1 pt)
  [PASS] cargo answered from your PATH and reported its version (1 pt)
  [PASS] rustup has a toolchain installed for your own machine — the only target this course ever builds for (1 pt)
  [PASS] clippy answered from your toolchain — the code checker every lab from 01 on runs over your library (1 pt)
  [PASS] rustc compiled the whole workspace, tests and all (2 pt)
  [PASS] the_list_is_sound — the word list that ships with the game proved its own rules on your machine, in a test run you made before writing any Rust (1 pt)

  score: 7/7
  ✅ all checks passed!

If a tool is missing this is where you find out, by name, with the install command — see Troubleshooting.

7. Work the lab

Read the lab on the site — lesson, canon, project brief — then build it in your editor and run its checks as you go:

sboot test

sboot test fetches the lab's tests if they are not cached yet, runs the course's build, runs the result, and grades it against the lab's published checks, right there in your terminal: [PASS]/[FAIL] per check with the points and evidence, then score: N/M. Run it as often as you like — it is the practice loop, and it never completes a lab.

Bare sboot at any point prints where you are in the course, which lab is current, and the one next thing to do.

Stuck on a failing check? sboot hint picks up the check your last run failed, and each ask goes one hint deeper. The lab page's Stuck? section mirrors the same ladder and adds a chat you can ask about your specific failure — see Troubleshooting.

8. Submit, read the review, complete

When the local run is green:

sboot submit

Submit re-runs the same local check first — one build, one run — and stops right there if it fails, sending nothing. On a pass it uploads that run's result together with your source tree, our server judges it, and the verdict comes back in the same command, ending with a link:

  ✅ official grade: 7/7 — recorded
  Submitted → https://sourceboot.com/courses/rust-for-beginners/stages/00-welcome?submission=<id>#review
  read your review, then press Complete there — that's what finishes the lab

That page shows the diff of what you wrote for this lab with a code review commented onto the exact lines. Reading it is the point; pressing Complete under it is what records the lab and unlocks the next one. Details in How grading works.