Instalação Agente Beszel Link: https://www.beszel.dev/guide/agent-installation Agent Installation The agent can be installed via Docker / Podman, single binary file, Homebrew package, WinGet / Scoop package, or Home Assistant add-on. TIP Check the  Getting Started  guide if you're setting up Beszel for the first time. Required variables KEY : The public key shown when adding a system in the Hub. TOKEN : Used to authenticate the agent (see  /settings/tokens ). HUB_URL : Used for outgoing WebSocket connection (not required for SSH connection). More information is available on the  Security  and  Environment Variables  pages. Using the Hub The  docker-compose.yml  or binary install command is provided for copy/paste in the hub's web UI. Click the  Add System  button to manually configure the agent, or use a universal token ( /settings/tokens ) to connect the agent without needing to set it up ahead of time. Docker or Podman TIP Preconfigured  docker-compose.yml  content can be copied the hub's web UI when adding a new system, so in most cases you do not need to set this up manually. docker-compose.yml docker run podman run services: beszel-agent: image: henrygd/beszel-agent container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - ./beszel_agent_data:/var/lib/beszel-agent - /var/run/docker.sock:/var/run/docker.sock:ro # monitor other disks / partitions by mounting a folder in /extra-filesystems # - /mnt/disk1/.beszel:/extra-filesystems/disk1:ro environment: LISTEN: 45876 KEY: "" HUB_URL: "" TOKEN: "" Why host network mode? The agent must use host network mode to access the host's network interface stats. This automatically exposes the port, so change the port using an environment variable if needed. If you don't need host network stats, you can remove that line from the compose file and map the port manually. Connecting to a local agent When connecting to a local agent,  localhost  will not work because the containers are in different networks. The recommended way to connect them is to use a unix socket. IMPORTANT This configuration should work out of the box, but you must follow these steps when adding the system in the web UI: Update the  KEY  and  TOKEN  environment variables with your public key and token, then restart the agent: docker compose up -d Use the unix socket path as the  Host / IP  in the web UI: /beszel_socket/beszel.sock docker-compose.yml services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped environment: APP_URL: http://localhost:8090 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 TOKEN: KEY: "" NOTE If you prefer to set up containers in a different way, please feel free to do so. Install  Docker  and  Docker Compose  if you haven't already. Copy the  docker-compose.yml  content. Create a directory somewhere to store the  docker-compose.yml  file. mkdir beszel cd beszel Create a  docker-compose.yml  file, paste in the content, and save it. nano vim emacs vscode nano docker-compose.yml Change the  APP_URL  environment variable to the URL you’ll use to access the Hub (for example, a domain name or public IP including port if needed) Start the service. docker compose up -d Binary Beszel is written in pure Go and can be easily compiled (or cross-compiled) if a prebuilt binary isn't available. 1. Install script (Linux, FreeBSD) Root privileges required The script needs root privileges to create a  beszel  user and set up a service to keep the agent running after reboot. The agent process itself does not run as root. The script installs the latest binary and optionally enables automatic daily updates. -k : Public key (enclose in quotes; interactive if not provided) -p : Port or address (default: 45876) -t : Token (optional for backwards compatibility) -url : Hub URL (optional for backwards compatibility) -v : Version (default: latest) -u : Uninstall --auto-update : Enable or disable automatic daily updates (interactive if not provided) --china-mirrors : Use GitHub mirror to resolve network issues in mainland China -h : Show help curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh 2. Manual download and start (Linux, FreeBSD, others) Download the binary Download the latest binary from  releases  that matches your server's OS / architecture. curl -sL "https://github.com/henrygd/beszel/releases/latest/download/beszel-agent_$(uname -s)_$(uname -m | sed -e 's/x86_64/amd64/' -e 's/armv6l/arm/' -e 's/armv7l/arm/' -e 's/aarch64/arm64/').tar.gz" | tar -xz beszel-agent Start the agent Use  -h  to see all available options. ./beszel-agent -key "" -token "" -url "" Update the agent ./beszel-agent update Create a service (optional) If your system uses systemd, you can create a service to keep the agent running after reboot. Create a service file in  /etc/systemd/system/beszel-agent.service . Replace the placeholder values (e.g.,  ,  ) with your actual configuration. You can also use  KEY_FILE  and  TOKEN_FILE  to load secrets from protected files (see  issue #1627 ). [Unit] Description=Beszel Agent Service After=network-online.target Wants=network-online.target [Service] ExecStart=/beszel-agent Environment="LISTEN=45876" Environment="KEY=" Environment="TOKEN=" Environment="HUB_URL=" # Environment="EXTRA_FILESYSTEMS=sdb" Restart=on-failure RestartSec=5 StateDirectory=beszel-agent # Security/sandboxing settings KeyringMode=private LockPersonality=yes NoNewPrivileges=yes ProtectClock=yes ProtectHome=read-only ProtectHostname=yes ProtectKernelLogs=yes ProtectSystem=strict RemoveIPC=yes RestrictSUIDSGID=true [Install] WantedBy=multi-user.target Enable and start the service. sudo systemctl daemon-reload sudo systemctl enable beszel-agent.service sudo systemctl start beszel-agent.service 3. Manual compile and start (any platform) Compile See  Compiling  for information on how to compile the agent yourself. Start the agent Use  -h  to see all available options. ./beszel-agent -key "" -token "" -url "" Update the agent ./beszel-agent update Create a service (optional) If your system uses systemd, you can create a service to keep the agent running after reboot. Create a service file in  /etc/systemd/system/beszel-agent.service . Replace the placeholder values (e.g.,  ,  ) with your actual configuration. You can also use  KEY_FILE  and  TOKEN_FILE  to load secrets from protected files (see  issue #1627 ). [Unit] Description=Beszel Agent Service After=network-online.target Wants=network-online.target [Service] ExecStart=/beszel-agent Environment="LISTEN=45876" Environment="KEY=" Environment="TOKEN=" Environment="HUB_URL=" # Environment="EXTRA_FILESYSTEMS=sdb" Restart=on-failure RestartSec=5 StateDirectory=beszel-agent # Security/sandboxing settings KeyringMode=private LockPersonality=yes NoNewPrivileges=yes ProtectClock=yes ProtectHome=read-only ProtectHostname=yes ProtectKernelLogs=yes ProtectSystem=strict RemoveIPC=yes RestrictSUIDSGID=true [Install] WantedBy=multi-user.target Enable and start the service. sudo systemctl daemon-reload sudo systemctl enable beszel-agent.service sudo systemctl start beszel-agent.service Homebrew (macOS, Linux) Environment variables can be changed in  ~/.config/beszel/beszel-agent.env . Logs are written to  ~/.cache/beszel/beszel-agent.log . Homebrew install script -k : SSH key (interactive if not provided) -p : Port (default: 45876) -t : Token (optional for backwards compatibility) -url : Hub URL (optional for backwards compatibility) -h : Show help curl -sL https://get.beszel.dev/brew -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh Homebrew manual install mkdir -p ~/.config/beszel ~/.cache/beszel echo 'KEY="ssh-ed25519 AAAA..."' > ~/.config/beszel/beszel-agent.env brew tap henrygd/beszel brew install beszel-agent brew services start beszel-agent WinGet / Scoop (Windows) The agent is available as a package in  WinGet  and  Scoop . The script below uses Scoop if you have it installed, otherwise it uses WinGet if that's installed. If neither are available, it will install both Scoop and the agent. It also installs  NSSM  and creates a service to keep the agent running after reboot. -Key : SSH key (interactive if not provided) -Port : Port (default: 45876) -Url : Hub URL -Token : Token -InstallMethod : "Auto", "WinGet", or "Scoop" -ConfigureFirewall : Add an incoming firewall rule. & iwr -useb https://get.beszel.dev -OutFile "$env:TEMP\install-agent.ps1"; & Powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-agent.ps1" The script's source code is available  on GitHub . There are also community-developed GUI applications to install and manage the agent: vmhomelab/beszel-agent-installer  which uses  Chocolatey . MiranoVerhoef/BeszelAgentManager  which uses WinGet. Edit configuration Edit the service in NSSM by running the command below. Scroll to the right in the GUI to find environment variables. nssm edit beszel-agent You can also change options directly from the command line: nssm set beszel-agent AppEnvironmentExtra "+EXTRA_FILESYSTEMS=D:,E:" Restart the service when finished:  nssm restart beszel-agent Logs Logs are saved in  C:\ProgramData\beszel-agent\logs . Upgrade Scoop nssm stop beszel-agent; & scoop update beszel-agent; & nssm start beszel-agent WinGet See  Upgrading with WinGet . Uninstall Scoop nssm stop beszel-agent nssm remove beszel-agent confirm scoop uninstall beszel-agent WinGet nssm stop beszel-agent nssm remove beszel-agent confirm winget uninstall henrygd.beszel-agent Home Assistant See the  Home Assistant Agent page  for instructions on setting up the agent as a Home Assistant add-on. Edit this page on GitHub Last updated:  31/03/2026, 20:10 Pager Previous page Hub Installation Next page Advanced Deployment