Getting started#

This page takes you from nothing to a running Alpha program, then to a GPU training executable. If you only want to look around, the REPL runs the real compiler in your browser.

With a coding agent#

Alpha is written mostly by AI agents, and the repository's AGENTS.md tells them how to work in it. Paste this into Claude Code, Codex or OpenCode:

Clone https://github.com/thomasdavis/alpha and read AGENTS.md first.
Build the compiler: (cd bootstrap/haskell && cabal build -O2 exe:alpha).
Write a small Alpha module whose main computes a number, check it with
alpha check, run it with alpha run, and explain what each quantity in it means.
Then read systems/gpt2 and explain how its model stays independent of the GPU.

The rest of this page does the same by hand.

Requirements#

ForYou need
The compilerLinux on x86-64 (AArch64 works for the direct native target), GHC 9.10.3 and cabal 3.12
Running on a GPUA supported NVIDIA card (see Hardware) with the Linux driver's 580 branch (the H100 hosts and AlphaOS images also admit 595). Alpha talks to the driver directly, so the CUDA toolkit is not needed.

Build the compiler#

The current compiler is a Haskell bootstrap that compiles Alpha source, including the compiler's own Alpha packages.

git clone https://github.com/thomasdavis/alpha.git
cd alpha
(cd bootstrap/haskell && cabal build -O2 exe:alpha)
export PATH="$(dirname "$(cd bootstrap/haskell && cabal list-bin -O2 exe:alpha)"):$PATH"

alpha version
alpha doctor      # checks the workspace and lists every command

Your first program#

Save this as Hello.alpha:

module Hello

def double : (pi unrestricted n : Nat . Nat) =
  (lambda unrestricted n : Nat . (nat-add n n))

def main : Nat =
  (double 21)

Run it, then build it as a native executable:

$ alpha run --edition alpha-2027 --root Hello.alpha; echo $?
42
$ alpha build hello.elf --profile dev --edition alpha-2027 --root Hello.alpha
$ ./hello.elf; echo $?
42

main's natural number becomes the process exit status. The ELF is about 29 KB, static, and has no libc. Inside the Alpha repository the workspace manifest (alpha.project) already selects the alpha-2027 edition, so you can drop --edition there. A source file given to alpha run without --root (alpha run Hello.alpha) is taken as the root; alpha build refuses an output path ending in .alpha, so name the program with --root.

What you just wrote:

  • module Hello names the module.
  • (pi unrestricted n : Nat . Nat) is a function type. pi is the dependent function type; here the result type does not depend on n, so it reads like Nat -> Nat.
  • unrestricted is the binder's quantity: n may be used any number of times at run time. The others are erased (never at run time), affine (at most once) and linear (exactly once).
  • (double 21) applies double to 21.

When something is wrong#

Errors carry stable codes. Change unrestricted to linear in double: n is now used twice, which a linear binder forbids.

$ alpha check --edition alpha-2027 --root Hello.alpha
./Hello.alpha:4:3: ALPHA-QUANTITY-VIOLATION: [module Hello] linear binder n is used 2 time(s)

Diagnostics lists the catalogued codes, and alpha explain CODE, run from the repository root, prints one code's catalogue entry (its namespace, producer and meaning) from docs/diagnostic-codes.tsv.

Build a learning system#

GPT-2 small is the live system with the classic model / learner / device-pairing layout. This builds its initialization as one self-contained executable that draws GPT-2's initialization on the card GPT2.Build.Target selects and publishes it as a run's update-0 checkpoint (with the compiler of 2026-11-08, an 81,744-byte ELF in about 3 minutes):

alpha build gpt2-initialization.elf --profile release --artifact-value artifact \
  --root systems/gpt2/tests/qualification/Proof/GPT2InitializationArtifact.alpha

The training, continuation and prediction executables follow the same train / continue-from-checkpoint / predict request protocol; Anatomy of a learning system walks through them. Learning systems lists every live system and where it runs.

In the browser#

The REPL checks a module with the real compiler, then evaluates main and shows its type and value. It runs in a sandbox with no network and uses the reference evaluator, so nothing is compiled to native code there.

Where next#

  • Language guide: syntax, types, quantities, effects and families.
  • Families and branches: defining and consuming data.
  • Language and compiler: how a program becomes an executable.
  • The REPL and editor tools: alpha repl, the language server and VS Code.
  • Anatomy of a learning system: GPT-2 taken apart, from model to executable.
  • Command-line reference: every command, flag, profile and exit status.
  • Specification: the exact rules, when prose is not enough.