Simon Willison's Weblog: micropython

micropython-wasm 0.1a2

2026-06-06T04:26:06+00:00

I added a CLI to micropython-wasm (issue #7), inspired by the first draft of the blog entry when I realized it would be a great way to illustrate the Try it yourself section.

Tags: python, sandboxing, webassembly, micropython

Running Python code in a sandbox with MicroPython and WASM

2026-06-06T03:53:34+00:00

I've been experimenting with different approaches to running code in a sandbox for several years now, but my latest attempt feels like it might finally have all of the characteristics I've been looking for. I've released it as an alpha package called micropython-wasm, and I'm using it for a code execution sandbox plugin for Datasette Agent called datasette-agent-micropython.

Why do I want a sandbox?

My key open source projects - Datasette, LLM, even sqlite-utils - all support plugins.

I absolutely love plugins as a mechanism for extending software. A carefully designed plugin system reduces the risk involved in trying new things to almost nothing - even the wildest ideas won't leave a lasting influence on the core application itself. My software can grow a new feature overnight and I don't even have to review a pull request!

There's one major drawback: my plugin systems all use Python and Pluggy, and plugin code executes with full privileges within my applications. A buggy or malicious plugin could break everything or leak private data.

I'd love to be able to run plugin-style code in an environment where it is unable to read unapproved files, connect to a network, or generally operate in a way that's risky or harmful to the rest of the application or the user's computer.

My interest covers more than just plugins. For Datasette in particular there are many features I'd like to support where arbitrary code execution would be useful. I've already experimented with this for Datasette Enrichments, where code can be used to transform values stored in a table. I'd love to build a mechanism where you can run code on a schedule that fetches JSON from an approved location, runs a tiny bit of code to reformat it into a list of dictionaries, then inserts those as rows in a SQLite database table.

What I want from a sandbox

My goal is to execute code safely within my own Python applications. Here's what I need:

Dependencies that cleanly install from PyPI, including binary wheels across multiple platforms if necessary. I don't want people using my software to have to take any extra steps beyond directly installing my Python package.
Executed code must be subject to both memory and CPU limits. I don't want while True: s += "longer string" to crash my application or the user's computer.
File access must be strictly controlled. Either no filesystem access at all or I get to define exactly which files can be read and which files can be written to.
Network access is controlled as well. Sandboxed code should not be able to communicate with anything without going through a layer I fully control.
Support for interaction with host functions. A sandbox isn't much use if I can't carefully expose selected platform features to the code that it's running.
It has to be robust, supported, and clearly documented. I've lost count of the number of sandbox projects I've seen in repos with warnings that they aren't actively maintained!

WebAssembly looks really promising here

Web browsers operate in the most hostile environment imaginable when it comes to malicious code. Their job is to download and execute untrusted code from the web on almost every page load.

Given this, JavaScript engines should be excellent candidates for sandboxes. Sadly those engines are also extremely complicated, and are not designed for easy embedding in other projects. Most of the v8-in-Python projects I've seen are infrequently maintained and come with warnings not to use them with completely untrusted code.

WebAssembly is a much better candidate. It was designed from the start to support all of the characteristics I care about and has been tested in browsers for nearly a decade. The wasmtime Python library is actively maintained and has binary wheels.

MicroPython in WebAssembly

WebAssembly engines like wasmtime run WebAssembly binaries. Some programming languages like Rust are easy to compile directly to WebAssembly. Dynamic languages like JavaScript and Python are harder - they support language primitives like eval(), which means they need a full interpreter available at runtime.

To run Python we need a full Python interpreter compiled to WebAssembly, wired up in a way that makes it easy to feed it code, hook up host functions and access the results.

Pyodide offers an outstanding package for running Python using WebAssembly in the browser, but using Pyodide in server-side Python isn't supported. The most recent advice I could find was from October 2024 stating "Pyodide is built by the Emscripten toolchain and can only run in a browser or Node.js".

The other day I decided to take a look at MicroPython as an option for this. The MicroPython site says:

MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimised to run on microcontrollers and in constrained environments.

WebAssembly sure feels like a constrained environment to me!

Building the first version

I had GPT-5.5 Pro do some research for me, which turned up this PR against MicroPython by Yamamoto Takahashi titled "Experimental WASI support for ports/unix".

It then produced this research.md document, so I let Codex Desktop and GPT-5.5 high loose on it to see what would happen:

read the research.md document and build this. You will probably need to write a script that compiles a custom WASM version of MicroPython as part of this project - fetch the MicroPython code to a /tmp directory for this as part of that script.

It worked. I now had a prototype Python library that could execute Python code inside a WebAssembly sandbox!

The trickiest piece to solve was persistent interpreter state. The WASM build we are using here exposes a single entry point which starts the interpreter, runs the code and then stops the interpreter at the end.

This works fine for one-off scripts, but for Datasette Agent I want variables and functions to stay resident in memory so I can reuse them across multiple code execution calls.

A neat thing about working with coding agents is that you can get from an idea to a proof of concept quickly. I prompted:

For keeping variables resident: what if we ran code inside micropython itself which called a host function get_next_python_code() and then passed that to eval() - and that host function blocked until new code was available, maybe by running in a thread with a queue? Could that or a similar idea help here?

After some iteration we got to a version of this that works! In Python code you can now do this:

from micropython_wasm import MicroPythonSession

with MicroPythonSession() as session:
    print(session.run("x = 10\nprint(x)").stdout)
    print(session.run("x += 5\nprint(x)").stdout)
    print(session.run("print(x * 2)").stdout)

Under the hood this starts a thread, sets up a request queue and then sends messages to that queue for the session.run() command, each time waiting on a reply queue for the result of that execution. Inside WASM the MicroPython interpreter blocks waiting for a __session_next__() host function to return the next line of code, which it runs eval() on before calling __session_result__({"id": request_id, "ok": True}) when each block has been successfully executed.

The other piece of complexity was supporting host functions, so my Python library could selectively expose functions that could then be called by code running in MicroPython.

Codex ended up solving this with 78 lines of C, which ends up compiled into the 362KB WebAssembly blob I'm distributing with the package.

I am by no means a C programmer, but I've read the C and had two different models explain it to me (here's Claude's explanation) and I've subjected it to a barrage of tests.

The great thing about working with WebAssembly is that if the C turns out to be fatally flawed the worst that can happen is the WebAssembly execution will fail with an exception. I can live with that risk.

Memory limits are directly supported by wasmtime. CPU limits are a little harder: wasmtime offers a "fuel" concept to limit how many operations a WebAssembly call can execute, and that's the correct fit for this problem, but the units are hard to reason about. I'm experimenting with a 20 million default "fuel" setting now but I'm not confident that it's the most appropriate value.

Try it yourself

The micropython-wasm alpha is now live on PyPI.

You can try it from your own Python code as described in the README. I've also added a simple CLI mode in version 0.1a2 which means you can try it using uvx without first installing it like so:

uvx micropython-wasm -c 'print("Hello world")'
# To see it run out of fuel:
uvx micropython-wasm -c 's = ""; while True: s += "longer"'
# Outputs: micropython-wasm: guest exited with code 1

You can also try it in Datasette Agent like this:

uvx llm keys set openai
# Paste in an OpenAI key, then:
uvx --with datasette-agent \
  --with datasette-agent-micropython \
  --prerelease allow \
  datasette --internal internal.db \
    -s plugins.datasette-llm.default_model gpt-5.5 \
    --root -o

Then navigate to http://127.0.0.1:8001/-/agent and run the prompt:

show me some micropython

Should you trust my vibe-coded sandbox?

Having complained about immature, loosely-maintained sandboxing libraries, it's deeply ironic that I've now built my own!

I deliberately slapped an alpha release version on it, and I'm not ready to recommend it to anyone who isn't willing to take a significant risk.

I've put it through enough testing that I'm OK using it myself. I've shipped my first plugin that uses it, datasette-agent-micropython. I've also locked GPT-5.5 xhigh in that Datasette Agent plugin and challenged it to break out of the sandbox and so far it has not managed to.

I'm hoping this implementation can convince some companies with professional security teams and high-stakes problems to commit to using Python in WebAssembly as a sandboxing approach and open source their own solutions.

Tags: python, sandboxing, ai, datasette, webassembly, generative-ai, llms, ai-assisted-programming, codex, datasette-agent, micropython

datasette-agent-micropython 0.1a0

2026-06-02T19:28:36+00:00

Release: datasette-agent-micropython 0.1a0

I want Datasette Agent to be able to generate and execute Python code safely. This alpha is looking promising so far. GPT-5.5 has so far failed to break out of the sandbox!

Tags: python, sandboxing, datasette, webassembly, datasette-agent, micropython

micropython-wasm 0.1a1

2026-06-02T19:20:47+00:00

Release: micropython-wasm 0.1a1

Fixes for some limitations that emerged while I was trying to use this to build datasette-agent-micropython.

Tags: python, sandboxing, webassembly, micropython

micropython-wasm 0.1a0

2026-06-02T03:43:45+00:00

Release: micropython-wasm 0.1a0

My latest sandboxing experiment: This alpha package bundles a lightly customized WASM build of MicroPython with a wrapper to execute code in it via wasmtime.

Tags: python, sandboxing, webassembly, micropython

Hacking the WiFi-enabled color screen GitHub Universe conference badge

2025-10-28T17:17:44+00:00

I'm at GitHub Universe this week (thanks to a free ticket from Microsoft). Yesterday I picked up my conference badge... which incorporates a ~~full Raspberry Pi~~ Raspberry Pi Pico microcontroller with a battery, color screen, WiFi and bluetooth.

GitHub Universe has a tradition of hackable conference badges - the badge last year had an eInk display. This year's is a huge upgrade though - a color screen and WiFI connection makes this thing a genuinely useful little computer!

The only thing it's missing is a keyboard - the device instead provides five buttons total - Up, Down, A, B, C. It might be possible to get a bluetooth keyboard to work though I'll believe that when I see it - there's not a lot of space on this device for a keyboard driver.

Everything is written using MicroPython, and the device is designed to be hackable: connect it to a laptop with a USB-C cable and you can start modifying the code directly on the device.

Getting setup with the badge

Out of the box the badge will play an opening animation (implemented as a sequence of PNG image frames) and then show a home screen with six app icons.

The default apps are mostly neat Octocat-themed demos: a flappy-bird clone, a tamagotchi-style pet, a drawing app that works like an etch-a-sketch, an IR scavenger hunt for the conference venue itself (this thing has an IR sensor too!), and a gallery app showing some images.

The sixth app is a badge app. This will show your GitHub profile image and some basic stats, but will only work if you dig out a USB-C cable and make some edits to the files on the badge directly.

I did this on a Mac. I plugged a USB-C cable into the badge which caused MacOS to treat it as an attached drive volume. In that drive are several files including secrets.py. Open that up, confirm the WiFi details are correct and add your GitHub username. The file should look like this:

WIFI_SSID = "..."
WIFI_PASSWORD = "..."
GITHUB_USERNAME = "simonw"

The badge comes with the SSID and password for the GitHub Universe WiFi network pre-populated.

That's it! Unmount the disk, hit the reboot button on the back of the badge and when it comes back up again the badge app should look something like this:

Building your own apps

Here's the official documentation for building software for the badge.

When I got mine yesterday the official repo had not yet been updated, so I had to figure this out myself.

I copied all of the code across to my laptop, added it to a Git repo and then fired up Claude Code and told it:

Investigate this code and add a detailed README

Here's the result, which was really useful for getting a start on understanding how it all worked.

Each of the six default apps lives in a apps/ folder, for example apps/sketch/ for the sketching app.

There's also a menu app which powers the home screen. That lives in apps/menu/. You can edit code in here to add new apps that you create to that screen.

I told Claude:

Add a new app to it available from the menu which shows network status and other useful debug info about the machine it is running on

This was a bit of a long-shot, but it totally worked!

The first version had an error:

I OCRd that photo (with the Apple Photos app) and pasted the message into Claude Code and it fixed the problem.

This almost worked... but the addition of a seventh icon to the 2x3 grid meant that you could select the icon but it didn't scroll into view. I had Claude fix that for me too.

Here's the code for apps/debug/__init__.py, and the full Claude Code transcript created using my terminal-to-HTML app described here.

Here are the four screens of the debug app:

An icon editor

The icons used on the app are 24x24 pixels. I decided it would be neat to have a web app that helps build those icons, including the ability to start by creating an icon from an emoji.

I bulit this one using Claude Artifacts. Here's the result, now available at tools.simonwillison.net/icon-editor:

And a REPL

I noticed that last year's badge configuration app (which I can't find in github.com/badger/badger.github.io any more, I think they reset the history on that repo?) worked by talking to MicroPython over the Web Serial API from Chrome. Here's my archived copy of that code.

Wouldn't it be useful to have a REPL in a web UI that you could use to interact with the badge directly over USB?

I pointed Claude Code at a copy of that repo and told it:

Based on this build a new HTML with inline JavaScript page that uses WebUSB to simply test that the connection to the badge works and then list files on that device using the same mechanism

It took a bit of poking (here's the transcript) but the result is now live at tools.simonwillison.net/badge-repl. It only works in Chrome - you'll need to plug the badge in with a USB-C cable and then click "Connect to Badge".

Get hacking

If you're a GitHub Universe attendee I hope this is useful. The official badger.github.io site has plenty more details to help you get started.

There isn't yet a way to get hold of this hardware outside of GitHub Universe - I know they had some supply chain challenges just getting enough badges for the conference attendees!

It's a very neat device, built for GitHub by Pimoroni in Sheffield, UK. A version of this should become generally available in the future under the name "Pimoroni Tufty 2350".

Update: Setup with iPhone only

If you don't have a laptop with you it's still possible to start hacking on the device using just a USB-C cable.

Plug the badge into the phone, hit the reset button on the back twice to switch it into disk mode and open the iPhone Files app - the badge should appear as a mounted disk called BADGER.

I used Textastic to edit that secrets.py and configure a new badge, then hit reset again to restart it.

Tags: github, hardware-hacking, microsoft, ai, generative-ai, raspberry-pi, llms, claude-code, disclosures, micropython

Badge Interactive REPL

2025-10-27T22:54:02+00:00

Tool: Badge Interactive REPL

Tags: micropython

MicroPython Code Executor

2025-09-25T15:44:23+00:00

Tool: MicroPython Code Executor

Tags: webassembly, micropython

PyScript Updates: Bytecode Alliance, Pyodide, and MicroPython

2022-11-09T22:26:09+00:00

PyScript Updates: Bytecode Alliance, Pyodide, and MicroPython

Absolutely huge news about Python on the Web tucked into this announcement: Anaconda have managed to get a version of MicroPython compiled to WebAssembly running in the browser. Pyodide weighs in at around 6.5MB compressed, but the MicroPython build is just 303KB—the size of a large image. This makes Python in the web browser applicable to so many more potential areas.

Tags: python, webassembly, pyodide, micropython