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

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, a computer that can stay running on its network, and Python 3.11+ or Docker on Linux.

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.

Install the server and start it (the protocol library is included):

python -m pip install "sofabaton-x-server>=0.2.3,<0.3"
sofabaton-x-server

Open http://<server>:8480/, or http://localhost:8480/ on the server computer. 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. Until you set up access (Server settings → Access in the panel), anyone on your network can change your hubs; after that, changes need the panel's sign-in or a token, while reading and the remote stay open. Use the server on a trusted LAN or behind an authenticating reverse proxy. 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.3, using API 1 and sofabaton-x >=0.2.2,<0.3. Read the changelog and upgrade notes when updating. This release adds the embeddable remote and layout export for other dashboards, improves the layout Save menu and panel navigation, and limits the DVR layout switch to X2 hubs. Existing access settings, hub registrations and saved layouts carry forward without conversion.

Development

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