DreamShell: a Dreamcast operating system with an XML UI and Lua scripting

What DreamShell is on the Dreamcast

The DreamShell is the operating system for the Sega Dreamcast, based on the KallistiOS kernel.

The description of what it is goes well beyond a bootable homebrew. It has a dynamic loadable modular system and an interface for creating applications with XML UI and both C/C++ and Lua script on. The documentation points at ready-made applications and modules, and at drivers for various devices, formats and interfaces, with examples for audio and video decoding, compression, packaging, binding, network, emulation and scripts. The phrase used for the range is from hardcore low-level assembler to high-level applications.

That range is the point. A Dreamcast homebrew usually means a bare metal binary loaded by a bootloader, which gives you full control of the hardware and nothing else. DreamShell sits above that with a module system, so a loadable driver or application can be dropped in, and an XML-based UI so those applications can have an interface without hand-drawing it.

The repository topics match the structure: bootloader, driver, filesystem, firmware, loader, shell, operating system, and the SH4 and NAOMI architectures the Dreamcast is built on, with bios, iso, lua, xml and cpp among the others.

The users are Dreamcast homebrew developers and the retro scene around it, and the project also targets the NAOMI and NAOMI 2 arcade boards, which is where the driver work is most demanding.

The ISO Loader subproject and what it emulates

There is also a large subproject, the ISO Loader, which the documentation calls out separately because it is a substantial piece of work in its own right.

It contains emulation of BIOS system calls, CDDA playback and VMU, and it can hook interrupts for various SDKs. The practical meaning is that a program written against the official Dreamcast SDK, which expects those BIOS calls, can run on the DreamShell environment without being rewritten from scratch. The BIOS system call emulation is the load-bearing part, since the commercial SDK programs call into the BIOS and would otherwise fail immediately.

CDDA playback covers the digital audio track of a CD, and VMU covers the memory card unit, the Dreamcast's removable storage peripheral. The interrupt hooking is what lets the loader substitute its own implementations for the SDK's expectations.

This is why DreamShell is a full operating system rather than a shell around a homebrew loader. The ISO Loader sits underneath the module system and the XML UI so that commercial-era software and new homebrew live in the same environment.

The licensing note in the documentation is specific about scope: DreamShell core and DreamShell-specific components, including ISO Loader, are licensed under the PolyForm Noncommercial License 1.0.0 in LICENSE, with required notices in NOTICE.

The build environment: KallistiOS, a toolchain and tolua

Building DreamShell is a multi-stage process because it sits on top of a ported KallistiOS, and the documentation walks through it in order.

The first stage is system packages and the tolua binding generator, which is built from source:

cd /tmp
git clone https://github.com/LuaDist/tolua.git
cd /tmp/tolua && mkdir build && cd ./build
cmake ../ && make && sudo make install

The second stage is the code. The KallistiOS ports repository is cloned, then the DreamShell organisation's fork of KallistiOS is cloned into it, then DreamShell itself is cloned inside that, and the checkout is pinned to whatever revision the repository records:

cd /usr/local/dc/kos
git clone https://github.com/KallistiOS/kos-ports.git
git clone https://github.com/DC-SWAT/KallistiOS.git kos
cd /usr/local/dc/kos/kos
git clone https://github.com/DC-SWAT/DreamShell.git ds
git checkout `cat ds/sdk/doc/KallistiOS.txt`
cp ds/sdk/toolchain/environ.sh environ.sh
cp ds/sdk/toolchain/patches/*.diff utils/kos-chain/patches
cd /usr/local/dc/kos/kos/ds
git submodule update --init --recursive

The checkout line is worth noting. The revision is read from a text file inside the repository rather than hard coded, so the KallistiOS version DreamShell is built against is a tracked value that can be updated in one place.

The third stage is the toolchain, built from a Makefile.cfg copied into the kos-chain directory, and the fourth is the SDK, which sources the environment file, builds the ports, and then links the host tools tolua, mkisofs and mksquashfs into the SDK's bin directory so the image building works.

The make targets you will actually use

Once the environment is in place, the Makefile exposes a set of targets that map onto the different things you might be building.

The top level ones are make build for a full build, make clean-all for a full clean, make release for a release package, make update to update all the code from GitHub, and make update-build to update and rebuild. There is make build-ports to update and rebuild just the ports, and make toolchain to rebuild the toolchain if it has been updated.

The granular targets are the useful part, because a full rebuild of a Dreamcast SDK toolchain is slow. A bare make builds the core and the libraries only, and there are separate targets for the libraries alone, for the modules, applications and commands only, and for the firmware.

The firmware target covers three separate firmwares, each built and installed individually, the bootloader, isoldr and hollysh, and the MIE firmware is a fourth with its own rule. MIE is the exception, because mie_z80.bin ships as-is and should only be rebuilt after changing the firmware, and doing so needs SDCC.

There is also a per-terminal step that is easy to miss. For each new terminal type, you have to source the environment file, since the build depends on the environment variables it sets:

cd /usr/local/dc/kos/kos/ds && source ../environ.sh

The repository also has Makefile.gcc_stubs and Makefile.stubs at the top level, which are the stub toolchain files for the host side of the build, and exports.txt and exports_gcc.txt which list the symbols the host executables export.

Running it: hardware tools and three emulators

The run targets cover both real hardware and emulation, and the distinction matters because the DreamShell build is a set of different binaries.

On hardware there are two tools, dc-tool-ip and dc-tool-serial, and the make targets are make run and make run-serial. The serial variant is the path that does not need a network link to the console.

For emulation there are three, lxdream, nulldc and flycast, with make lxdream, make nulldc and make flycast. The Makefile header comment also mentions the flycast-ide and flycast-ide-naomi variants, which pair the emulator with the IDE/SD image and the NAOMI target respectively.

Two image targets round out the list. make cdi produces a CDI image, which is the format the Dreamcast's own drive tooling uses, and make ide produces an IDE or CF raw FAT32 disk image, which is what you put on a physical memory card or SD card.

The build outputs are named by version, and the Makefile derives the name from four variables. VER_MAJOR, VER_MINOR and VER_MICRO give the 4.0.5 in this tree, and VER_BUILD encodes the build type, with the comment that build types run from 0x0N for Alpha through 0x1N for Beta, 0x2N for RC and 0x3N for Release. The current value, 0x15, means Beta 5, and the target name becomes DreamShell_v4.0.5_Beta5 with a core binary of DS_CORE.BIN.

The licence is the part to read carefully

This is the most consequential thing about the project, and it is stated in three parts.

DreamShell core and DreamShell-specific components, including ISO Loader, are licensed under the PolyForm Noncommercial License 1.0.0, in the LICENSE file. Required notices are in NOTICE. And the distribution also includes third-party components under their own licenses, for example lib/, modules/ and parts of sdk/, and for those, the license stated in the corresponding file or directory applies.

So the licensing is layered, and a distributor has to check all three layers. The PolyForm Noncommercial term means the DreamShell-specific code cannot be used for commercial purposes, which is a real constraint for anyone who wants to ship a product containing DreamShell components, and it is a different constraint from the GPL-style terms that the third-party libraries carry.

The platform classifies the repository licence as one it cannot categorise, which is consistent with a nonstandard licence file rather than with an oversight. Read LICENSE and NOTICE together, and read the per-directory terms before you assume a component is covered by the top-level licence.

Contributing has its own condition. Contributions require acceptance of CONTRIBUTING.md and CLA.md, so the project asks for a contributor licence agreement alongside the contribution terms, which is normal for a project that wants to be able to relicense or defend its own code.

Where DreamShell is the wrong tool

The first limit is the licence, and it is the one that decides the project for most organisations. If you intend to distribute DreamShell components inside a commercial product, the PolyForm Noncommercial 1.0.0 term on the core and on the DreamShell-specific components rules that out, and the third-party components under lib/, modules/ and parts of sdk/ carry their own separate terms that you would have to audit one directory at a time.

The second is the build cost. This is not a single binary you compile. It is a ported KallistiOS, a toolchain built from a Makefile, an SDK with the host tools linked into it, and a set of submodules, and the whole thing is driven from a Linux machine with a long list of apt packages. The benefit of that complexity is that you can build a real DreamShell, the firmware images, and the modules; the cost is that a first build is a session of work rather than a coffee break.

The third is the target hardware. The Dreamcast is 128-bit hardware, and the driver work for the NAOMI and NAOMI 2 arcade boards is a separate target with its own constraints. Anything you build here is for that machine, and so expect some friction in the tooling as well.

The fourth is the ecosystem position. DreamShell competes with other Dreamcast homebrew environments and with the original SDK itself. The difference in approach is that DreamShell provides an operating system layer with modules, an XML UI and Lua scripting, where a bare KallistiOS homebrew gives you hardware control and nothing else. If you are writing a single demo with tight timing, that layer is overhead. If you are building a suite of applications with a shared shell, it is the whole point.

Project state and what to check before you start

The repository is not archived, and the last push was on 2026-10-22, so the tree is current. The release tags are v4.0.3.Release from 2025-09-30 and v4.0.4.Release from 2026-07-14, plus a dev tag that tracks the master branch, and the Makefile in this tree is already on 4.0.5 at build 0x15, so the version 5 development line is in progress.

The documentation's own entry points are the website at dc-swat.ru, the forum, and a donation page, which tells you this is a volunteer project with a support community rather than a company product.

What to check before you start is concrete. Read LICENSE and NOTICE as a pair, and then the per-directory terms under lib/, modules/ and sdk/, because that decides whether you can use what you build at all. Then decide whether you need the ISO Loader's BIOS call emulation, since that is the difference between running commercial-era SDK software and running only native DreamShell applications.

If you are building, set the environment up in the order the documentation gives, because the steps depend on each other: the packages and tolua first, then the code checkout pinned to the recorded KallistiOS revision, then the toolchain, then the SDK with the host tool links. After that, use the granular make targets rather than make build, so a change to a module does not cost you a full toolchain rebuild.

And keep in mind the one dependency the documentation calls out separately. The MIE firmware ships prebuilt as mie_z80.bin and only needs SDCC if you change it, so if you are not touching that firmware you can skip installing SDCC entirely.

Editorial conclusion

DreamShell fits a Dreamcast homebrew developer who wants a full application environment rather than a bare metal homebrew, and who needs the XML UI, the Lua scripting and the ISO Loader together in one tree. It does not fit a commercial product, because the PolyForm Noncommercial License 1.0.0 covers the core and the DreamShell-specific components, and a project that distributes DreamShell has to satisfy that restriction. Before you adopt it, read the LICENSE and NOTICE files as a pair, since the third-party components under lib/, modules/ and parts of sdk/ carry their own terms, and plan the build for the toolchain and the SDCC dependency the MIE firmware needs.

Frequently asked questions

Official sources

1. DC-SWAT/DreamShell on GitHub
2. Issues
3. Project website
4. README
5. Releases