gbos

A tiny Unix-flavored OS for the Game Boy Color — a from-scratch cooperative microkernel with fork/exec, a shell with pipes, a persistent filesystem, a color terminal on the LCD, and a real TCP/IP stack over the link cable. It boots, gets a DHCP lease, pings, resolves DNS, fetches web pages, and hangs out on IRC. On a 1997 handheld (well, an emulated one).

Real capture: cold boot → DHCP lease → ping → an IRC session, typed live into the on-screen console. Regenerate it anytime with tools/gbdemo (below).

What's in the box

• Processes, the V7 way: fork/exec/wait/exit, zombies + reaping, background jobs (spin &), ps, kill — round-robin cooperative scheduling across banked memory with an HRAM context switch.
• A shell (written in C, running on the GB) with I/O redirection (> <) and pipes (|), argument passing, and a cwd-aware prompt.
• Networking, for real: the kernel owns SLIP over the link port, IPv4, ICMP, UDP and TCP; userland gets BSD-ish sockets via one syscall. On top: dhcp (boot-time lease), ping, nslookup (real DNS), wget (HTTP), chat, and a colorized IRC client (irc HOST [NICK], /join and friends, SELECT for the keyboard).
• A network to plug into: tools/gbhub is a virtual switch + DHCP server + NAT gateway — spawn a fleet of Game Boys that ping each other and reach the real internet; tools/gbjoin attaches an interactive GB to it, and tools/gbtype types into any GB's shell from the host.
• 40×18 color terminal on the LCD (4×8 font, two chars per tile, ANSI-ish colors) + an on-screen keyboard on the window layer (SELECT toggles it).
• Persistent filesystem on battery-backed cart RAM: inodes, nested directories, per-process cwd — survives power-off.
• A C toolchain: userland is plain C compiled with SDCC (sm83); ~30 tools ship in usr/ (cat, wc, head, ls, uptime, …). Adding a program is one .c file + a table entry.

Quick start

git config core.hooksPath hooks        # once: clang-format pre-commit hook
make                                   # -> gbos.gb  (needs RGBDS + SDCC)

# solo, in the sl0pboy emulator (~/dev/gbc):
~/dev/gbc/build/sl0pboy --sixel 3 --chrome gbos.gb

# networked — hub in one terminal, Game Boys in others:
sudo tools/gbhub --daemon              # virtual net + DHCP + NAT (needs root)
tools/gbjoin                           # a windowed GB joins 10.0.0.0/24
tools/gbtype 'ping 10.0.0.3'           # or type into it from the host

On the Game Boy: SELECT toggles the on-screen keyboard, d-pad + A types, START sends the line.

/# uname -a
gbos sm83 (Game Boy Color)
/# ping 10.0.0.1
PING 10.0.0.1
  reply from 10.0.0.1 seq=1
  ...
-- 4/4 received
/# irc 10.0.0.1 sl0pboy
-!- registering as sl0pboy (SELECT = keyboard)

The demo GIF

The GIF above is produced by a scripted, self-syncing demo driver: tools/gbdemo runs a step file (demo/readme.gbd), injects console text and button events at the right moments — syncing on the actual screen contents (the terminal's WRAM shadow, read over the emulator's debug socket) rather than timers — while the emulator records every frame, then renders the GIF:

sudo tools/gbhub --daemon              # network up (once)
tools/gbdemo demo/readme.gbd           # inside tmux; writes demo/gbos-demo.gif

Edit demo/readme.gbd to choreograph your own (verbs: type, slowtype, key, waitfor, record, gif, …).

Docs

• docs/internals.md — the full technical breakdown: memory model, syscall ABI, fork/exec/context-switch internals, the network stack, the filesystem layout, C toolchain notes, war stories, roadmap.
• docs/link-drop-investigation.md — a networking bug hunt, preserved.

Built and tested against the sl0pboy emulator; runs on anything that emulates a CGB + MBC5 cartridge with battery RAM. No MMU, no protection, no regrets.