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 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.5,<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.5, using API 1 and sofabaton-x >=0.2.4,<0.3. Read the changelog and upgrade notes when updating. This release adds per-hub server IP overrides, improves multi-interface routing, lets you copy favorites between activities, and updates the control panel and web remote. 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.