Velxio: an in-browser Arduino, ESP32 and Raspberry Pi emulator you can self-host

What Velxio replaces, and for whom

The project targets the gap between writing embedded code and having the board on your desk. The README describes it as "an open-source multi-board emulator and circuit simulator" where you write Arduino C++, MicroPython, ESP-IDF or Python, compile it, and run it against CPU emulation with 150+ interactive electronic components in a browser tab. The README also claims 40 boards across 5 CPU families: AVR8, ARM Cortex-M, Xtensa LX6/LX7, RISC-V and ARM Cortex-A Linux.

The audience is narrower than that board count suggests. It suits people who want a working serial monitor and a wired circuit without ordering parts, and it suits anyone who needs a repeatable environment instead of a laptop with a specific toolchain installed. The repository includes a vscode-extension/ directory, so editor integration is part of the intended surface, not an afterthought.

One thing to read carefully before you plan around it: the self-hosted image and the hosted service do not carry the same catalog. The README states plainly that the self-hosted image runs the Arduino, Raspberry Pi Pico and ESP32 families, while STM32, Raspberry Pi Linux, the ESP32-C6 and the partner boards are only available online at velxio.dev. The headline board count is a hosted-service number.

Real CPU emulation, a SPICE layer, and a compile cache that decides your day

The architecture visible in the repository splits into a backend/ and a frontend/ directory, with docker/, prebuilt/ and scripts/ alongside them. The frontend is where the editor and canvas live; the README shows Monaco on the left, the circuit canvas on the right, and compiler output plus the Serial Monitor at the bottom.

Compilation is not a browser trick. The docker-compose.yml sets IDF_PATH=/opt/esp-idf and IDF_TOOLS_PATH=/root/.espressif, and the repository carries Dockerfile.espidf-toolchain, so ESP-IDF builds run against a real toolchain inside the container. Arduino libraries land in /root/.arduino15 and /root/Arduino. The electrical side is separate: the README describes a SPICE-based electrical layer that shows currents, voltages and shorts on the wires you draw, with oscilloscope channels on any pin.

The performance story is entirely about caching, and it is worth understanding before you benchmark anything. The compose file enables ccache through IDF_CCACHE_ENABLE=1 with CCACHE_DIR=/var/cache/ccache, and sets VELXIO_PERSISTENT_BUILD_DIR=1 so the ESP-IDF build directory persists per board target. The comment in that file states the intent: warm builds go from roughly 5 to 7 minutes down to roughly 5 to 30 seconds. Both flags can be turned off without rebuilding the image. If you skip the named volumes, you get the slow path on every restart.

Installing Velxio with Docker and running a first ESP32 sketch

The README gives a single-command self-host. Port 3080 on the host maps to port 80 in the container, and the named volumes are what preserve the Arduino libraries, the ccache directory and the persistent build directory across restarts.

docker run -d \
  --name velxio \
  -p 3080:80 \
  -v velxio-data:/app/data \
  -v velxio-arduino-libs:/root/.arduino15 \
  -v velxio-arduino-user-libs:/root/Arduino \
  -v velxio-ccache:/var/cache/ccache \
  -v velxio-build:/var/lib/velxio-build \
  ghcr.io/davidmonterocrespo24/velxio:master

Open http://localhost:3080 in a browser and the editor loads. The README says logs can be followed with docker logs -f velxio, which is the first place to look if the container starts but the page does not answer.

If you prefer compose, the repository ships a docker-compose.yml that builds from Dockerfile.standalone and starts the same service on the same port. backend/.env is optional; when it is missing, the entrypoint generates a random SECRET_KEY so the app boots out of the box. Create it only when you need OAuth or a fixed key.

docker compose up --build

The compose file also declares a healthcheck against http://localhost/health with a 90 second start period, so a container that reports healthy has finished booting rather than merely started.

For the first real use, pick an ESP32 DevKit from the component picker, drop an LED on the canvas, wire it to a GPIO, and write a sketch that blinks it and prints over UART. The README's own screenshot shows exactly this: an ESP32 DevKit blinking an external LED with the Serial Monitor open. Compile, then watch the monitor. If you want a starting point rather than a blank file, the README points at an examples gallery of more than 400 projects filtered by board, difficulty and topic.

Where Velxio stops being the right tool

The first limitation is the one the README states outright rather than hides: the self-hosted image does not include STM32, Raspberry Pi Linux, the ESP32-C6 or the partner boards. If your project is an STM32 target, self-hosting Velxio does not help you, and the workaround is using velxio.dev, which means your code and your circuit go to someone else's server. That is a real constraint for anyone whose reason for self-hosting is confidentiality.

The second is the cold-start cost. The compose comment puts a cold ESP-IDF compile at 5 to 7 minutes. That is tolerable interactively and painful in automation, and it only improves if the ccache and build volumes survive. Any deployment that recreates volumes on each run pays that price every time.

The third is the licence. The README badge says AGPL v3 and the repository carries both LICENSE and COMMERCIAL_LICENSE.md. AGPL is a strong copyleft licence with network-use terms, and a commercial option exists separately. Whether your integration triggers those obligations is a question for your own counsel; the point here is that a permissive-licence assumption is wrong for this project.

Finally, emulation is not a substitute for the physical board. Timing, analog behaviour and radio conditions in a simulated environment will not match a real device, and the README makes no accuracy claim beyond the emulated CPU families and the SPICE electrical layer. Treat a passing simulation as a reason to flash hardware, not as a replacement for it.

Velxio compared with Wokwi and the desktop simulators

Wokwi is the closest comparison and the one people search for. Both put an editor and a circuit canvas in a browser and both emulate microcontroller families rather than interpreting a simplified model of your sketch. The difference that matters for adoption is deployment: Velxio publishes a container image at ghcr.io/davidmonterocrespo24/velxio and a docker-compose.yml that you can run on your own machine, which Wokwi's model does not offer in the same form. The trade is catalog breadth, since Velxio's self-hosted image covers only the Arduino, Raspberry Pi Pico and ESP32 families.

On the desktop side, PICSimLab is a long-running simulator that runs locally as a native application. It does not give you a browser URL that a colleague can open, and it does not give you a container image to put behind a healthcheck, but it also does not depend on a container toolchain being present. Tinkercad sits at the other end: it is aimed at beginners and classroom circuits, and the README's positioning of Velxio as supporting ESP-IDF projects and custom chips compiled to WebAssembly puts it well past that scope.

A useful way to choose: if you want the lowest-friction path for a beginner, a hosted teaching tool is fine. If you want the emulator to live inside your own infrastructure, with your own library cache and your own build directory, Velxio is the option in this group that ships a Docker image.

Maintenance, upgrades and what the AGPL means for a self-hosted instance

The repository is not archived and the last push was on 2026-09-23, so the codebase is moving. Releases are frequent and small: v3.0.5 on 2026-09-02, v3.0.4 on 2026-08-25 and v3.0.3 on 2026-08-10, roughly one to two weeks apart. That cadence is good for fixes and awkward for anyone pinning versions, since a patch release can land mid-sprint.

The README's docker run example uses the master tag, which means pulling it again later gives you whatever master was at that moment. If you need reproducibility, pin a digest or a version tag rather than tracking master, and re-pull deliberately. Because the state lives in named volumes (the SQLite database under /app/data, the Arduino libraries, ccache and the build directory), an image upgrade does not wipe your environment, but it also means a broken upgrade can leave stale build artifacts. The compose file gives you two escape hatches for exactly this: IDF_CCACHE_ENABLE=0 and VELXIO_PERSISTENT_BUILD_DIR=0 both disable caching without a rebuild.

On licensing, the README labels the project AGPL v3 and links a separate COMMERCIAL_LICENSE.md. Running the container for your own development is one thing; offering a modified Velxio to other users over a network is where AGPL's network clause is usually discussed. The repository does not spell out which uses require the commercial licence, so that is the document to read before you build a product on top of it. This is not legal advice, and the terms themselves are the authority.

Editorial conclusion

Adopt Velxio if you want a self-hosted, AGPL-licensed board emulator for Arduino, ESP32 and Raspberry Pi Pico work, or if you need a browser sandbox for teaching and CI-style checks without hardware. Skip it if your target is an STM32, an ESP32-C6, a Raspberry Pi Linux image or one of the partner boards, because the self-hosted image does not ship those and you would be depending on velxio.dev. Before committing, verify three things: that the board you care about appears in the self-hosted image rather than only online, that the named volumes from the docker run command are actually mounted, and that you have read COMMERCIAL_LICENSE.md alongside LICENSE rather than assuming AGPLv3 covers your use.

Frequently asked questions

Official sources

1. davidmonterocrespo24/velxio on GitHub
2. Issues
3. Project website
4. README
5. Releases