diff --git a/content/projects/noxos/docs/build-instructions.md b/content/projects/noxos/docs/build-instructions.md
new file mode 100644
index 0000000..12982b0
--- /dev/null
+++ b/content/projects/noxos/docs/build-instructions.md
@@ -0,0 +1,51 @@
+---
+title: "Build Instructions"
+summary: "Instructions for setting up the workspace and building noxos"
+---
+
+**DISCLAIMER:** To build this project you need a linux system (WSL could work for windows users, but I haven't tested it)
+
+First you need to clone the repository:
+
+`git clone https://git.nerdcult.net/noxos/kernel`
+
+then there are a few tools required, that need to be installed:
+* **gcc** - compiler
+* **ld** - linker
+* **nasm** - assembler
+* **cmake** - build system
+* **xorriso** - ISO creation tools
+* **qemu** - emulator
+* **ovmf** - UEFI firmware
+
+you can check if you have all tools installed, with `./build.sh check`.
+
+There is a shell script to setup the workspace and compile.
+Just run it using the following commands:
+```bash
+cd noxos
+./build.sh
+```
+If the Bootloader ([limine](https://github.com/limine-bootloader/limine)) isn't downloaded yet, the script will download it.
+
+The final ISO file will be written to the *build* directory.
+
+To launch the ISO, run the `run.sh` script.
+
+# BIOS Emulation
+To emulate a BIOS system, you can run `./run.sh bios`.
+
+# Debugging
+## Logs
+When running through the script, qemu is configured to write the kernels logs to *STDOUT* and a file called *noxos.log*.
+
+## GDB
+You can connect GDB to qemu.
+To achieve this, run `./run.sh debug`.
+QEMU will wait until you connect GDB to it as a 'remote' target on `localhost:1234`.
+```bash
+gdb build/cmake/kernel/kernel
+target remote localhost:1234
+c
+```
+(note, that the last to commands have to be 'executed' in gdb not in your shell)