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

Create .env if it does not exist:
```
cp -n .env.sample .env
```

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

Render the template:

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

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

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.

2.1 KiB Raw Blame History