Skip to main content

Edge Agent Installation

Prerequisites​

Before you install, make sure the following are in place on the machine that will run the agent.

RequirementDetails
Operating systemLinux (Ubuntu 20.04+, Debian 11+, or RHEL 8+). Windows via WSL2 works but is not recommended for production.
Python3.12 or later. Earlier versions are not supported.
Package manageruv , a fast Python package manager used to create the agent's isolated environment.
Outbound networkThe machine must be able to reach api.haltless.io on port 443 (HTTPS). No inbound ports are required.
Disk~200 MB for the agent and its dependencies, plus space for the local buffer. Budget generously if you expect long offline periods.
Memory64 MB is enough for most deployments.

You will also need two things from Haltless before the agent can send data:

  1. A registered machine for every device you want to monitor. The machine_identifier in your config must match the registered machine exactly (it is case-sensitive).
  2. An API key for your account. See API keys to create one. The key is shown only once, so store it securely.
tip

If a device is already reachable over the internet and you'd prefer not to run local software, you can skip the agent entirely and push readings straight to the ingestion API. See Direct ingestion.

Step 1 , Install Python and uv​

Install Python 3.12 (Debian/Ubuntu shown; use your distribution's package manager otherwise):

sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv
python3.12 --version   # expect: Python 3.12.x

Install uv and make sure it is on your PATH:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

Step 2 , Place the agent files​

Copy the edge-agent directory provided by Haltless to a stable location the service will own, for example /opt/haltless-agent. The directory contains the agent source, a pyproject.toml, and a config.yaml.example you will use as a starting point.

Step 3 , Install dependencies​

The core dependencies (needed for the CSV and JSON collectors) are always installed. The Modbus and OPC-UA collectors are optional extras , install only what you need.

cd /opt/haltless-agent

# Core only (CSV + JSON)
uv sync

# Add Modbus TCP support
uv sync --extra modbus

# Add OPC-UA support
uv sync --extra opcua

# Both
uv sync --extra modbus --extra opcua

uv sync creates an isolated virtual environment in .venv/ inside the project directory. No system-wide packages are changed.

Step 4 , Create the configuration file​

Copy the example and edit it for your environment:

cp config.yaml.example config.yaml

At minimum, set cloud_api_url, api_key, and one or more sources. The Configuration page documents every key, and Protocols covers the per-source settings.

Lock down the file so only the agent's user can read it (it contains your API key):

chmod 600 config.yaml

Step 5 , Run it once by hand​

Before installing it as a service, run the agent in the foreground to confirm it loads its config, authenticates, and starts collecting:

uv run python -m src.main

By default the agent reads config.yaml from the working directory. You can also pass a path explicitly:

uv run python -m src.main /opt/haltless-agent/config.yaml

On a healthy start you'll see the agent initialize each collector, confirm the connection to Haltless, report a heartbeat status of active, and begin sending batches. Press Ctrl+C to stop.

Step 6 , Run as a service (systemd)​

For production, run the agent under a process supervisor so it starts on boot and restarts on failure. A minimal systemd unit:

[Unit]
Description=Haltless Edge Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=haltless
Group=haltless
WorkingDirectory=/opt/haltless-agent
ExecStart=/opt/haltless-agent/.venv/bin/python -m src.main
Restart=always
RestartSec=10
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Running as a dedicated low-privilege user (haltless above) is recommended. Create it, hand it ownership of the directory, then enable the service:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin haltless
sudo chown -R haltless:haltless /opt/haltless-agent

sudo systemctl daemon-reload
sudo systemctl enable haltless-agent
sudo systemctl start haltless-agent
sudo systemctl status haltless-agent

Verify it's connected​

Check outbound reachability. From the agent host, confirm it can reach Haltless. A successful (2xx) response means the network path is open:

curl -sS -o /dev/null -w "%{http_code}\n" https://api.haltless.io/health

Watch the agent logs. Under systemd, logs go to the journal:

sudo journalctl -u haltless-agent -f

Look for the heartbeat line reporting status=active and lines confirming batches were sent. The heartbeat is the agent's own health check , when it reports active, the agent has reached Haltless and your subscription is in good standing.

Check the dashboard. Open your machine in the Haltless dashboard. New readings should appear within one collection interval of the agent starting.

Next steps​