How to Use Beszel: The Beginner's Guide (First Hub, First Agent, First Alert, and the Never-Expose-8090 Rule)

CodexFuse Team · 2026-10-31T08:42:50.507Z · 15 min read

Learn how to use Beszel: install the lightweight monitoring hub on Docker, add your first system and agent in minutes, read the dashboard, and set your first alert — without exposing port 8090.

If you own more than one server, you already know the pain: one VPS here, a homelab box there, maybe a Raspberry Pi in the corner, and no single place to see how any of them are doing. Learning how to use Beszel fixes that with the least effort of any monitoring setup you will try. Beszel is a lightweight, self-hosted server monitoring platform built around a hub-and-agent model: one hub holds the dashboard, and a tiny agent on each machine reports CPU, memory, disk, network, temperatures, and per-container Docker stats back to it. This beginner's guide walks the whole arc in one sitting: installing the hub on Docker, adding your first system, installing the agent with the one-liner, reading the dashboard, setting your first alert, and putting it all behind HTTPS without exposing the dashboard to the whole internet. If you have never deployed a container before, skim the Docker beginner guide first — the hub runs happiest as a container.

What Is Beszel, in One Paragraph?

Beszel is an open-source server monitoring tool by Henry Doss (MIT license, built on PocketBase) that splits monitoring into two pieces: a hub, a web application where you view dashboards, configure alerts, and manage users; and a tiny agent you install on every system you want to watch, which reports metrics to the hub over an encrypted channel. There is no Prometheus scrape config to write, no YAML dashboards to build, and no per-host pricing — the agent uses roughly 10MB of RAM, versus the 200–500MB a Netdata agent needs, according to an independent 2026 comparison test by developer Vikas Yadav on dev.to. The full first-use arc is five steps:

1. Start the hub as a Docker container on port 8090.
2. Create your admin account on first load.
3. Click Add System and let the hub generate a unique key and token for the new machine.
4. Run the hub-generated agent install command on that machine (agent listens on port 45876).
5. Watch the tile turn green, then set your first alert.

Is Beszel the Right Monitor for You?

Beszel is the right choice if you run between two and fifty machines — homelab servers, VPSs, a NAS, a media box — and you want one clean dashboard instead of SSH-ing into boxes one by one to run htop. It is also the right choice if your monitoring server itself is small: a 168-day-old dev.to test installed the hub (12MB) plus agent (8MB) on a $3 VPS and had a working setup in about four minutes, which is a footprint no full metrics stack can touch. The honest limits: Beszel is resource monitoring, not service uptime checking — it measures from inside the machine, so if you also want to know that a website is reachable from the outside world, pair it with the Uptime Kuma beginner guide (Kuma pings services from outside; Beszel measures from inside). And if you need deep per-second metrics, custom dashboards, and a query language, that is Grafana-and-Prometheus territory — Beszel deliberately trades that depth for a setup you finish before your coffee cools.

How Do You Install the Beszel Hub on Docker?

The hub is the web app, and the official quick start on beszel.dev gives you two ways to run it: a single binary or Docker. Docker is the beginner-friendly path, and it is the one the independent guides converge on. Pick any always-on machine for the hub — if you do not have one yet, a cheap VPS works; the what is VPS hosting explainer covers how to pick and size one. Then run:

mkdir beszel && cd beszel
docker run -d \
  --name beszel \
  --restart unless-stopped \
  -p 127.0.0.1:8090:8090 \
  -v ./beszel_data:/beszel_data \
  henrygd/beszel:latest

Two details in that command matter. Binding port 8090 to 127.0.0.1 only — the never-expose-8090 rule — keeps the dashboard off the public internet until you deliberately put HTTPS in front of it; the RamNode VPS deployment guide demonstrates exactly this localhost binding with nginx in front. And the volume (./beszel_data) is where Beszel stores everything, since the hub is built on PocketBase — keep that folder backed up and you can move the whole hub to another server by copying it. Now open http://<your-server-ip>:8090 in a browser from a machine that can reach it. The first request prompts you to create the admin account — do it now, because the hub will not show you the dashboard until an admin exists, per the official getting-started guide.

How Do You Add Your First System in the Hub?

Log in and click Add System in the top right. Fill in a name (something descriptive like homelab-nas), the host or IP of the machine you are about to monitor, and the agent port 45876. When you save, the hub generates a unique public key and a unique token for this one system — every system gets its own pair, so a compromised key only ever affects one machine. The hub then shows you the exact agent install command with your key and token already filled in. Copy that command verbatim — the RamNode guide's troubleshooting section calls out that even a single extra space in the token breaks authentication. Since version 0.12.0 there is also a universal-token option under Settings → Tokens that lets an agent connect without pre-configuring the system first, but for your first setup the per-system Add System flow is clearer, because it teaches you where each credential lives.

How Do You Install the Beszel Agent with the One-Liner?

On the machine you want to monitor, run the install script you copied from the hub — or, if you prefer to see the shape of it first, the generic form is:

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh
chmod +x /tmp/install-agent.sh
/tmp/install-agent.sh -p 45876 -k "<your-public-key>"

Run it with root privileges: the script creates a dedicated beszel user (the agent process itself does not run as root), registers beszel-agent.service as a systemd service, and enables it so the agent survives reboots — the 2026 dev.to Proxmox guide verifies the service comes back up after a restart with systemctl is-enabled beszel-agent. Passing -p and -k skips the interactive prompts, which is what the bitnesia install reference (published the same week as this article) documents. Open firewall port 45876 between the agent and the hub, then go back to the dashboard: the new system's tile turns green within seconds and starts drawing CPU, memory, disk, and network graphs.

Hub vs Agent: Which Piece Does What?

Beginners trip on the two names, so here is the clean split. The Beszel hub is the brain: the web UI, the historical data store, the alert engine, user management, OAuth/OIDC logins, and automatic backups (the official README documents backups to disk or S3-compatible storage). It listens on port 8090 and only needs to be reachable by you and by your agents. The Beszel agent is the senses: a single small Go binary on each monitored machine that reads system metrics and pushes them to the hub. It listens on port 45876 for the hub's connection, uses about 10MB of RAM, and — this is the architectural point the ricardogil.com 2026 comparison stresses — needs no config files, no YAML, and no scrape targets. You can even run both on the same machine while learning, but remember: a hub that lives on the only server it monitors cannot notify you when that server dies. Put the hub somewhere that outlives any single box it watches.

How Do You Install the Beszel Agent with Docker Instead?

If the machine you want to monitor already runs Docker, the container agent is often tidier than the binary. The hub's Add System dialog has a Copy docker compose button that generates the exact agent compose file with your key and token baked in — the markpitblado.me setup guide (written against Beszel v0.9.1) walks this flow. The shape of it is:

services:
  beszel-agent:
    image: "henrygd/beszel-agent"
    container_name: "beszel-agent"
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      KEY: "<your-public-key>"
      TOKEN: "<your-token>"

The Docker socket mount is what gives the agent per-container CPU, memory, and network stats — without it you get host metrics but no container breakdown. Then docker compose up -d, make sure port 45876 is open to the hub, and the tile goes green. One caution from the official docs: on Docker Desktop setups the agent compose looks different (it uses a Unix socket path as the host), so if your first machine is a laptop rather than a Linux server, follow the official quick-start's Docker Desktop section instead of the generic one.

What Does the Beszel Dashboard Show You?

The main dashboard is a grid of tiles, one per system, each with live CPU, memory, disk, and network sparklines; click a tile for the full system page with history graphs. The supported-metrics list in the official GitHub README is generous for a tool this small: host and Docker/Podman container CPU, memory (including swap and ZFS ARC), disk usage and I/O across partitions, network throughput, load average, temperature and fan sensors, GPU usage and power draw for Nvidia, AMD, and Intel cards, battery charge, per-container status and metrics, S.M.A.R.T. disk health (including drive-failure notifications), and ZFS pool capacity, health, I/O, and scrub status. The Docker container view is the feature homelabbers praise most — each container gets its own colored line on the graphs, so you can see exactly which container is eating your RAM without opening a terminal. History goes back as far as you configure it to keep, which makes the dashboard double as a "what changed last Tuesday" debugging tool.

How Do You Set Up Your First Alert in Beszel?

Alerts are configured per system in the hub, and the flow the official README documents is: thresholds first, notification channel second. But the channel must exist before the alert can fire — this is the step beginners skip. Open the notification settings and configure at least one destination first: the 2026 dev.to comparison test lists email, Discord, ntfy, Pushover, and Telegram, and the ricardogil.com guide adds Slack and webhooks. For email you will need an SMTP server configured (markpitblado.me uses Mailgun as the example) — the hub cannot send mail out of thin air. Then create the alert: a classic first alert is CPU above 80% for 5 minutes, plus disk above 90% for the partition that holds your data. Keep the first alert simple and let it fire once on purpose (a quick stress test works) so you trust the pipeline before you need it at 3 a.m. The alert history in the hub shows you every firing, which makes tuning thresholds a data-driven job instead of guesswork.

How Do You Put Beszel Behind HTTPS Safely?

Remember the never-expose-8090 rule from the install step: the hub has password and OAuth logins, but its admin surface should never sit naked on the public internet. The pattern every independent guide converges on is a reverse proxy with automatic HTTPS in front of the localhost-bound hub. If you like Caddy, the setup is a three-line Caddyfile — the Caddy beginner guide covers the full install, and the markpitblado.me Beszel guide shows the exact proxy block:

monitor.example.com {
    reverse_proxy 127.0.0.1:8090
}

Caddy fetches and renews the certificate automatically. Prefer nginx? The RamNode deployment guide pairs certbot with a proxy pass to the same localhost port — same architecture, more typing. Either way, the firewall story stays the same: publicly expose only ports 80 and 443, keep 8090 on localhost, and open 45876 only between your hub and your agents. One more piece of hygiene from the README: Beszel supports OAuth/OIDC with password auth optionally disabled, so once HTTPS works, consider moving your own login to a provider you already trust.

Beszel vs Netdata: Which One Should You Pick?

This is the comparison the monitoring corner of the internet keeps re-litigating, and the answer depends on what you value. The numbers, all from the 2026 guides fetched for this article: the Beszel agent uses about 10MB of RAM; a Netdata agent uses 200–500MB; and the full Grafana + Prometheus + node_exporter + cAdvisor stack lands around 400–700MB combined. Beszel's latest release at write time is v0.21.1 (October 22, 2026), and the project has gathered roughly 26,700 GitHub stars since its July 2024 launch.

The honest read, matching the ricardogil.com verdict: if you want the lightest thing that still gives you history, container stats, and alerts, Beszel wins. If you need per-second granularity or you are building SLI dashboards for a team, you will outgrow it — and that is fine, because migrating later costs you an afternoon, not a re-architecture.

What Mistakes Do Most Beszel Beginners Make?

Every setup story in the research for this guide trips on at least one of these. Learn them here instead of at midnight:

Sources

• Official Beszel quick-start guide (beszel.dev/guide/getting-started) — hub install, first admin account, Add System flow, universal tokens since 0.12.0, agent Docker setup.
• GitHub henrygd/beszel README (fetched 2026-10-31) — MIT license, PocketBase hub, full supported-metrics list, S.M.A.R.T./ZFS/GPU coverage, OAuth/OIDC, S3 backups; releases API: v0.21.1 (2026-10-22), ~26,700 stars.
• Vikas Yadav, "I Tested 7 Self-Hosted Monitoring Tools on a $3 VPS in 2026" (dev.to, ~168d) — hub 12MB + agent 8MB, ~4-minute setup, alert destinations (email, Discord, ntfy, Pushover, Telegram).
• Vikas Yadav, "How to Monitor Proxmox with Beszel in 5 Minutes (2026)" (dev.to, ~161d) — ~10MB agent vs Netdata 200–500MB, curl -sL https://get.beszel.dev | bash, systemd reboot-proofing.
• Ricardo Gil, "Beszel vs Grafana + Prometheus on Proxmox 2026" (ricardogil.com, ~25d) — ~10MB agent, 400–700MB full-stack comparison, community Proxmox LXC script, alert channels incl. Slack/webhook.
• RamNode, "Deploy Beszel on a VPS — Lightweight Server Monitoring" (ramnode.com) — ports 8090/45876, localhost binding, nginx + HTTPS, per-system key/token, PocketBase backups, token-match troubleshooting.
• Mark Pitblado, "Simple server monitoring with Beszel" (markpitblado.me) — Caddy reverse proxy block, Add System "Copy docker compose" flow, SMTP via Mailgun.
• Bitnesia, "How to Install Beszel for Server and Docker Monitoring" (bitnesia.com, 8h) — binary agent install script, root requirement, dedicated beszel user, -k/-p flags.
• Cloudron docs, "Beszel agent on Cloudron" (docs.cloudron.io) — /tmp/install-agent.sh -p 45876 -k, systemd service path, -u uninstall.
• XDA Developers, "This Docker utility is a must have for every self-hosted stack" (~367d) — no ports exposed to the internet, optional HTTPS via reverse proxy.

Beszel Tutorial FAQ

How much RAM does Beszel actually use?

The agent uses about 10MB of RAM per monitored machine, and the hub adds roughly 12MB, per the 2026 dev.to comparison test that installed the full setup on a $3 VPS. For context, a Netdata agent needs 200–500MB and a full Grafana/Prometheus stack needs 400–700MB combined. That is why Beszel is the default recommendation for Raspberry Pis and tiny VPSs.

Is Beszel free for commercial use?

Yes. Beszel is MIT-licensed open source with no paid tier, no per-host pricing, and no telemetry, per the official GitHub README. You pay only for the server you run the hub on — which can be a $3–$4/month VPS or hardware you already own.

Does Beszel require Docker?

No. The hub runs as a single binary or a Docker container, and the agent installs as a native binary via the official install script or as a Docker container. The binary agent path (created beszel user + systemd service) is the right pick for machines where you would rather not install Docker at all.

Can Beszel monitor my Docker containers, not just the host?

Yes — per-container CPU, memory, and network history is one of Beszel's headline features. The agent reads the Docker socket (mount it read-only in the agent compose file), and each container shows up as its own colored line on the graphs plus its own status tile.

Why shouldn't I expose Beszel's port 8090 directly to the internet?

Port 8090 serves the hub's web UI and admin surface. Every independent deployment guide puts it behind a reverse proxy with HTTPS (Caddy or nginx) and binds it to localhost, exposing only ports 80/443 publicly. The hub holds credentials and metrics for your entire fleet — treat it like any other admin panel and keep it off the open internet.