[Bug]: Documentation is missing key details about keys.

[drthornt]

Component

Hub

Description

I've read the docs.

https://beszel.dev/guide/getting-started

1. Update the KEY and TOKEN environment variables with your public key and token, then restart the agent:

After hunting around a bit I've read the security document:

https://beszel.dev/guide/security

The SSH connection is initiated by the hub and connects to the agent's SSH server. ... When the hub is started for the first time, it generates an ED25519 key.

I think it would be good if it was more clear what key is required for agent start. I think it should be clear in the getting started guide what's going on with the keys.

For example the getting started guide might read:

1. In the agent config update the KEY environment variables with the public key generated by the hub when it first starts, which can be found here INSERT LOCATION OF PUBLIC KEY . Then restart the agent.

2. Optionally add the TOKEN environment variables with a token INSERT HOW TO GET A TOKEN . Then restart the agent.

For more on how secure communication works between agent and hub, see here: INSERT LINK TO SECURITY DOCUMENT

I still don't know where the public key is.

Expected Behavior

In the getting started guide it should be clear the steps needed to get "up and running". It says "It should work "out of the box" , but that is not my experience.

I'm still wondering about if I need a token and how to make it.

And I don't know where the public key is.

Do I need to craft one from the private key? I was able to figure out where the private key is , but not because it was mentioned in the documentation.

Steps to Reproduce

1st try:

1. created docker compose file.
2. unable to fill in key field, left it blank.
3. attempted run docker compose up and got an error.

2nd try

1. examined files created by docker compose from 1st try.
2. found private key, could not find public key.
3. created public key from private using ssh CLI tools.
4. pasted public key into env var config.
5. ran docker compose up , success

Category

Setup , Configuration, Documentation

Affected Metrics

N/A

OS / Architecture

linux/amd64

Beszel version

0.16.1

Installation method

Docker

Configuration

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - ./beszel_socket:/beszel_socket
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: /beszel_socket/beszel.sock
      HUB_URL: http://localhost:8090
      KEY: "??"

Hub Logs

Agent Logs

$ /usr/bin/docker compose -f /home/david/beszel/docker-compose.yml up
[+] Running 1/1
 ✔ Container beszel-agent  Recreated                                                                                                                                                                                               0.0s
Attaching to beszel, beszel-agent
beszel-agent  | 2025/11/16 18:43:28 Failed to load public keys:no key provided: must set -key flag, KEY env var, or KEY_FILE env var. Use 'beszel-agent help' for usage
beszel-agent exited with code 1 (restarting)
beszel        | 2025/11/16 18:43:29 Server started at http://0.0.0.0:8090
beszel        | ├─ REST API:  http://0.0.0.0:8090/api/
beszel        | └─ Dashboard: http://0.0.0.0:8090/_/
beszel-agent  | 2025/11/16 18:43:29 Failed to load public keys:no key provided: must set -key flag, KEY env var, or KEY_FILE env var. Use 'beszel-agent help' for usage
beszel-agent exited with code 1 (restarting)

[supermarkert]

FYI, I opened a discussion about this, and the Dev responded: https://github.com/henrygd/beszel/discussions/1206

[dazzag24]

Glad to find this issue. I've been looking to install beszel and hit exactly the same roadblock.

[henrygd]

You can find the public key and token in the 'Add System' dialog when adding your first system. It's also included if you copy any of the preset configs / commands.

I'll take a second look at the docs when I have time.