Beszel Hub

Monitor your servers through connected Beszel agents.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Beszel Hub

Editable Compose files in your own directory.

Set the initial administrator email and password before first start, or create the first account in Beszel.
Add agents using keys from the hub; do not expose agent listeners to arbitrary networks.

selfhost app --directory ./beszel init beszel

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./beszel start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd beszel
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Beszel Hub, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "beszel",
  "name": "Beszel Hub",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Actions for a linked container

Check hub health

Check whether the Beszel hub is responding.

selfhost existing action EXISTING_ID health

Before configuring integrations

Native settings include heartbeat receivers, MFA policy and container-detail access.
Configure OAuth providers in PocketBase administration before disabling password login.
Email OTP requires working SMTP. Selfhost does not yet register a PocketBase provider automatically.

Beszel Hub integrations

Compose service: beszel. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (10)

Public URL public-url: string
Initial administrator email first-user: Used only when the hub has no users. string
Initial administrator password first-password: Used only when creating the first user. Changing this does not reset existing passwords. secret
Create accounts from OIDC user-creation: Configure the provider in the PocketBase admin UI first. stringChoices: true, false
Disable password login password-auth: Enable only after verifying another login method. stringChoices: true, false
Email one-time passwords mfa: Requires working SMTP. stringChoices: false, true, superusers
Allow container details container-details: Allows users to inspect container metadata and logs. stringChoices: true, false
External heartbeat receiver heartbeat-url: Optional status receiver; includes system health details. Treat token-bearing URLs as credentials. secret
Heartbeat HTTP method heartbeat-method: stringChoices: GET, POST, HEAD
Heartbeat interval heartbeat-interval: Seconds between notifications. string

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./beszel config beszel
selfhost app --directory ./beszel plan beszel changes.json
selfhost app --directory ./beszel apply beszel changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Check hub health

Check whether the Beszel hub is responding.

selfhost app --directory ./beszel action beszel health

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

beszel: henrygd/beszel:0.20.0

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Beszel Hub documentation