Self-Host ioBroker and Access It with Localtonet

How ioBroker and Localtonet fit together

ioBroker provides an integration layer for systems that need to exchange configuration, state, and event data. It uses objects for metadata and configuration and states for changing values. Adapters run as separate processes and connect supported technologies to this common model.

ioBroker can keep objects and states in its built-in storage or use Redis. Its project documentation describes the platform as being designed for trusted adapters inside trusted networks. That creates a clear security boundary: databases, Redis, arbitrary adapter ports, and individual smart-home device services should not be published merely because remote administration is required.

The administration adapter provides the browser interface used to configure and operate the system. A default installation commonly makes this interface available at http://HOST:8081, where HOST is the ioBroker machine's local address or name. Port 8081 is a default, not an immutable value. An existing deployment may use another port, bind to a different interface, or use HTTPS, so verify the installed Admin adapter configuration before creating a tunnel.

With Localtonet, our client runs on the ioBroker host or another trusted device that can reach it. The client establishes an outbound connection to a Localtonet relay. An HTTP tunnel then supplies a public HTTPS address for the configured local web target, without requiring inbound router port forwarding, firewall changes, a public IP address, or VPN setup.

For project-level information, use the primary ioBroker repository, the ioBroker documentation, and the ioBroker release history. Release information matters because Node.js compatibility, installer behavior, and upgrade requirements can change.

Prepare the ioBroker host

ioBroker's controller can run on ARM or x86 hardware using an operating system supported by Node.js. The project identifies Linux, Windows, and macOS as possible platform families. This tutorial provides the repository's documented Linux and Windows installation paths. Although the controller can run on macOS, the supplied primary installation evidence does not establish a complete current macOS production-service procedure, so it is not presented here as an equivalent always-on installation path.

Choose a suitable operating system and account

Start with a maintained operating system that still receives security updates. On Linux, use a normal administrative account that can invoke sudo when the installer requests system changes. Avoid running the entire installation as the root user unless the current installer explicitly directs you to do so. Current ioBroker installer work includes checks and warnings around root execution, so bypassing those controls is not a neutral choice.

On Windows, use an account permitted to create the installation directory and install or manage the ioBroker service. If Windows security controls request elevation for a service or installer action, review the request rather than disabling those controls globally.

Use a release-compatible Node.js version

ioBroker depends on Node.js, but the supported runtime lines belong to the selected ioBroker controller release rather than to this tutorial. The current repository release evidence identifies ioBroker 7.0.1 as the latest release dated October 13, 2026, and its diagnostics include a recommended Node.js version hint. The installer and iob diag output are therefore the release-aware compatibility checks to follow.

Use an even-numbered Node.js LTS line that the selected ioBroker release explicitly supports. Do not assume that the newest Node.js release, an old distribution package, or an odd-numbered development line is compatible. Before a new installation, check the release notes and installer check. On an existing installation, run:

iob diag

Review the reported installed and recommended Node.js versions before changing the runtime. If the command is unavailable outside the installation environment, run it from the ioBroker host using the command wrapper created by the installer. The current ioBroker release also provides the managed updater command:

iob nodejs-update

Do not run that updater merely to discover what it will do on a production server. Read its prompts and current release notes, create a backup first, and schedule an interruption window.

Plan memory, storage, and networking

ioBroker starts a separate Node.js process for every adapter instance. The project estimates approximately 10 MB to 60 MB per adapter, but this is not a complete host requirement. The controller, Admin adapter, operating system, databases, logs, visualizations, and file caches also consume resources. Actual demand depends on the enabled adapters and workload.

If the Localtonet client will run on another device, confirm that this device can reach the ioBroker host over the trusted LAN. Do not broaden ioBroker's network binding or disable a firewall until you understand why communication is failing.

Install ioBroker on Linux or Windows

The ioBroker repository documents a direct npx installer for Linux. For Windows, it documents either a command-line installation under C:\iobroker or the project's Windows installer. Use one path rather than combining their files or service definitions.

Linux installation

node --version
npx --version
npx @iobroker/install

A standard Linux installation normally creates the ioBroker environment under /opt/iobroker and establishes service startup through the installer. Treat the installed configuration as authoritative if a deliberately customized deployment uses another location.

Windows command-line installation

Open an administrative Command Prompt, create the documented directory, enter it, and run the package installer:

mkdir C:\iobroker && cd C:\iobroker && npx @iobroker/install

Keep the installation on persistent local storage. Review all installer prompts and completion messages. Do not copy a partially installed directory between machines as a replacement for installation and restore.

Windows graphical installer

The project also supplies a Windows installer from its main repository. This is an alternative to the command-line path, not an additional step. Use the current installer linked by the project, complete its service and installation prompts, and preserve the selected location. Interface text can change between releases, so use the current package rather than an archived screenshot or third-party download.

Check controller status and startup

The ioBroker command wrapper provides controller lifecycle checks across installed environments. After installation, check status:

iob status

If the controller is installed but stopped, start it:

iob start

The corresponding maintenance controls are:

iob stop
iob restart

These commands control the ioBroker controller. They are not substitutes for verifying that the operating-system service is configured to return after a reboot. Complete the post-reboot test in the operations section before relying on unattended operation.

Complete the first-run ioBroker setup

Begin on the trusted local network. For a default installation, open:

http://IOBROKER-HOST:8081

Replace IOBROKER-HOST with the ioBroker machine's local IP address or resolvable local name. If you are browsing directly on the host and the Admin adapter accepts loopback connections, http://127.0.0.1:8081 can be used as a local test.

If the page does not open, do not scan nearby ports and select one at random. Run iob status, inspect logs, and check the Admin adapter's installed configuration. Existing systems can use a changed port, HTTPS, or a restricted bind address.

Follow the setup wizard

A new installation can present first-run configuration in the browser. Complete the displayed language, regional, and system settings deliberately. Confirm the location and units where relevant to automations. Add only the adapters required for the initial test. Installing many adapters before validating the base controller makes later failures harder to isolate.

Confirm that the Instances view shows the Admin adapter running and that navigation between the main administration pages works. A browser receiving any response from port 8081 is not sufficient. The actual administration application must load and display the expected controller state.

Confirm a changed administration endpoint

In the ioBroker administration interface, open the Instances view and edit the configuration of the Admin adapter instance, normally admin.0. Record its configured port, binding address, and whether secure HTTPS mode is enabled. Save only intentional changes and wait for the adapter to restart before testing the new URL.

The resulting local target consists of three separate values:

• The protocol expected by the Admin adapter, either HTTP or HTTPS.
• The address reachable from the Localtonet client.
• The configured Admin adapter port, commonly 8081 unless changed.

Enable and test ioBroker authentication before exposure

Do not rely on the public URL being difficult to guess. Before creating a Localtonet tunnel, set a password for the administrative ioBroker user, enable authentication on the Admin adapter, restart it, and prove that a browser with no existing session is denied access until valid credentials are supplied.

Set the administrator password interactively:

iob user passwd admin

Do not append the password to the command. If your installed command wrapper displays different syntax, use iob help and the current ioBroker command documentation for that release rather than exposing a credential in a workaround.

Verify ioBroker locally before creating a tunnel

Remote access should be the final connectivity layer. Establish a known-good local baseline so that a controller issue is not mistaken for a tunnel problem.

On Linux, a direct HTTP response check can supplement the browser test:

curl -I http://127.0.0.1:8081

Change the scheme, address, and port to match the installed Admin adapter. A response proves that an HTTP service answered, but it does not replace the private-browser authentication test.

For diagnostics and recent logs, use:

iob diag
iob logs --watch

Stop the live log view after collecting the required information. Logs can include host names, device identifiers, adapter details, and other private information, so redact them before sharing.

Connect the verified ioBroker interface through Localtonet

Follow the current Localtonet HTTP tunnel documentation while configuring the dashboard. The documented sequence is to run the client, open the HTTP Tunnel page, select the process type, select the device token and relay server, enter the local target, and then start the tunnel.

Public HTTPS and the local target are separate connections

The public address for the Localtonet HTTP tunnel is HTTPS. The ioBroker target can still be local HTTP if that is what the Admin adapter serves. Public HTTPS does not mean that the local application has silently changed from HTTP to HTTPS, and entering the wrong local protocol can cause handshake failures, resets, or redirect problems.

When Localtonet and ioBroker run on the same machine, a loopback HTTP target keeps that local hop on the host. When they run on different machines, local HTTP traffic crosses the LAN between those hosts. That traffic should be confined to a trusted or appropriately segmented network. If the Admin adapter is configured for local HTTPS, target it as HTTPS and make sure the Localtonet client host can complete the connection using the certificate configuration in place.

Test from outside the LAN

Open the assigned public HTTPS URL using a device on another network, such as a mobile connection with Wi-Fi disabled. Use a private browser window. Confirm that the ioBroker login appears before administration content, an invalid password fails, and valid credentials open the expected system.

Stop the tunnel immediately if it reaches the wrong application, exposes ioBroker without authentication, or displays an unexpected service. Correct the local target and repeat local verification before restarting it.

Secure the remote administration path

Expose only the Admin adapter

Point the HTTP tunnel only to the verified administration endpoint. Do not create public tunnels for ioBroker object or state databases, Redis, arbitrary adapters, or individual smart-home devices. If an adapter is intentionally designed to receive internet traffic, assess that adapter separately using its current security documentation.

Protect both account systems

ioBroker credentials protect the application. The Localtonet auth token identifies the client device. Treat them as separate secrets. Do not place passwords or tokens in screenshots, shell commands, repositories, tickets, shared notes, or URLs.

Use a unique ioBroker administrator password. Where users require different access levels, create separate accounts and apply the controls supported by the installed ioBroker release instead of sharing one administrator login.

Keep the local path trustworthy

If the tunnel client is separate from the ioBroker host, protect the LAN path with segmentation and host firewall rules appropriate to the deployment. Bind the Admin adapter only as broadly as required for the chosen client to reach it. Do not bind every interface or disable the host firewall merely to make troubleshooting easier.

Use tunnel lifecycle controls

Stop the tunnel outside maintenance windows when continuous remote administration is unnecessary. Stopping preserves the configuration for later use. Delete obsolete tunnels so that an old target cannot be restarted accidentally.

Standard Localtonet HTTP tunneling is not a VPN. If the requirement is private network membership rather than a public application URL, Localtonet VPN Manager is the separate private mesh VPN feature.

Back up, update, restore, and verify the deployment

Create a controller backup

Create an ioBroker backup before controller updates, Node.js changes, major adapter updates, authentication changes, or host migration:

iob backup

Wait for successful completion and record the resulting archive. A backup stored only inside the ioBroker installation is vulnerable to the same disk failure as the live system, so copy the archive to protected storage on another device.

Backups can contain automation configuration, device identifiers, network information, and adapter credentials. Restrict access and do not place them in a public file share.

Test the restore procedure

A backup is trustworthy only when its archive can be read and its restore workflow is understood. List the available controller backups using the installed command help and select the intended archive explicitly. Stop active changes before restoration, then restore with:

iob restore BACKUP

Replace BACKUP with the backup identifier or path accepted by the installed release. Follow the command's prompts, restart ioBroker if instructed, and repeat controller, adapter, authentication, and local browser checks. Never experiment with restoration for the first time during an unrehearsed production failure.

Run diagnostics before updating

iob diag
iob backup

Review the current ioBroker release notes for controller changes and runtime requirements. The release notes are especially important before changing Node.js. Resolve existing diagnostic errors before introducing another variable.

Update in controlled stages

Use the Admin interface or the installed ioBroker command workflow to review available repository and adapter updates. Update one major layer at a time:

1. Create and copy a backup off-host.
2. Review controller, adapter, and Node.js compatibility.
3. Stop the Localtonet tunnel during invasive maintenance.
4. Apply the intended ioBroker or adapter update.
5. Check iob status and logs.
6. Test the local login and required automations.
7. Restart the tunnel and test the public login only after local verification succeeds.

For a release-supported Node.js change, use the maintained updater rather than replacing runtime files manually:

iob nodejs-update

Read every prompt. Current release notes also describe improvements to this updater and an interactive option to run iob fix after a successful installation. Do not run repair commands routinely without understanding the reason, and preserve diagnostics before making changes.

Plan rollback instead of assuming one command exists

ioBroker does not provide one universal rollback that can reverse every controller, Node.js, operating-system, database, and adapter change. The practical rollback boundary is the verified backup plus the release-specific installation requirements.

If an update fails, stop further changes, preserve logs, and determine which layer changed. Restore the pre-change backup only into a compatible ioBroker environment. If the runtime or controller must also be reverted, follow the release notes for that version rather than forcing an older package over a newer data layout.

Inspect logs

Use the controller's log command for current output:

iob logs --watch

Standard Linux installations normally keep log files under /opt/iobroker/log. A Windows command-line installation normally keeps them under the installation tree, such as C:\iobroker\log. Customized installations can differ, so the running installation and command output remain authoritative.

Verify startup after a reboot

Troubleshoot installation and remote-access problems

npx is not recognized

Confirm that a release-compatible Node.js toolchain is installed and available to the current terminal. Reopen the shell after installation if its environment has not refreshed. Do not solve the problem by installing an arbitrary Node.js release without checking ioBroker compatibility.

The installer fails with a permission or root warning

On Linux, use a normal account with working sudo access and let the installer request elevation. Do not manually change ownership across the ioBroker tree or add the service account to powerful system groups as a shortcut. Preserve the first meaningful error, then use iob diag or the current project support guidance.

Port 8081 does not open

Run iob status and inspect logs. Port 8081 is the documented default, but the Admin adapter can be changed. Check the installed Admin adapter configuration for its protocol, bind address, and actual port. A failure at a guessed URL does not prove that the controller is stopped.

The page works on the ioBroker host but not from the Localtonet device

This normally indicates a local binding, host firewall, routing, name-resolution, or segmentation problem. A service bound only to 127.0.0.1 is reachable only on the ioBroker host. Either run Localtonet on that host or deliberately configure a LAN-reachable Admin binding protected by the local network controls. Do not expose it on every interface without assessing the effect.

The public URL does not work

• Open the ioBroker URL from the Localtonet client device.
• Confirm that the selected Localtonet device is connected.
• Confirm that the HTTP tunnel was explicitly started.
• Check the configured local address and port.
• Confirm that the local HTTP or HTTPS selection matches ioBroker.
• Review whether a reboot, address change, firewall rule, or certificate change occurred.

Do not create several tunnels to nearby ports. Return to the exact locally verified endpoint and correct the existing configuration.

The public URL reaches the wrong service

Stop the tunnel immediately. Recheck the target address and port, especially when the client host runs several web applications. Verify ioBroker from the same machine that runs Localtonet, update the target, and repeat the external private-browser test.

The public URL bypasses the login

Stop the tunnel. Confirm the result in a new private browser window to eliminate an existing session. If administration content remains visible without credentials, correct the Admin adapter authentication setting, restart the adapter, and retest locally before restarting Localtonet.

HTTP and HTTPS errors appear

Confirm the local Admin adapter protocol. A Localtonet public HTTPS URL can target a local HTTP service, but the tunnel target must still be configured according to what ioBroker actually serves. Sending HTTP to a local HTTPS listener, or HTTPS to a local HTTP listener, can produce resets, handshake errors, or malformed responses.

Remote access stops after a reboot

Check the chain in order: host availability, iob status, local Admin URL, Localtonet client connection, and tunnel running state. This identifies the missing layer without changing a working target.

The system becomes unreliable after adding adapters

Inspect memory, processor use, disk space, and adapter logs. Each adapter instance creates another Node.js process and can use approximately 10 MB to 60 MB, with real consumption depending on its workload. Disable or correct the recently added adapter according to current ioBroker guidance before changing the tunnel.

Frequently asked questions