1
HOST
Browser
UI, JavaScript, Web Serial and the Wanix namespace.
window + WebAssembly
01
COMPOSE THE COMPUTER
Wanix turns resources into one tree.
The page does not install a Linux machine in the usual sense. These binds layer remote archives, temporary browser memory and a VM device into one namespace.
/ ├── opt/xtensa-lx106 compiler archive ├── opt/esp8266 Arduino SDK + core ├── workspace → #ramfs/new │ ├── main.cpp ← browser writes │ └── build.sh ← HTTP file bind └── vm → #vm └── v86 ← emulator archive
Bind
Attach a resource at a path. It can come from HTTP, RAM, persistent browser storage or a device.
Namespace
A private view of the filesystem assembled for this application—not the host Mac’s filesystem.
See the actual HTML
<wanix-bind dst="." type="archive"
src="wanix-linux.tgz">
<wanix-bind dst="workspace"
src="#ramfs/new">
<wanix-bind dst="vm" src="#vm">NAMESPACE COMPOSITION
The filesystem is assembled, not downloaded as one disk.
<wanix-namespace> creates a private root. Each child bind places a resource provider at a destination path, so unrelated implementations appear as one coherent tree.
<wanix-bind dst="." type="archive" src="wanix-linux.tgz">
<wanix-bind dst="workspace" src="#ramfs/new">
<wanix-bind dst="vm" src="#vm">
<wanix-vm export="ttyS0" mem="256M" term start>- The Linux and ESP8266 toolchain archives populate normal-looking paths such as
/opt/xtensa-lx106. #ramfs/newsupplies a browser-memory filesystem at/workspace. JavaScript and the guest both see its files.#vmsupplies the virtual-machine device. The v86 archive adds its driver, and<wanix-vm>boots the guest.- The page waits for the guest’s
#taskpath before enabling Build. Files appearing in the tree are the readiness signal.
WANIX IDEA
A path describes where a capability appears, not where its bytes physically live. HTTP archives, RAM and a device can all participate in the same namespace.
02
MAKE IT YOURS
Change what the hardware does.
This is not a configuration block bolted onto a cached application. Your choices become C++ source, and Wanix builds a new application and firmware image.
SOURCE GENERATION
The controls generate a complete C++ translation unit.
Every input event calls firmwareSource(owner, cycleMs, profile). The source panel is therefore a preview of the exact text that will become /workspace/main.cpp.
constexpr char kOwner[] = "Jeff";
constexpr uint32_t kBlinkHalfPeriodMs = 500;
digitalWrite(LED_BUILTIN, LOW); // LED on
delay(kBlinkHalfPeriodMs);
digitalWrite(LED_BUILTIN, HIGH); // LED off- The name is checked as UTF-8 and limited to 64 bytes, then encoded as a safe C++ string literal.
- The selected full blink cycle is divided into equal ON and OFF delays. These profiles use an active-low built-in LED on GPIO2, so
LOWturns it on. - The browser sends only a whitelisted profile ID. The guest owns its board macro, pin variant, linker script and flash capacity; UI text never becomes arbitrary compiler flags.
- The Arduino core and SDK libraries are precompiled dependencies. This page still compiles the newly generated
main.cpp, then links a new ELF and packages a new flash image.
WANIX IDEA
The UI is a source-code authoring tool. Personalization is not patched into a prebuilt firmware blob; it crosses the browser/guest boundary as an ordinary file.
03
CROSS THE VM BOUNDARY
Drive Linux through a Wanix terminal.
No build request is sent to a server. JavaScript writes the source into the shared namespace, opens the VM terminal as a file, sends one shell command and watches for the result to appear back in the tree.
1Compilemain.cpp → object
→
2Linkobject + Arduino core → ELF
→
3PackageELF → firmware.bin
TERMINAL-DRIVEN BUILD
There is no special build RPC.
JavaScript treats the VM terminal as a duplex file. It writes a shell command to the same byte stream from which it reads compiler output.
const out = await root.openReadable(`${vm.term}/data`);
const input = await root.openWritable(`${vm.term}/data`);
BUILD_ID=build-… APP_SOURCE=/workspace/main.cpp \
/bin/sh /workspace/build.sh- The controller first writes
workspace/main.cppthrough the Wanix root API. - The shell script compiles it with
xtensa-lx106-elf-g++, links it with the packaged Arduino core and SDK, then runswanix-elf2bin. - Compiler scratch files live in a guest
/tmptmpfs; only useful outputs cross back into the shared workspace. - A unique marker printed after the command carries its exit status. The page recognizes that marker in the terminal stream and then reads
result.json.
WANIX IDEA
Automation and a person can drive the same real shell interface. The application composes familiar files and commands instead of requiring a custom guest API.
04
RETURN TO THE BROWSER
The output becomes another file.
The guest writes firmware.bin into the shared workspace. Wanix lets browser JavaScript read it directly: nothing is uploaded, and no application server sees the source, compiler transcript or firmware.
firmware.bin
— flashable bytesfirmware.elf
— linked executableSHA-256
Build to calculate content identity0x0000000x1000000x4000000xFFFFFF
new application
filesystem / unused
No artifact yet. The entire application will be written from offset zero.
ARTIFACT HANDOFF
The output crosses back through the namespace.
The guest copies its result files into a unique directory below /workspace/artifacts. Because that path is backed by Wanix RAM, browser JavaScript can immediately consume the same bytes.
await root.waitFor("workspace/artifacts/build-…/result.json");
const firmware = await root.readFile("…/firmware.bin");
const digest = await crypto.subtle.digest("SHA-256", firmware);
const url = URL.createObjectURL(new Blob([firmware]));result.jsoncarries build status, elapsed guest time and exact source, ELF and firmware byte counts.readFilereturns the binary firmware to JavaScript as bytes—not base64 and not an HTTP response.- WebCrypto computes the content identity. Blob URLs then expose those in-memory bytes to the download link and flashing component.
- The ELF is the linked executable used to create the image;
firmware.binis the ESP8266 flash layout that starts at offset zero.
WANIX IDEA
The build result is not returned by a service call. Producer and consumer agree on paths, so a Linux process and a web component can exchange artifacts through files.
05
OPEN THE MACHINE
Don’t take our word for it. Look around.
wanix-term attaches an xterm directly to the same terminal device the build controller used. This is the actual Alpine guest, with the same namespace and files—not a transcript or simulated shell.
C
A terminal is a file
The UI opens #term/…/data for reading and writing. That same file can serve automation first and an interactive human next.
TRY THESE INSIDE LINUX
pwd
ls -lah /workspace
sed -n '1,80p' /workspace/main.cpp
find /opt -maxdepth 2 -type d
xtensa-lx106-elf-g++ --version
find /workspace/artifacts -type f
The shell becomes available when the Wanix VM is ready.
A TERMINAL AS A FILE
The interactive shell and build controller share one endpoint.
<wanix-term> is an xterm UI attached to the VM’s terminal path. It does not imitate a shell; keyboard bytes go to Linux and terminal bytes come back.
const term = document.createElement("wanix-term");
term.setAttribute("for", "linux");
term.setAttribute("path", vm.term);
term.setAttribute("raw", "");
term.setAttribute("scrollback", "2000");- The VM exports its serial console as a terminal device. Its data endpoint appears at
#term/…/data. - When you open the shell, the custom element opens that endpoint and renders the stream with xterm.
- The terminal has one owner at a time. Starting a build removes the interactive element before automation opens the stream; afterwards you can attach again.
- Detaching the UI does not stop v86. The guest, shell history and files continue to live in browser memory until the page reloads.
WANIX IDEA
A terminal is another namespaced resource. The same endpoint supports a polished web interface, scripted control and direct human inspection without inventing three different backends.
06
ENTER THE PHYSICAL WORLD
A human opens the USB door.
Wanix produces the bytes; ESP Web Tools asks the browser for a serial port. The chooser and confirmation require you because a web page must not silently rewrite attached hardware.
ESP
8266
8266
D1 mini Pro LED preview follows your selected rate
Next action Connect your board over USB, then let the browser choose it and install your new firmware.
Before you flash
This lab targets a Wemos D1 mini Pro with an ESP8266 and 16 MiB flash. Installation replaces the application at offset 0x000000.
THE HARDWARE BOUNDARY
A manifest connects in-memory bytes to Web Serial.
After a successful build, the page creates an ESP Web Tools manifest that identifies the target family and maps the firmware Blob URL onto flash address 0x000000.
{
"builds": [{
"chipFamily": "ESP8266",
"parts": [{ "path": "blob:…", "offset": 0 }]
}]
}- Clicking the install button is the required human gesture that lets the browser show its serial-port chooser.
- ESP Web Tools opens the selected USB serial adapter and speaks the ESP8266 ROM bootloader protocol.
- It verifies the ESP8266 chip family, not whether the physical board is a D1 mini or NodeMCU. The selected profile therefore determines the firmware layout, and community-test profiles remain explicitly unverified on hardware.
- The complete application image is written from offset zero; a new install may erase flash first. On reset, the ROM loads it and the LED begins the active-low blink loop you compiled.
- Browser permission and USB are the only physical boundary. The source, compiler invocation and firmware bytes remain local; this site is only static files.
WANIX IDEA
Wanix gets an existing native toolchain to the artifact boundary. A browser-native component can then carry that artifact into hardware while preserving the browser’s explicit permission model.