Elchi Client Overview and Requirements
The Elchi Client (elchi-client) is the agent you install on each Linux edge host. It registers the host with your Elchi control plane over gRPC, then runs the Envoy listeners you deploy from the UI as systemd services on that host. It also carries out the commands the control plane sends it: deploys and undeploys, service start/stop/restart, Envoy version downloads, network and BGP (FRR) changes, and log shipping.
The installer also brings up the elchi-shield ext_proc WAF sidecar on the same host, unless you pass --no-shield.
How the client fits in
- You install the client with a name, the control plane's host and port, TLS on or off, and a token from Settings → Tokens in the Elchi UI. The token has the form
<uuid>--<project>, so the host joins the project the token was issued for. - The client starts as
elchi-client.service(/etc/elchi/bin/elchi-client start --config /etc/elchi/config.yaml, restarted automatically) and appears under Operations → Clients. - When you deploy a listener to the host, the client writes its bootstrap and runs Envoy as a systemd unit named
<listener>-<adminPort>.service. If the Envoy version that listener needs is not on the host yet, the client downloads it in the background; retry the deploy once the download finishes.
Day-two work (deploys, commands, logs, metrics) is covered in Operations.
Supported operating systems
| Requirement | Supported |
|---|---|
| Operating system | Ubuntu 24.04 LTS (minimum) |
| Architecture | linux/amd64. Published builds are amd64 only. |
| Privileges | root (the installer must run with sudo) |
| Init system | systemd |
| Network | Outbound access to the control plane's --host:--port, and to the public Elchi archive to download binaries |
The installer configures apt sources only on Ubuntu, and it refuses to run on an Elchi OS appliance, which configures its agent from the console instead. Additional distributions are on the roadmap: request a build.
Download
Every client release is mirrored in the public elchi-archive repository. A release contains the client binary, the installer script (elchi-install.sh) and the elchi-shield binary bundled with it, each with a .sha256 file. The newest release when this page was last updated is v2.1.6 (bundles elchi-shield v1.3.2):
This page is only as fresh as its last edit. The archive manifest lists the newest build first under elchi_client_releases, with a sha256 for every file, and the download portal shows the same list. You rarely need the files by hand: the get.sh bootstrap picks the newest release, checks the installer's sha256 against the manifest and runs it. Pin a release with --client-version=vX.Y.Z.
To verify a file you downloaded yourself:
curl -fsSLO https://github.com/CloudNativeWorks/elchi-archive/releases/download/elchi-client-v2.1.6/elchi-client-linux-amd64
curl -fsSLO https://github.com/CloudNativeWorks/elchi-archive/releases/download/elchi-client-v2.1.6/elchi-client-linux-amd64.sha256
sha256sum -c elchi-client-linux-amd64.sha256
What the installer sets up
Besides the client binary at /etc/elchi/bin/elchi-client and its config at /etc/elchi/config.yaml, the installer:
- creates the
elchiandenvoysystem users (no login shell), - writes kernel tuning (sysctl) for proxy workloads and a sudoers rule for the agent,
- configures rsyslog and filebeat for log shipping, and takes over the host's netplan file so the agent can manage interfaces and routes,
- installs and starts FRR for BGP when you pass
--enable-bgp, - installs elchi-shield as
elchi-shield.serviceunless you pass--no-shield.
Running elchi-install.sh --upgrade on an installed host replaces only the client binary, its unit, sudoers and tuning files, then restarts the agent. The config, identity, filebeat, rsyslog, netplan, FRR and shield stay as they are. Add --shield-version=vX.Y.Z (or latest) to upgrade the shield as well.
Two edge boxes can share VIPs active/passive as an HA pair. HA pairs run only on Elchi OS appliances, which ship the elchi-ha service, its firewall rules and kernel settings; a client installed with the installer on a general-purpose Linux host cannot join a pair. To run the client as an appliance instead of on your own Linux host, see Elchi OS.
Next steps
- Install the client with
get.shor the installer. - Configure it:
/etc/elchi/config.yamlreference. - The bundled Shield sidecar: audit and metrics sinks, policies.