homelab-blueprint/docker-compose-files/beszel-agent

Beszel Agent

Docker deployment for the Beszel monitoring agent. Run all commands from the repository root.

Persistent Data

Beszel Agent state is stored in the Docker-managed named volume beszel_agent_data.

Existing deployments that use appdata/beszel-agent must copy that data into the named volume before recreating the container.

Installation

1. Create .env if it does not exist:

   cp -n .env.sample .env
   

2. Add the agent credentials supplied by Beszel Hub to .env:

   TZ=Africa/Johannesburg
   BESZEL_AGENT_KEY=<public-key-from-hub>
   BESZEL_AGENT_TOKEN=<token-from-hub>
   BESZEL_AGENT_HUB_URL=https://beszel.example.com
   BESZEL_AGENT_LISTEN=45876
   BESZEL_SOCKET_PROXY_PORT=2375
   DOCKERLOGGING_MAXFILE=3
   DOCKERLOGGING_MAXSIZE=10m
   

3. Render the template:

   ./substitute_env.sh docker-compose-files/beszel-agent/template.yaml docker-compose.beszel-agent.yml .env
   

4. Start the socket proxy first, then validate and start the agent:

   docker compose -f docker-compose.beszel-proxy.yml up -d
   docker compose -f docker-compose.beszel-agent.yml config --quiet
   docker compose -f docker-compose.beszel-agent.yml up -d
   

5. Verify the container:

   docker compose -f docker-compose.beszel-agent.yml ps
   docker compose -f docker-compose.beszel-agent.yml logs --tail=100 beszel-agent
   

Apply Configuration Changes

./substitute_env.sh docker-compose-files/beszel-agent/template.yaml docker-compose.beszel-agent.yml .env
docker compose -f docker-compose.beszel-agent.yml up -d

Initial Setup

Add the system in Beszel Hub and use the generated key, token, and hub URL in .env.

Network Requirements

• Beszel Hub must reach the agent on BESZEL_AGENT_LISTEN.
• The agent reaches the socket proxy at 127.0.0.1:BESZEL_SOCKET_PROXY_PORT.

Troubleshooting

Confirm beszel-proxy is running and listening on localhost if Docker container metrics are missing.

Useful Commands

docker compose -f docker-compose.beszel-agent.yml restart beszel-agent

Backup

Back up the beszel_agent_data named volume.