Install ServerBee Natively with Localtonet Access

How the ServerBee deployment works

ServerBee is a self-hosted server-monitoring platform built around a central server and lightweight agents. The central server receives metrics from enrolled agents, stores data in embedded SQLite, and serves the browser dashboard. Agents stream metrics and events to the server over WebSocket connections, while the browser dashboard uses real-time communication to display changing CPU, memory, disk, network, load, temperature, disk I/O, and other available information.

For this tutorial, the central server and its embedded web interface run as a native Linux binary. ServerBee's project documentation recommends Docker for the central server, but it explicitly supports a binary server installation. Native binaries are recommended for agents because they provide host-level access with a small footprint. Choosing a native central server can still be appropriate when you prefer systemd-managed services, do not want a container runtime on the monitoring host, or want to keep deployment components to a minimum.

The documented default listener is 0.0.0.0:9527. That means the service accepts connections on port 9527 through the host's available network interfaces, subject to host and network policy. The local dashboard address on the server itself is therefore:

http://127.0.0.1:9527

On another machine that can already reach the Linux host, the corresponding address is normally http://SERVER_ADDRESS:9527. Do not assume that this address is publicly reachable. NAT, cloud security groups, host firewalls, and upstream routing can all prevent inbound access. Opening the port directly is also not always desirable for an administrative monitoring interface.

With Localtonet, the client on the ServerBee host establishes an outbound connection to one of our relay servers. An HTTP tunnel can then connect a public HTTPS address to the local ServerBee HTTP service. This does not require an inbound router port-forwarding rule, a public IP address, VPN setup, or an inbound firewall change. The public endpoint remains available only while the selected Localtonet client is connected and the tunnel is running.

Prerequisites and deployment decisions

Prepare a Linux host on which you can run commands through sudo or as an appropriately privileged administrator. The documented installer uses a downloaded shell script and hands service management to systemd. The host also needs outbound network access so that it can retrieve the installer and ServerBee release artifacts.

The evidence for this guide does not establish a complete Linux distribution, CPU architecture, minimum kernel, memory, or disk-support matrix. We therefore do not recommend guessing a package name or manually choosing a release asset. Let the official installer evaluate the current host and stop if it reports that the operating system or architecture is unsupported.

You will need the following:

• A Linux server or virtual machine with systemd.
• Administrative access through sudo or an equivalent root session.
• curl for downloading the official installer and testing the HTTP endpoint.
• Outbound HTTPS connectivity to retrieve ServerBee files.
• Local capacity for the ServerBee binary, configuration, logs, and monitoring data.
• A browser for signing in to the dashboard.
• A Localtonet account and client installation if the dashboard will be exposed remotely.

Decide where the central server belongs before enrolling agents. An agent needs a server URL it can continue to reach after enrollment. If agents are on the same private network, an internal ServerBee URL may be sufficient. If remote agents will connect through the Localtonet public address, establish and test that address before generating their final installation commands. The ServerBee dashboard's Add Server workflow generates the enrollment command, so it is safer to let the dashboard provide the current command rather than constructing one from memory.

Install the ServerBee server as a native binary

ServerBee's installer accepts a component and an installation method. The component is server, and the method for this tutorial is binary. Specifying the method avoids the interactive choice and prevents accidentally selecting Docker.

Run the installation command:

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh -s -- server --method binary

The installer places the serverbee/usr/local/bin/serverbee and arranges for systemd to manage the installed service. Because the project is actively developed, read the command output rather than assuming that every installer message, downloaded version, or generated value will remain identical over time.

After installation, check all ServerBee component states:

sudo serverbee status

A successful installation should report the central server as active. If it does not, do not create a tunnel yet. Remote exposure cannot repair a service that failed to install, cannot read its configuration, or is not listening locally.

Understand and configure the native server

The documented native-server configuration file is /etc/serverbee/server.toml. ServerBee also supports environment variables prefixed with SERVERBEE_. For nested settings, two underscores act as the separator. For example, the project documents SERVERBEE_AUTH__MAX_SERVERS as the environment-variable form of a nested authentication setting.

A minimum TOML configuration has the following shape:

[server]
listen = "0.0.0.0:9527"
data_dir = "/var/lib/serverbee"

[admin]
password = ""

The listen value defines the address and port accepted by the central server. The default shown by the project is 0.0.0.0:9527. The data_dir setting identifies the persistent data location. An empty initial administrator password tells ServerBee to generate one and print it during startup.

Do not copy the example blindly over an installer-generated file. First inspect the existing configuration through the installed management command:

sudo serverbee config

Use that command to view or set configuration according to its current interactive behavior. The available options can evolve with ServerBee releases, so this guide does not invent undocumented flags for changing individual values.

Choosing the listener address

Keeping 0.0.0.0:9527 allows the service to receive direct network connections where firewall and routing policy permit them. That can be useful when private-network agents connect directly to the central server. It can also make the dashboard reachable from more interfaces than intended if the host has permissive network rules.

Binding only to loopback can reduce direct network exposure when every browser and agent connection is deliberately routed through a local reverse proxy or tunnel client. However, changing ServerBee to 127.0.0.1 would prevent agents on other machines from connecting directly to port 9527. Choose the binding based on the complete agent topology, not only browser convenience.

Applying a configuration change

Restart ServerBee after changing a setting that requires service reload:

sudo serverbee restart

Then check the state again:

sudo serverbee status

If the service fails after an edit, compare the changed values with the documented TOML structure. Quotation errors, malformed section names, invalid paths, and an unavailable listener address can prevent startup. Restore the previous known-good configuration instead of continuing to modify several settings at once.

Back up the persistent state

ServerBee includes backup and restore functionality, and the documented minimum configuration stores its data under /var/lib/serverbee. Establish backups before the monitoring history becomes operationally important. A complete backup policy should account for both persistent data and the effective configuration. Protect backup copies because they can contain operational information about monitored systems.

Verify ServerBee locally before exposing it

Local verification separates application problems from tunnel problems. A healthy service should answer on port 9527 before the Localtonet client is involved. Perform the first test on the ServerBee host so that routing, NAT, and external firewall behavior cannot obscure the result.

Test the local endpoint with:

curl -v http://127.0.0.1:9527/

The exact response body can change between ServerBee releases, so the important result is that the TCP connection succeeds and the server returns an HTTP response. A connection-refused error means nothing is listening at that address and port. A timeout can point to an incorrect address, routing issue, or filtering when the test is made from another host.

If the service is active but the loopback request fails, check whether the configured listener still uses port 9527. On systems that provide the ss utility, this general Linux diagnostic can show listening TCP sockets:

sudo ss -ltn

Look for port 9527 and compare its bound address with the URL being tested. A listener on 127.0.0.1:9527 accepts only local connections. A listener on 0.0.0.0:9527 accepts connections through the host's IPv4 interfaces, subject to network policy.

Enroll agents and perform routine operations

Once the central server is healthy, sign in as an administrator and choose Add Server. ServerBee generates an installation command containing a server-bound enrollment offer. That offer is single-use and expires after about ten minutes. Generate it only when you are ready to run it on the target node.

A documented agent installation has this structure:

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh -s -- agent --method binary \
  --server-url http://YOUR_SERVER:9527 \
  --enrollment-code YOUR_ONE_TIME_CODE

Treat this block as an explanation of the command structure, not as a reusable enrollment command. Replace neither value by guessing. Copy the current command from your own ServerBee dashboard so that it contains the correct server URL and a fresh one-time code.

The native binary method is recommended for ServerBee agents because it provides host-level metrics and the smallest documented deployment footprint. A Docker agent is also supported, but container isolation changes which host resources are visible. Prebuilt agents do not include optional NVIDIA GPU metric support. That support requires a self-built agent with the project's GPU feature enabled.

During first enrollment, the agent generates and persists its run token before claiming the offer. The one-time enrollment code is required only for the initial claim. The agent then uses its persisted token for subsequent reconnections. Never copy an existing agent's token to another machine.

Routine management commands

The native installer provides a management interface for common lifecycle operations:

sudo serverbee status
sudo serverbee restart
sudo serverbee config

To upgrade to the latest release on the selected stable path, the project documents:

sudo serverbee upgrade -y

A beta-channel upgrade is also available:

sudo serverbee upgrade --channel beta -y

Do not use the beta channel on an operational monitoring server merely because it has a newer version number. ServerBee is under active development, and prerelease builds can change behavior rapidly. Back up the service, configuration, and data before upgrades, then verify the dashboard and connected agents afterward.

If an agent must be removed from a host, the documented uninstall command is:

sudo serverbee uninstall agent -y

That command specifically targets the agent. Do not substitute server without first checking the current management command's behavior and confirming that you intend to remove the central service and its relationship to persistent data.

Expose the working dashboard with Localtonet

After ServerBee works locally, use an HTTP tunnel to make its dashboard reachable through a public HTTPS address. The Localtonet client must run on the ServerBee host or on another device that can reach the configured ServerBee IP address and port. Running it on the same host makes 127.0.0.1:9527 the simplest local target.

Creating a tunnel does not automatically make it active. You must select the client device, configure the HTTP target, choose a currently available relay server, and press Start. The assigned public address works only while that selected client remains connected and the tunnel is running.

The target values for a same-host installation are:

Local IP:   127.0.0.1
Local port: 9527
Protocol:   HTTP

Use an HTTP tunnel rather than a raw TCP tunnel for the browser dashboard unless your specific architecture has a separate reason to expose the raw port. HTTP is the application protocol presented by ServerBee, and Localtonet HTTP and File Server process types provide public HTTPS addresses.

For current dashboard details, consult our Localtonet HTTP tunnel documentation. Client installation interfaces and available relay selections can change, which is why this guide does not invent an installation command, token, region code, or plan-specific option.

Verify WebSocket traffic through the public address

ServerBee specifically requires WebSocket handling for /api/ws/ and /api/agent/ws. The first path is associated with real-time application communication, while the second is used for agent communication. If another reverse proxy sits between Localtonet and ServerBee, it must forward WebSocket Upgrade and Connection headers and use a suitably long read timeout.

Test the public endpoint in layers:

• Open the assigned public HTTPS address and confirm that the login page appears.
• Sign in and navigate between dashboard views.
• Confirm that metric values update without manually refreshing the page.
• Check that enrolled agents remain connected rather than cycling between online and offline.
• If you use browser developer tools, inspect the Network panel and confirm that WebSocket requests do not repeatedly fail or disconnect.
• Test terminal or other real-time functions only after granting the minimum required ServerBee capabilities.

Secure the dashboard and remote workflow

A ServerBee dashboard contains infrastructure details and can expose administrative functions. Depending on enabled capabilities, ServerBee supports remote terminal sessions, a file manager, Docker operations, firewall controls, and remote commands. Publishing the login page therefore deserves the same care as publishing another privileged operations console.

Change the auto-generated administrator password during the first session and store the replacement in a password manager. ServerBee supports OAuth, TOTP two-factor authentication, administrator and member roles, audit logs, and agent-owned capability gates. Use those controls according to your deployment needs. Do not rely solely on the obscurity of a generated public hostname.

Agent enrollment codes are server-bound, single-use, and short-lived, but they are still credentials during their validity period. Do not place one in permanent shell scripts, documentation, screenshots, or ticket history. Generate an offer immediately before installation and generate a new one if the previous code expires or might have been disclosed.

The Localtonet tunnel removes the need for inbound port forwarding, but it does not replace application authentication or authorization. Anyone who can reach the public URL can attempt to access the exposed login surface. Keep ServerBee current, review audit activity, disable unused capabilities, and stop the tunnel when its availability is no longer required.

If agents use the public tunnel as their central server route, stopping it also disconnects those agents. In that topology, treat tunnel uptime as part of the monitoring design rather than as an occasional administrator convenience. If only browsers use the public URL and agents connect privately, stopping the tunnel can remove browser access without interrupting private agent communication.

Troubleshoot installation, dashboard, and tunnel problems

The installer does not complete

Confirm that the machine is Linux, uses systemd for the intended workflow, has curl, can reach the official repository over HTTPS, and allows the administrative operation. Read the installer's error instead of manually selecting an unverified binary asset. The supplied evidence does not define every supported distribution and architecture, so an explicit compatibility error should not be bypassed by guessing.

The ServerBee installer is designed to support reruns and upgrades more safely, including atomic configuration writes. Nevertheless, preserve existing configuration and data before retrying on a host that already contains a deployment.

The management command reports an inactive service

Start with:

sudo serverbee status

If the failure followed a configuration edit, restore the last known-good TOML and restart:

sudo serverbee restart
sudo serverbee status

Check the listener syntax, data-directory path, TOML quotations, and section names. Avoid changing the listener, administrator settings, and storage path simultaneously because that makes the cause harder to isolate.

Port 9527 refuses a local connection

Verify that the server is active and that the configured port remains 9527. Test the exact loopback URL:

curl -v http://127.0.0.1:9527/

If ServerBee is bound to another local address, adjust the test accordingly. If the Localtonet client runs on a different device, remember that 127.0.0.1 on that device refers to the client device itself, not the ServerBee host.

The public URL shows a gateway or connection error

Confirm that the ServerBee endpoint still works locally. Then confirm that the selected Localtonet device is connected, the HTTP tunnel has been started, and the target IP and port are correct. Creating a tunnel without starting it does not make the endpoint available. A tunnel also goes offline when its selected client disconnects.

If the client and ServerBee are on separate hosts, test http://SERVER_ADDRESS:9527 from the client host. Local success on the ServerBee machine does not prove that a second device can reach it.

The page loads but metrics do not update

This usually narrows the problem to real-time communication rather than basic HTTP reachability. Inspect WebSocket requests for /api/ws/. If there is an additional Nginx, Caddy, load balancer, or application proxy in the route, confirm that it forwards Upgrade and Connection headers and does not close the connection with an overly short read timeout.

Also test the dashboard directly against the local ServerBee address. If local WebSockets fail too, troubleshoot ServerBee before changing the Localtonet tunnel. If they work locally but fail only through the final public route, inspect each intermediary in that route.

Agents cannot enroll or remain disconnected

Generate a fresh command from Add Server. Enrollment offers expire after about ten minutes and can be used only once. Confirm that the agent host can reach the exact server URL included in the command. If that URL uses the Localtonet public endpoint, the client and tunnel must remain running during enrollment and subsequent operation.

Do not reuse an enrollment command across multiple hosts. Each agent should claim its own offer and persist its own run token. If an agent disconnects later, focus on continued reachability to the central URL, tunnel state where applicable, and whether an intermediary permits the long-lived /api/agent/ws connection.

An upgrade introduces unexpected behavior

Verify which release channel was selected. The stable upgrade and beta-channel upgrade are separate documented commands. Restore from your backup if the new release is incompatible with your environment, then review the project's current release information before retrying. Do not downgrade database-backed applications by replacing only the executable unless the project explicitly documents that path for the versions involved.

Frequently asked questions