WebThings

Announcing WebThings Gateway 2.0

by Ben Francis

2025-12-19

The WebThings community are very excited to announce the WebThings Gateway 2.0 release.

WebThings logo with an illustration of connected devices

Build your own smart home hub. WebThings Gateway is a self-hosted web application for monitoring and controlling your home over the web.

What's New?

Groups

An often requested feature is the ability to create groups of "things". With the new groups feature you can now create a group by clicking the big "+" button at the bottom right of the Things screen and then clicking "Add group".

Screenshot of add group button in Things screen

You can then drag and drop things into groups and organise them however you like.

Screenshot of Things organised into groups

W3C Web of Things Compliance

WebThings Gateway 2.0 is the first version to be compliant with the W3C Web of Things 1.x family of standards, as a replacement for our legacy Web Thing API.

W3C WoT logo

This includes WoT Thing Description 1.1 for describing connected devices in a standardised way, WoT Discovery 1.0 for sharing a directory of devices, and WoT Profiles 1.0 (including the HTTP Basic Profile and HTTP SSE Profile) for providing interoperability guarantees.

This is a really big deal for us and is the culmination of a years-long effort working closely with the W3C WoT Working Group to ensure that the needs of the WebThings project have been reflected in the standards.

We believe that having your smart home safely expose a standards-based web API is the best way to enable an open ecosystem of apps and services which you can benefit from, whilst remaining fully in control of your own devices and data.

OS Upgrades

The Docker image has been upgraded from a Debian 10 (Buster) to Debian 12 (Bookworm) base, and makes a giant leap from Node.js 10 to Node.js 20, and from Python 3.7 to Python 3.11.

This will provide a much more up to date base for the gateway and mean it can benefit from the latest features of programming languages and their various software libraries and packages.

Release Model

WebThings Gateway 2.0 brings a new approach to our release model.

WebThings Gateway has always had an automatic update mechanism for the gateway application itself, but there was no way to automatically update the underlying Raspbian operating system used in our OS images for the Raspberry Pi.

Unfortunately the version of Raspbian we were using has now reached the point where it is too old to support the dependencies that the latest version of WebThings Gateway relies on, and is no longer receiving security updates. Because there is no way for us to automatically upgrade existing users to a new version of the operating system, and it can be tricky for users to upgrade between major versions manually, we have decided to switch to a new release model.

Raspbian-based OS images - Deprecated

We could have just released a new OS image using the latest version of what is now called Raspberry Pi OS and ask users to re-install from scratch, but the same situation would eventually occur again. Therefore we are recommending that users of the WebThings Gateway 1.x OS images switch to using our Docker image, or experimental snap package, instead.

Both of these options bundle all of the dependencies the gateway needs inside a container that is safely sandboxed from the underlying OS. By choosing your own host operating system you will be fully in control of the OS that runs your smart home, have the freedom to install other self-hosted web applications alongside WebThings Gateway, and can be sure that it will always be possible for you to upgrade to the latest version of the gateway in the future. Both options also give you a wider range of hardware to choose from, whilst still supporting Raspberry Pi.

Docker image and snap package

The Docker image has already become by far the most popular way to use WebThings Gateway, but for those users currently using our Raspbian-based 1.x OS images it will unfortunately require a one-off re-installation of a new operating system. Please see the documentation for installation instructions.

We realise that not everyone wants to administer their own host operating system and we've spent lots of time exploring alternatives for creating a pre-built OS image using lightweight, containerised base operating systems like Ubuntu Core and balenaOS. Unfortunately we still haven't quite found the right fit for a community-maintained distribution which anyone can download and use. We are continuing to explore other alternatives which might meet our needs for a lightweight production-quality OS which supports OTA updates of both applications and the underlying operating system, has a solid security model, is easily maintainable, and can target a wide range of hardware.

In the meantime, we recommend you use the Docker image, or experimental snap package.

💡 Before upgrading an exisiting gateway, we recommend you back up the .webthings directory which the gateway uses to store its local data, so that you can restore it back to its original state if necessary. In some cases this may also be useful when migrating between installation methods (e.g. from the legacy Raspbian-based OS images to the Docker image).

A Note about Add-ons

⚠️ Warning: Many add-ons may not yet work properly with WebThings Gateway 2.0.

This is a big update to both APIs and the underlying OS which has inevitably meant some backwards incompatible changes. We've tried to minimise the impact on add-ons as much as possible by having the gateway automatically migrate things. However, it's quite likely that add-ons that worked with versions 1.0 and 1.1 of the gateway may need updating for 2.0, even if they are listed in the add-ons directory as being compatible with any gateway version.

The WebThings Gateway 2.0.0 Beta release has been available for four months now and we've already tested some core add-ons like the Zigbee adapter and Virtual Things adapter, but we need your help to test your favourite add-ons and file issues for any problems you discover.

This does mean that you may want to hold off on upgrading any mission critical gateways until you've verified that the add-ons you depend on will work with 2.0.

🗒️ Note: If you are an add-on developer, please see this wiki page for advice on how to update your add-on to work with WebThings Gateway 2.0.

What's Next?

We have lots of exciting plans for upcoming future releases, including:

Matter logo

Outside of the gateway there are also lots of exciting upcoming developments coming to WebThings including:

A mockup of a touchscreen user interface with a status bar and navigation bar

UI mockup of WebThings Shell

Getting Involved

The WebThings open source project is maintained by an international community of volunteers. I'd like to say a big thank you to the many contributors who made this release possible.

If you’d like to get involved then you can file issues on GitHub, join the conversation on Discourse, chat with us on Matrix, follow us on Twitter or Mastodon, or jump into our documentation to learn how to develop your own web things and gateway add-ons.

Commercial Smart Building Pilot

A quick note from our sponsors, Krellian...

Are you wasting money on underutilised and inefficient buildings? Krellian helps facilities managers meet their net zero targets whilst saving money, by using smart building technology to optimise space utilisation and reduce energy consumption.

Screenshot of the Krellian Cloud user interface showing a heat map superimposed over the floorplan of large building

Early next year we will be starting a pilot of our commercial smart building solution:

If you would like to make your building smarter, safer, and more sustainable, then please register your interest today at krellian.com.