losant/edge-agent repository overview

⁠Losant Gateway Edge Agent

The Losant Gateway Edge Agent is a service that’s installed on every Losant Edge Compute device to manage the deployment and execution of edge workflows.

⁠Supported Tags

• 2.5.0, 2.5, 2, latest

• 2.5.0-amd64, 2.5-amd64, 2-amd64, latest-amd64

• 2.5.0-arm64, 2.5-arm64, 2-arm64, latest-arm64

• 2.5.0-alpine, 2.5-alpine, 2-alpine, latest-alpine

• 2.5.0-alpine-amd64, 2.5-alpine-amd64, 2-alpine-amd64, latest-alpine-amd64

• 2.5.0-alpine-arm64, 2.5-alpine-arm64, 2-alpine-arm64, latest-alpine-arm64

⁠Quick reference

• Where to get help:
  Losant Gateway Edge Agent Installation Tutorial⁠
  Losant Gateway Edge Agent Usage Tutorial⁠
  Losant Documentation⁠
  Losant Forums⁠

• Maintained by:
  Losant⁠

• Supported architectures:
  amd64, arm64

⁠How to use this image

For help installing Docker and pulling this image, check out the installation instructions⁠. You can also find a quick run down on using Docker commands⁠ to manage the Agent⁠.

⁠Start a Losant Gateway Edge Agent instance (docs⁠)

docker run -d --name myAgent \
  -e 'DEVICE_ID=<your-device-id>' \
  -e 'ACCESS_KEY=<your-access-key>' \
  -e 'ACCESS_SECRET=<your-access-secret>' \
  losant/edge-agent

⁠Start and mount in persistent storage (docs⁠)

docker run -d --name myAgent \
  -e 'DEVICE_ID=<your-device-id>' \
  -e 'ACCESS_KEY=<your-access-key>' \
  -e 'ACCESS_SECRET=<your-access-secret>' \
  -v /docker/host/dir:/data \
  losant/edge-agent

  By default, persistent data is stored in the VOLUME /data, which can be used with --volumes-from some-volume-container or -v /docker/host/dir:/data (see docs.docker volumes⁠).  

⁠Start and expose HTTP endpoint for triggering (docs⁠)

docker run -d --name myAgent \
  -e 'DEVICE_ID=<your-device-id>' \
  -e 'ACCESS_KEY=<your-access-key>' \
  -e 'ACCESS_SECRET=<your-access-secret>' \
  -p <host port>:8080 \
  losant/edge-agent

  By default, the Losant Agent exposes HTTP endpoint at port 8080, which can be exposed to a local host port using -p (see exposing ports⁠).  

⁠If you want to use your own agent config file (docs⁠)

You can mount in your own config file like the following:

docker run -d --name myAgent \
  -v /host/dir/custom-config.toml:/etc/losant/losant-edge-agent-config.toml \
  losant/edge-agent

  The file at /etc/losant/losant-edge-agent-config.toml is an example agent config file; it is a great starting place for creating your own agent config file.  

⁠All Available Options

Most options can be set through environment variables (most common for Docker), the configuration file, or command line flags. You can see the details for each option below this table. If an option is set multiple ways, the command line flag is used first, followed by the environment variable, and then finally falling back to the configuration file.

⁠Option Details

• CONF_PATH:
  Set the path to the agent configuration file. Defaults to the file /etc/losant/losant-edge-agent-config.toml, which is also the example configuration file.
• DEVICE_ID: REQUIRED
  Losant Device ID of the agent. This should correspond to the ID of an Edge Compute Device⁠ in your Losant account.
• ACCESS_KEY: REQUIRED
  Losant Access Key to use for the agent. This should be the key part of a Device Access Key⁠ that can be used for the given Device ID.
• ACCESS_SECRET: REQUIRED Losant Access Secret to use for the agent. This should be the secret part of a Device Access Key⁠ that can be used for the given Device ID.
• LOGGER_OUT:
  Desired destination for logging. Either console or a file path. Defaults to console.
• LOGGER_LEVEL:
  Desired logging level. One of error, warn, info, or verbose. Defaults to info.
• STORE_PATH:
  Path to the persistent store directory for the agent. Defaults to /data/losant-edge-agent-store.db.
• BROKER_HOST:
  Hostname of the broker for the agent to connect to. Defaults to broker.losant.com.
• BROKER_PROTOCOL:
  Protocol to use when connecting to the broker. Defaults to mqtts.
• BROKER_SSL_KEY_PATH:
  Path to the SSL key to use for client certificate authentication with the broker. Default is no path. If an SSL key is provided, an SSL certificate must be provided as well.
• BROKER_SSL_KEY:
  The SSL key to use for client certificate authentication with the broker. You can use this to set the contents of the key directly, instead of reading it from a file. Default is no value. If an SSL key is provided, an SSL certificate must be provided as well. If this environment variable is set, it will be used instead of BROKER_SSL_KEY_PATH.
• BROKER_SSL_CERT_PATH:
  Path to the SSL certificate to use for client certificate authentication with the broker. Default is no path. If an SSL certificate is provided, an SSL key must be provided as well.
• BROKER_SSL_CERT:
  The SSL certificate to use for client certificate authentication with the broker. You can use this to set the contents of the certificate directly, instead of reading it from a file. Default is no value. If an SSL key is provided, an SSL certificate must be provided as well. If this environment variable is set, it will be used instead of BROKER_SSL_CERT_PATH.
• WORKFLOW_DIRECTORY:
  Path to the directory containing any on disk workflows to load and run. Defaults to /data/workflows.
• UDP_ADDRESS:
  Address that the agent should bind to for any open UDP Trigger ports. Defaults to 0.0.0.0, which means to bind to all interfaces on the machine.
• QUEUE_OFFLINE_MESSAGES:
  If the agent should queue messages while offline to send later. Defaults to true.
• SUBSCRIBE_TO_PERIPHERAL_UPDATES:
  If the agent should subscribe to peripheral update topics. One of true (subscribe to all updates), false (subscribe to no updates), floating (subscribe to only floating peripheral updates), or peripheral (subscribe to only peripheral updates that have this device as their gateway). Defaults to true.
• WEBSERVER_ENABLED:
  Whether the agent web server should be enabled. Default is enabled (true).
• WEBSERVER_PORT:
  Port the agent should run its web server on. Defaults to 8080.
• WEBSERVER_ADDRESS:
  Address that the agent's web server should bind to. Defaults to 0.0.0.0, which means to bind to all interfaces on the machine.
• WEBSERVER_USERNAME:
  Username to use to authenticate requests to the agent's web server (using basic auth). Default is no username. If neither a username or a password is configured, no authentication is needed for requests against the agent's web server.
• WEBSERVER_PASSWORD:
  Password to use to authenticate requests to the agent's web server (using basic auth). Default is no password. If neither a username or a password is configured, no authentication is needed for requests against the agent's web server.
• WEBSERVER_SSL_KEY_PATH:
  Path to the SSL key to use for the agent's web server. Default is no path. If an SSL key is provided, an SSL certificate must be provided as well.
• WEBSERVER_SSL_KEY:
  The SSL key to use for the agent's web server. You can use this to set the contents of the key directly, instead of reading it from a file. Default is no value. If an SSL key is provided, an SSL certificate must be provided as well. If this environment variable is set, it will be used instead of WEBSERVER_SSL_KEY_PATH.
• WEBSERVER_SSL_CERT_PATH:
  Path to the SSL certificate to use for the agent's web server. Default is no path. If an SSL certificate is provided, an SSL key must be provided as well.
• WEBSERVER_SSL_CERT:
  The SSL certificate to use for the agent's web server. You can use this to set the contents of the certificate directly, instead of reading it from a file. Default is no value. If an SSL key is provided, an SSL certificate must be provided as well. If this environment variable is set, it will be used instead of WEBSERVER_SSL_CERT_PATH.
• WEBSERVER_SSL_BUNDLE_PATH:
  Path to the SSL certificate bundle to use for the agent's web server. Default is no path, and it is not required for SSL. If no SSL certificate or key is provided, this option is ignored.
• WEBSERVER_SSL_BUNDLE:
  The SSL bundle to use for the agent's web server. You can use this to set the contents of the bundle directly, instead of reading it from a file. Default is no value. If no SSL certificate or key is provided, this option is ignored. If this environment variable is set, it will be used instead of WEBSERVER_SSL_BUNDLE_PATH.
• LOCAL_BROKER_ENABLED:
  Whether the agent local broker should be enabled. Default is disabled (false).
• LOCAL_BROKER_PORT:
  Port the agent should run its local broker on. Defaults to 1883.
• LOCAL_BROKER_ADDRESS:
  Address that the agent's local broker should bind to. Defaults to 0.0.0.0, which means to bind to all interfaces on the machine.
• LOCAL_BROKER_USERNAME:
  Username to use to authenticate client connections to the agent's local broker. Default is no username. If neither a username or a password is configured, no authentication is needed for connections to the agent's local broker.
• LOCAL_BROKER_PASSWORD:
  Password to use to authenticate client connections to the agent's local broker. Default is no password. If neither a username or a password is configured, no authentication is needed for connections to the agent's local broker.
• LOCAL_BROKER_SSL_KEY_PATH:
  Path to the SSL key to use for the agent's local broker. Default is no path. If an SSL key is provided, an SSL certificate must be provided as well.
• LOCAL_BROKER_SSL_KEY:
  The SSL key to use for the agent's local broker. You can use this to set the contents of the key directly, instead of reading it from a file. Default is no value. If an SSL key is provided, an SSL certificate must be provided as well. If this environment variable is set, it will be used instead of LOCAL_BROKER_SSL_KEY_PATH.
• LOCAL_BROKER_SSL_CERT_PATH:
  Path to the SSL certificate to use for the agent's local broker. Default is no path. If an SSL certificate is provided, an SSL key must be provided as well.
• LOCAL_BROKER_SSL_CERT:
  The SSL certificate to use for the agent's local broker. You can use this to set the contents of the certificate directly, instead of reading it from a file. Default is no value. If an SSL key is provided, an SSL certificate must be provided as well. If this environment variable is set, it will be used instead of LOCAL_BROKER_SSL_CERT_PATH.
• LOCAL_BROKER_SSL_BUNDLE_PATH:
  Path to the SSL certificate bundle to use for the agent's local broker. Default is no path, and it is not required for SSL. If no SSL certificate or key is provided, this option is ignored.
• LOCAL_BROKER_SSL_BUNDLE:
  The SSL bundle to use for the agent's local broker. You can use this to set the contents of the bundle directly, instead of reading it from a file. Default is no value. If no SSL certificate or key is provided, this option is ignored. If this environment variable is set, it will be used instead of LOCAL_BROKER_SSL_BUNDLE_PATH.
• HEALTH_CHECK_ENABLED:
  Whether the agent health check endpoint should be enabled. Default is enabled (true).
• HEALTH_CHECK_PORT:
  Port the agent should make the health check endpoint available on. Defaults to 8010.
• HEALTH_CHECK_ADDRESS:
  Address that the agent's health check endpoint should bind to. Defaults to 127.0.0.1. Set to 0.0.0.0 to bind to all interfaces, which is required when the endpoint must be reachable from outside the container (for example, Kubernetes liveness/readiness probes).
• HEALTH_CHECK_OFFLINE_IS_UNHEALTHY:
  If the agent should consider itself unhealthy when it is not online and connected to Losant. Default is false.
• -V, --version:
  Outputs the version of the Losant Gateway Edge Agent.
• -h:
  Outputs help on the available CLI options.

Copyright (c) 2026 SUSE

https://www.losant.com⁠