IA64.CC

IA64.CC is a web environment for learning x86 assembly through an MS-DOS-style interface. This repository contains the complete application in a single monorepo: the browser frontend and the optional Rust execution runtime.

The frontend includes an assembler, debugger, guided lessons, scenarios, register and flag views, memory explorers, breakpoints, a stack display, and a VGA screen. Programs can run entirely in the browser with Unicorn, Keystone, and Capstone, or use the server runtime in hybrid mode.

Repository layout

Directory	Image	Role	Port	Documentation
front/	ia64-front	Static web application and browser emulator	8000	front/README.md
runtime/	ia64-runtime-server	Rust API, WebSocket, sessions, and Unicorn runtime	8080	runtime/README.md

The root Makefile and docker-compose.yml operate both components together. The component Makefiles remain available for frontend-only or runtime-only development.

Quick start with Docker

Requirements:

• Docker Engine
• Docker Compose v2, or the classic docker-compose command

Start both containers from the repository root:

make run

Then open http://localhost:8000/index.html. The runtime health endpoint is available at http://localhost:8080/health.

Starting with frontend v0.48, new browser installations default to hybrid execution and WebP text-screen rendering. Existing choices stored in the browser remain unchanged. Open Runtime > Configuration in the debugger to select a different mode or endpoint; the same-domain /runtime prefix is the default. Full client execution remains available when no backend is deployed. For the root Compose stack without a reverse proxy, select the full URL http://localhost:8080 in that window.

Useful root commands:

make help
make build_image
make test
make smoke
make logs
make stop

The ports and runtime engine can be overridden when starting the stack:

make run PORT=8001 RUNTIME_PORT=8081 RUNTIME_ENGINE=mock

RUNTIME_ENGINE=unicorn is the default. The mock engine is intended for protocol tests.

Forge multi-image builds

The forge can discover and build the two production images independently:

Dockerfile	IMAGE_NAME	Sources
Dockerfile	ia64-front	front/
Dockerfile.runtime	ia64-runtime-server	runtime/

Both Dockerfiles are intentionally at the repository root because the forge only discovers root files named Dockerfile or Dockerfile.*. Each one declares the metadata expected by the forge:

The frontend keeps the historical Dockerfile filename deliberately. The forge derives its patch counter from the Git history of that exact path; renaming it to Dockerfile.front would reset the generated frontend version to v0.0.

ARG IMAGE_NAME=<unique-image-name>
ARG APP_VERSION
ARG VERSION_MAJOR=0
ENV APP_VERSION=$APP_VERSION
ENV VERSION_MAJOR=$VERSION_MAJOR

IMAGE_NAME is unique for each container. The forge generates APP_VERSION as v<VERSION_MAJOR>.<PATCH> and injects both values as Docker build arguments. Because it tracks each Dockerfile independently, the frontend and backend patch numbers can differ. The frontend consumes them during its Node build so the version is compiled into the static JavaScript. The runtime stores them in the final image and returns its full version as app_version (and the compatibility field version) from GET /health. The debugger reads that value in Runtime > Configuration. No VERSION file is used.

The equivalent manual builds are:

docker build -f Dockerfile \
  --build-arg APP_VERSION=v0.0 \
  --build-arg VERSION_MAJOR=0 \
  -t ia64-front:v0.0 .

docker build -f Dockerfile.runtime \
  --build-arg APP_VERSION=v0.0 \
  --build-arg VERSION_MAJOR=0 \
  -t ia64-runtime-server:v0.0 .

Local development

The frontend requires Node.js with npm. Python 3 is used by its local static server, and Chrome or Chromium is required for browser smoke tests.

make install
make build_front
make test_front
make smoke_front

To run only the frontend development server:

make -C front serve

To build or test only the Rust runtime through Docker:

make build_runtime
make test_runtime

Hybrid runtime overview

The browser sends a standard ia64.codemap to the runtime. The server validates it, removes authoring and UI metadata, creates a stable ia64.runtime-codemap, stores it by SHA-256 hash, and creates isolated execution sessions. Sessions can be controlled with bounded step/run commands over HTTP or WebSocket and return CPU, memory, register, and VGA snapshots.

Principal endpoints include:

• GET /health
• POST /api/codemaps/compile
• POST /api/codemaps
• POST /api/sessions
• GET /api/sessions/{id}/snapshot
• POST /api/sessions/{id}/step
• POST /api/sessions/{id}/run
• GET /api/sessions/{id}/vga.html
• GET /api/sessions/{id}/ws

See the component documentation for the complete frontend runtime contract and API details.