Edge Agent Configuration

The edge agent is configured via a TOML file at /etc/haltless/agent.toml (or a path set by the HALTLESS_CONFIG environment variable).

Configuration file

# /etc/haltless/agent.toml

[agent]
# Your API key (required)
api_key = "hk_your_api_key_here"

# Haltless API base URL
api_url = "https://api.haltless.io"

# How often to push data to the cloud (seconds)
push_interval = 30

# Maximum readings per batch (max: 1000)
batch_size = 100

# Local buffer directory for offline resilience
buffer_dir = "/var/lib/haltless/buffer"

# Maximum buffer size in MB (oldest data is dropped when exceeded)
max_buffer_mb = 500

# Heartbeat interval (seconds)
heartbeat_interval = 300

# Log level: debug, info, warn, error
log_level = "info"

# --- Data sources ---
# Define one or more [[source]] blocks

[[source]]
name = "cnc-mill-1"
machine_identifier = "CNC-001"
protocol = "opcua"

[source.opcua]
endpoint = "opc.tcp://192.168.1.100:4840"
security_mode = "None"          # None, Sign, SignAndEncrypt
security_policy = ""             # Basic256Sha256, etc.
username = ""                    # Optional: OPC-UA auth
password = ""                    # Optional: OPC-UA auth

[[source.opcua.nodes]]
node_id = "ns=2;i=1001"
metric_name = "temperature"
unit = "celsius"

[[source.opcua.nodes]]
node_id = "ns=2;i=1002"
metric_name = "vibration"
unit = "mm/s"

[[source.opcua.nodes]]
node_id = "ns=2;i=1003"
metric_name = "pressure"
unit = "psi"

[[source]]
name = "conveyor-motor"
machine_identifier = "CONV-001"
protocol = "modbus"

[source.modbus]
host = "192.168.1.101"
port = 502
unit_id = 1
poll_interval = 10

[[source.modbus.registers]]
address = 100
count = 1
register_type = "holding"       # holding, input
metric_name = "temperature"
unit = "celsius"
scale = 0.1                     # Multiply raw value
offset = 0.0                    # Add after scaling

[[source.modbus.registers]]
address = 102
count = 1
register_type = "holding"
metric_name = "speed"
unit = "rpm"
scale = 1.0
offset = 0.0

Environment variables

All settings can be overridden with environment variables (useful for Docker):

Variable	Description	Default
HALTLESS_API_KEY	API key for authentication	(required)
HALTLESS_API_URL	API base URL	https://api.haltless.io
HALTLESS_POLL_INTERVAL	Data collection interval (s)	30
HALTLESS_PUSH_INTERVAL	Cloud push interval (s)	30
HALTLESS_BATCH_SIZE	Max readings per batch	100
HALTLESS_BUFFER_DIR	Offline buffer directory	/var/lib/haltless/buffer
HALTLESS_MAX_BUFFER_MB	Max buffer size (MB)	500
HALTLESS_LOG_LEVEL	Log level	info
HALTLESS_CONFIG	Config file path	/etc/haltless/agent.toml
HTTPS_PROXY	HTTP proxy URL	(none)

Offline buffering

When the agent cannot reach the Haltless cloud, readings are buffered locally in buffer_dir. Once connectivity is restored, buffered data is pushed automatically in chronological order.

The buffer uses a write-ahead log to ensure no data loss during process restarts. When max_buffer_mb is exceeded, the oldest readings are dropped.

Timestamp handling

All timestamps must be in UTC. The agent validates that timestamps are:

• Not more than 5 minutes in the future (clock skew tolerance)
• Not more than 3,650 days in the past (within Enterprise retention window)

If your devices use local time, configure the agent to convert:

[agent]
timezone = "Europe/Berlin"  # Convert local timestamps to UTC

Reading validation

Each sensor reading must have:

Field	Type	Required	Constraints
machine_identifier	string	Yes	Must match a registered machine
timestamp	ISO 8601	Yes	UTC, within valid range
metric_name	string	Yes	Max 255 characters
value	float	Yes	Must be finite (no NaN/Inf)
unit	string	Yes	Descriptive unit label
raw_tag	string	No	Original tag name from source

Invalid readings are rejected individually , valid readings in the same batch are still accepted.

Multiple sources

You can collect from as many devices as needed. Each [[source]] block maps to one machine:

[[source]]
name = "pump-station-a"
machine_identifier = "PUMP-A1"
protocol = "modbus"
# ...

[[source]]
name = "pump-station-b"
machine_identifier = "PUMP-B1"
protocol = "modbus"
# ...

[[source]]
name = "scada-server"
machine_identifier = "SCADA-001"
protocol = "opcua"
# ...

Security best practices

1. Rotate API keys periodically , create a new key, update the agent, then revoke the old one
2. Use least-privilege keys , API keys are scoped to the tenant, not to specific machines
3. Encrypt the config file , protect the api_key and any device passwords
4. Use TLS for OPC-UA , set security_mode = "SignAndEncrypt" when supported
5. Restrict network access , the agent only needs outbound HTTPS to api.haltless.io

Next steps

• Protocols , detailed protocol-specific configuration
• Troubleshooting , common issues and solutions