How to Self-Host Beszel in 2026: Agents, Private Networking and Backups

The shortest Beszel demo proves that a process listens on port 8090. Production needs stronger evidence. It must pass this scenario even after the container has been replaced: enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart.

Beszel is being deployed for a clear purpose: lightweight server monitoring in a small container. Its most common deployment trap is that the hub cannot reach port 45876 on an agent or its SSH key changed, so public URL handling and durable state receive the same attention as image startup.

Draw the Beszel runtime boundary

Process health and product health are separate for Beszel. Port 8090 may answer while the user-facing transaction still fails. The network contract for Beszel is a Beszel agent on every monitored machine. Keep private endpoints on internal DNS, permit only required outbound calls and give Beszel a scoped service credential.

Use this readiness exercise after meaningful configuration changes: enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart. Keep expensive external checks out of liveness probes so a provider outage does not cause a restart loop. Capacity work should track agent count, metrics retention, hub storage and network reachability to each agent on its dedicated port, which is closer to Beszel's real pressure than page requests.

Make the public origin unambiguous

The browser, API client and Beszel must agree on one origin. To make that true, route the hub through HTTPS and keep agent ports private. Preserve the original host and protocol while keeping port 8090 unavailable as a competing public address.

The site-down troubleshooting guide helps distinguish an unreachable route from a responding application. That distinction matters here: the hub cannot reach port 45876 on an agent or its SSH key changed. Only the former is fixed by ingress changes; the latter needs Beszel logs, state or workload inspection.

Run the first production-shaped instance

The first container should be easy to delete and recreate. Keep data off the writable layer, bind port 8090 only where the proxy can reach it and pass configuration at runtime.

docker run -d \
  --name beszel \
  --restart unless-stopped \
  -p 127.0.0.1:8090:8090 \
  -v beszel-data:/beszel_data \
  henrygd/beszel:latest

Pin the image after the initial test. Read the earliest startup error rather than the final restart message, verify each mount with docker inspect, and follow logs while you enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart. That sequence distinguishes a bad image command from a dependency or permission problem.

Logs that answer the next question

A green container is necessary but not sufficient. The service-level indicator is successful completion of “enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart”, while the likely pressure signals are agent count, metrics retention, hub storage and network reachability to each agent on its dedicated port.

Change control matters because hub and agent versions should be tested together because protocol changes can look like silent monitoring gaps. Preserve the old image, test migrations on copied state and document whether rollback is supported after the schema moves. If the hub cannot reach port 45876 on an agent or its SSH key changed, diagnose the first boundary that differs from the working environment.

A production acceptance run for Beszel

Before real users arrive, make a release worksheet for Beszel. It must name the pinned image, port 8090, canonical origin, persistent paths and the owner of a Beszel agent on every monitored machine. Attach the expected result of this transaction: enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart.

Use the worksheet after a normal replacement and after a clean restore. Recovery is accepted only if systems, history and alerts return and every restored agent resumes sending current metrics. Also collect a short resource trace covering agent count, metrics retention, hub storage and network reachability to each agent on its dedicated port; keep it beside the release so future capacity changes are compared with the same workload.

Include one controlled failure: temporarily deny the test identity access to a Beszel agent on every monitored machine. Confirm Beszel reports the problem at the correct boundary, put the valid condition back and rerun the transaction. This checks error visibility, not merely success, and prevents a healthy-looking interface from concealing a broken worker, callback or database connection.

Design the Beszel restore before launch

Inventory every durable artifact: hub data, users, systems and alert configuration. Mount /beszel_data before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Include configuration that changes how stored data is interpreted, not only the largest directory.

Set retention, copy backups off-host and run a clean-room restore. The Beszel drill is complete when systems, history and alerts return and every restored agent resumes sending current metrics. If snapshots are part of the plan, use PITR versus snapshot guidance to document what each mechanism can recover.

Close temporary setup access

Threat-model the action Beszel performs, not just its login form. Here the high-risk mistake is publishing agent listeners to the internet without network controls. Implement this boundary: keep agent listeners on private networks and protect the hub account and enrollment keys.

Beszel has no mandatory bootstrap secret in this baseline; protect its actual administrator account or upstream authentication instead. Do not solve a permission error by running the container as root or mounting the host broadly. Resource limits also belong to the security design when agent count, metrics retention, hub storage and network reachability to each agent on its dedicated port can be triggered by users.

Move the repeatable infrastructure work to Dockup

For Beszel, Dockup is most useful at the boundary between an image and a durable service. It keeps the route to 8090, TLS, secret values and storage attached across container replacements, whether the compute belongs to Dockup or to your attached server.

Finish with application knowledge: route the hub through HTTPS and keep agent ports private; connect and test a Beszel agent on every monitored machine; and run this verification: enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart. Keep the result as a deployment check so the next image update is judged by behavior rather than by container status.

Frequently asked questions

What does Beszel need for a production deployment?

Route the Beszel container on port 8090 through one HTTPS origin. The supporting network requirement is a Beszel agent on every monitored machine. Do not call Beszel ready until you can enroll an agent, observe CPU, memory and disk charts, trigger a threshold alert and reconnect the agent after a hub restart.

Which Beszel data belongs in a backup?

Persist /beszel_data and include hub data, users, systems and alert configuration in the same recovery manifest. A clean Beszel restore passes only when systems, history and alerts return and every restored agent resumes sending current metrics.

Does Beszel require HTTPS behind a reverse proxy?

Use HTTPS for the public Beszel origin and keep port 8090 on the internal route. Apply the Beszel setting correctly: route the hub through HTTPS and keep agent ports private. For Beszel, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Beszel upgrade be tested?

Restore current Beszel state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because hub and agent versions should be tested together because protocol changes can look like silent monitoring gaps. Keep the previous Beszel image until its data-migration and rollback boundary are understood.