SurfOS GitHub
Menu

Build it yourself.

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.

Browse the development branch
Clone the development branch
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.

Development environment guide
Hardware

Simulate SurfCPU

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.

SurfCPU command guide