Skip to main content

Sofabaton X Server

Manage your Sofabaton hubs from your browser.

Sofabaton X Server is a self-hosted management application for X1, X1S, and X2 hubs. Configure devices and activities, edit commands and button assignments, back up and restore your configuration, and control your equipment with the built-in web remote.

Run one server for all your hubs. Open it from a computer, phone or tablet on your network. No Home Assistant installation is required. Its local HTTP and WebSocket API also lets you connect your hubs to automation platforms and build your own integrations.

Unofficial community project; not affiliated with or endorsed by Sofabaton.

Get started · Manage your hubs · Run the server · Build an integration

Control panel

What you want to do Where to start
Add a hub or switch between hubs The hub picker at the top of the panel
Edit devices, commands and IR payloads Hub → Devices
Change activity buttons, favorites, macros, power sequences and inputs Hub → Activities
Create, edit or restore a backup Backup → Make / Edit / Restore
Control equipment and customize your web remote Remote → Card / Layout
Set up remote buttons for an integration to use Wifi Commands
Require a sign-in for changes, and make tokens for integrations Server settings → Access in the cog menu
Configure and test the X2 MQTT broker Server settings → MQTT broker (admin sign-in required)

Review configuration changes before Sync to Hub writes them. The panel shows progress and prevents competing writes while another hub operation or the official Sofabaton app owns control.

Follow the hub management guide for editing, synchronization, backups and Wifi Commands.

Run

You need a Sofabaton X1, X1S or X2 hub and something on the same network that stays on to run the server: a NAS or Docker host, or a computer running Windows, macOS or Linux. One server manages all your hubs. (Home Assistant users have the integration in this repository, which manages hubs inside Home Assistant; this server is for everyone else and for other platforms.)

Fully close the official Sofabaton app on all phones and tablets before setup. If another proxy, including the Home Assistant integration, already manages the hub, disable that hub there first.

Pick the way that fits where it will run:

  • Docker, or a NAS such as a Synology: run the published image m3tac0de/sofabaton-x-server (also on GHCR) with the Compose file and Linux host networking. See Docker.

  • A computer (Windows, macOS, Linux): install with pipx, which keeps the server in its own Python environment and upgrades with one command:

    pipx install "sofabaton-x-server>=0.2.7,<0.3"
    sofabaton-x-server --data-dir <a folder for its data>
    

    Plain pip works too. See Install.

  • From source: install both packages from the repository root. See from a source checkout.

Then open http://<server>:8480/, or http://localhost:8480/ on the machine running it. Add your hub through the hub picker, try Remote, then create and download your first backup. The getting-started guide walks through each step.

Keep the server's data directory across restarts; the Server page tells you when a newer release is out and how to update your kind of installation. Until you set up access (Server settings → Access), anyone on your network can change your hubs; see security.

For Docker, networking and reverse proxies, settings, and storage and upgrades, see Running the server.

Using the official Sofabaton app

After setup, the official app can connect through the server's local proxy. The hub normally accepts one client connection; the server holds that connection and presents a virtual hub to the app.

While the app is connected, the server observes the session and pauses control and configuration writes. Close the app to return control to the panel and your integrations. After editing in the app, refresh the affected devices or activities in the panel.

Back up and restore

Use Backup → Make to save your entire hub or selected devices, then download the result. Edit a backup file in the browser or restore selected devices and activities through Backup → Edit / Restore.

The downloaded file is your backup; the server keeps no backup archive. See back up and restore for the steps and restore options. For command payloads, see the IR reference.

Web remote

Use Remote in the panel, or open http://<server>:8480/ui/remote/ for a standalone remote. Select a hub, bookmark the page, or add it to your phone's home screen. Customize its buttons and layout in Remote → Layout and save the configuration for that hub.

The same card is also a web component for your own dashboard: load /ui/embed/sofabaton-remote.js from the server and place <sofabaton-remote hub="..."> on any page whose origin you list under Server settings → Access (or install sofabaton-x-remote from npm). See the web remote guide for layout options, device mode and dashboard embedding.

Connect an automation platform

The server provides activity control, command sending, hub state and remote-button events for integrations. Wifi Commands lets you assign selected remote buttons to events an integration can receive. An integration must receive those events and run the actions in your platform.

The Hubitat example demonstrates activity switches, command actions and button events. Developers can use the same API to build integrations for other platforms.

For setup, see Wifi Commands. For delivery details, see the button-event and MQTT reference.

Build an integration

Use the server as the starting point for a platform integration. Let users configure their hubs in the panel, then select those hubs in your client. Your integration can focus on controls, state and automations, and link back to management and the web remote.

  • Build an integration: activity controls, synchronized state, command actions and remote-button triggers, with an optional runnable client.
  • Platform integration guide: production behavior, errors, reconnection and optional editing flows.
  • API reference: snapshots, jobs, writes, recovery, IR payloads, backups, discovery and events.
  • OpenAPI document: the committed contract for generated clients. A running server also serves interactive docs at /api/v1/docs.

Help and releases

Start with setup troubleshooting. For a bug report, open an issue with your server version, hub model and firmware, installation method, relevant logs and steps to reproduce the problem.

This README describes 0.2.7, using API 1 and sofabaton-x >=0.2.6,<0.3. Read the changelog and upgrade notes when updating. This release edits activity and device icons (and X2 colors) and X2 IR emitter routing, tests that Wifi Device presses reach the server, opens X2 Wifi commands made in the Sofabaton app in the HTTP form, and sends the cheapest remote sync after each write. Existing access settings, hub registrations, Wifi Devices and saved layouts carry forward without conversion.

Development

See server development for building the UI, tests, OpenAPI generation and releases.

Metadata

Release files for sofabaton-x-server 0.2.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sofabaton-x-server 0.2.7
File Size Uploaded Provenance Actions
sofabaton_x_server-0.2.7.tar.gz 1.0 MB With provenance Details for sofabaton_x_server-0.2.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sofabaton-x-server 0.2.7
File Interpreter ABI Platform Actions
sofabaton_x_server-0.2.7-py3-none-any.whl Python 3 none any Details for sofabaton_x_server-0.2.7-py3-none-any.whl

Total release size: 1.8 MB

Release files / sofabaton_x_server-0.2.7.tar.gz

Download URL sofabaton_x_server-0.2.7.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
f7403911dcd829d1092aea80e427ca1562aa220ca98f30ea9baeeb332650e86c
BLAKE2b-256 checksum
How to use checksums
08f542584b0216dfe829cfa99a6b6abcd39261c96e575dfccd197ff1a4606a33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / sofabaton_x_server-0.2.7-py3-none-any.whl

Download URL sofabaton_x_server-0.2.7-py3-none-any.whl
Size 805.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8c75fbc4a4f81159ea4a135500687aa3a30e0297489a5708985c4907c6010575
BLAKE2b-256 checksum
How to use checksums
2ba3b4f7483b0a233962fb9fb3b9dac89012bc7c609323bff801c21a9534d506
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for sofabaton-x-server 0.2.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sofabaton_x_server-0.2.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page