Getting Started

For background information, see the What is Beszel? page.

1. Start the hub

The hub can be run with a single binary file or with Docker / Podman.

• Binary
• Docker or Podman

Click to view complete docker-compose.yml config including local agent

IMPORTANT

This configuration should work out of the box, but you must follow these steps when adding the system in the web UI:

1. Update the KEY value with your public key, then run docker compose up -d again to restart the agent.

2. Use host.docker.internal as the Host / IP. Do not use localhost or 127.0.0.1.

docker-compose.yml

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    extra_hosts:
      - host.docker.internal:host-gateway
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PORT: 45876
      # Do not remove quotes around the key
      KEY: 'UPDATE WITH YOUR PUBLIC KEY (copy from "Add system" dialog)'

Click to view instructions for running docker compose

NOTE

If you prefer to set up containers in a different way, please feel free to do so.

1. Install Docker and Docker Compose if you haven't already.

2. Copy the docker-compose.yml content.

3. Create a directory somewhere to store the docker-compose.yml file.

mkdir beszel
cd beszel

4. Create a docker-compose.yml file, paste in the content, and save it.

nano

nano docker-compose.yml

vim

vim docker-compose.yml

emacs

emacs docker-compose.yml

vscode

code docker-compose.yml

5. Start the service.

docker compose up -d

2. Create an admin user

After starting the hub, navigate to http://localhost:8090 or your chosen address.

You will be prompted to create an account:

3. Configure your first system

Click the Add System button in the top right corner to open the system creation dialog. We're using localhost in this example, but you may use a remote agent instead.

Do not click the Add System button inside the dialog until you've started up the agent.

4. Start the agent

Docker instructions

NOTE

If you prefer to set up containers in a different way, please feel free to do so.

1. Copy the docker-compose.yml content from the Add System dialog.

2. Create a directory somewhere to store the agent's docker-compose.yml file.

mkdir beszel-agent
cd beszel-agent

3. Create a docker-compose.yml file and paste in the content provided in the Add System dialog.

nano

nano docker-compose.yml

vim

vim docker-compose.yml

emacs

emacs docker-compose.yml

vscode

code docker-compose.yml

4. Start the agent.

docker compose up -d

Binary instructions

The install script is for Linux only

If you use a different OS, please manually download and run the correct binary for your system. See the Agent Installation page or the Compiling page for more information.

1. Copy the binary install command from the Add System dialog.

2. Open a terminal and run the command.

This will download the correct binary, create a user called beszel, and start the agent. It also creates a service to keep it running after reboot, and optionally enables automatic daily updates.

5. Finish adding the system

Now that the agent is running, click the Add System button in the dialog.

You will see the new system in table. If it flips to green, you're good to go.

If it changes to red, check the Common Issues page.