8bitworkshop, a browser IDE that assembles and runs 8-bit code locally

Compile as you type, emulate in the same tab

8bitworkshop is a browser-based IDE for micro computers and consoles, and its central claim is that it compiles or assembles your code as you type and then runs the result in a built-in emulator, all locally in the browser with no server round trip.

That last clause is the design decision that shapes everything else. There is no build server to wait on and no upload of your source, which means the loop from typing an instruction to seeing a sprite on a fake CRT happens in the tab you are already looking at.

The platform coverage is wide enough to be the reason to try it. The README lists toolchains and emulators for dozens of platforms, including the Atari 2600, 7800 and 8-bit lines, Commodore 64 and VIC-20, NES, Game Boy, ColecoVision, MSX, ZX Spectrum, Amstrad CPC, PC Engine, Vectrex and Apple II, plus a number of arcade boards, with the complete list on the Toolchains and Platforms page in the documentation.

The compilers and assemblers named in the feature list are cc65, SDCC and the Z80, 6502 and 6809 assemblers, with more linked from the Tools document. The emulators come with keyboard and gamepad input, so the same project can be driven from a pad plugged into a laptop.

The project is at version 4.0.0 in the package manifest, the licence is GPL-3.0, and the last push to master was on 2026-10-19.

A debugger with time-travel replay, not just a monitor

The debugger section of the feature list is where this separates from a plain code runner. It has breakpoints, stepping, a memory browser, disassembly, a call stack, memory probes, and time-travel replay.

Memory probes and time-travel replay are the two that change what a session feels like. A memory probe lets you watch a specific address while the emulator runs, which is how you find out that a zero page pointer you thought you had set has been overwritten by an interrupt handler. Time-travel replay means you can run back to the moment before the crash and watch it again, which is the feature that turns a black screen into a debuggable event.

The rest of the feature set rounds this out. There is hardware simulation with Verilog, so you can simulate a custom chip and use it from your 6502 code. There is an asset editor for bitmaps and palettes, which is how you get the graphics that a game of this era needs. And there are the outputs: export ROMs, save screenshots and videos, share playable links, and sync projects to GitHub.

That last one, sharing playable links, is the piece that makes the project usable for teaching. A student writes a program, gets a link, and the teacher opens it in a browser.

The 8bws CLI runs the same toolchains without a browser

The 8bws command line tool builds and runs projects headlessly, without a browser, and the README describes it as useful for scripting, CI and regression tests. The examples in the README are the fastest way to understand what it does:

# Build a source file to a ROM
npm run cli -- build --platform c64 hello.c -o hello.prg --symbols

# Run a ROM for 200 frames and take a screenshot
npm run cli -- run --platform nes --frames 200 --png shot.png game.nes

# Run with a debugger script (symbolic addresses come from the build)
npm run cli -- run --platform gb hello.c -e "break _main; pc 4"

Two things stand out. The build command emits symbols, and the run command can then use them, so a debugger script can say break _main and refer to symbolic addresses rather than raw ones. And the run command takes a platform, a frame count and a screenshot path, which is precisely the shape of a regression test: run for a fixed number of frames, capture the screen, compare.

There are also list-platforms and list-tools commands, so a script can discover what is available rather than hard-coding a target list. Run scripts, passed with -e or --script <file>, can use run, break, step, trace, hist, key, mem, screen, pc, info, reset and echo, and the README points at npm run cli -- help for the full list.

The package manifest registers the binary as 8bws pointing at ./gen/tools/8bws.js.

Building locally needs Node 24, make, git and Python 3

The online version is the easy path. The latest release lives at 8bitworkshop.com/redir.html, and a bleeding edge build from HEAD is at 8bitworkshop.github.io/8bitworkshop/, with 8bitworkshop.com/latest/ pointing at the same thing and redirecting to GitHub.

To run it yourself, the requirements are Node.js 24.x, npm, make and git, plus Python 3 for the local dev server. The clone is a single branch:

git clone -b master --single-branch [email protected]:sehugg/8bitworkshop.git

And the build is one command, with a note about Windows:

# On Windows, use the `UCRT64` shell from https://msys2.org/
# On Linux/macOS, just type:
make

What make does is spelled out in the README: it initialises git submodules, installs npm dependencies, builds the TypeScript and lezer grammars, and runs esbuild. The Makefile confirms the shape, with a submodules target that runs git submodule update --init --recursive when the submodule status shows anything uninitialised or divergent, a buildgrammars target that invokes the lezer generator on the 6502 and Z80 grammar files, and a buildtsc target that chains the grammar build with the TypeScript build, the doctools step and esbuild.

For development, make tsweb starts a web server on http://localhost:8000/ while TypeScript compiles in the background, and there is a note for VSCode users about selecting the workspace TypeScript version to fix type errors. To use the GitHub integration locally, you download the Firebase config file for your version.

Testing needs a token, because the tests talk to GitHub

The test section is short and the reason it needs setup is stated up front:

# To avoid "API rate limited exceeded" errors, set `TEST8BIT_GITHUB_TOKEN`,
# see: https://github.com > Settings > Developer settings > Personal access tokens
export TEST8BIT_GITHUB_TOKEN="<github_personal_access_token>"

npm test

So the test suite talks to GitHub, and without a token it hits anonymous API rate limits. The environment variable name is the one to use.

The rest of the tooling in the package manifest is worth a look for a project of this size. The test runner is mocha with jsdom for the DOM side, and there is a nightwatch.json in the repository root, which points to browser-level end to end tests. The editor is CodeMirror 6 with lezer grammars, and the lezer generator is a dev dependency, which is how the 6502 and Z80 syntax highlighting is produced at build time. The bundler is esbuild, the server is express with cors, and the client-side storage is localforage.

The dependency list also shows what a project like this has to carry: binaryen for the WebAssembly toolchain, dompurify for sanitising, jszip and pako for archives, and octokat as a GitHub API client.

A GPL project that bundles AGPL and MIT emulators side by side

The licence section is unusually careful, and it is the thing to read before you redistribute this.

The original source code in the repository is copyright Steven E. Hugg from 2016 to 2026 and is licensed under GPL-3.0. But the project also bundles and links against third-party components, including emulators, compilers and libraries, and those are explicitly not covered by the GPL-3.0 licence above. They remain under their own licences, and you must comply with those terms when redistributing the project or a modified version of it.

The dependencies list makes the mixture concrete. The emulators include Javatari under AGPL-3.0, jsnes under Apache 2.0, MAME under BSD-3-Clause, chips under Zlib, Z80.js under MIT, jsvecx under GPL-3, ifvms.js and 6502.ts under MIT, jspce under MIT and jsspeccy2 under GPL-3. The compiler cc65 is under zlib.

That is a serious constraint for anyone planning to embed the IDE. An AGPL component and a GPL-3.0 codebase are a different proposition from the permissive licences most web tooling uses, and the LICENSES/ directory in the repository exists to hold the individual terms.

One exception is stated clearly. All included code samples in the presets/ directory are licensed under CC0 unless a different licence is explicitly stated in the specific sample, so the starting code you build on is not encumbered by the copyleft at all.

The README also documents a policy on generated code that is unusual for a project of this kind. It discourages LLM usage for generating the code samples, on the grounds that it tends to hide subtle errors in code and in comments, diminishes the human achievement and the human-to-human communication aspects of the project, and asks that such code be thoroughly reviewed and edited.

Editorial conclusion

Adopt 8bitworkshop if you teach or practise 8-bit assembly and want a toolchain that works from a browser tab on a Chromebook, since the compilers, emulators and debugger run locally with no server round trip and the same toolchains are scriptable through the 8bws CLI. Do not adopt it as a production build system, since the emulators and assemblers it bundles carry their own licences, and do not expect the language service quality of a full commercial toolchain. Before you build on it, read the Toolchains and Platforms page for the exact list of supported targets, decide whether you want the online version or a local build, which needs Node.js 24, npm, make, git and Python 3, and note the licence split, with the original source under GPL-3.0 and the bundled third-party emulators under terms of their own.

Frequently asked questions

Official sources

1. 8bitworkshop/8bitworkshop on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README