Clone ai-dev to get the shared kernel, x86 desktop, and SurfCPU hardware in one checkout. The project’s guide for coding agents maps the source and explains how to test a kernel change on both architectures.
git clone --branch ai-dev https://github.com/brandonburr86/surfos.git
cd surfos
Start a local build
Run either recipe from the root of your SurfOS checkout.
Operating system
Boot the x86 system
Start Docker and install QEMU on your computer. The build script compiles the kernel and programs in a container. The run script uses your local qemu-system-i386 to open the console.
x86 build and boot
./devenv/build.sh
./devenv/run.sh
At the shell prompt, try help or ls. The development environment guide also covers the UEFI image for the desktop.
On macOS, start Docker Desktop and have make available. Build the toolchain image, then exercise the processor in simulation. These tests run without an FPGA board.
SurfCPU simulation
make -C surfcpu image
make -C surfcpu test-cpu
The suite checks instructions, traps, and pipeline behavior. The command guide also covers full-system simulation and the SurfBoot firmware.