Skip to main content

Install a sensor on Linux (Docker)

The supported deployment path today. The sensor is distributed as a container image and run with Compose on any Linux host that can reach the console.

Before you start, check the system and network requirements and decide where the sensor needs to sit — placement is what decides which integrations it can run.

Get a deployment token​

In the console, open Settings → Sensors → Add sensor and reveal or copy the tenant's deployment token — the same token described under Enrolling a sensor. It is valid for 60 minutes, so fetch it when you are ready to install rather than in advance.

Write the compose file​

docker-compose.yml
version: '3'
services:
  lumenedge-agent:
    image: lumenedge-agent:v0.9.0
    restart: always
    network_mode: "host"
    environment:
      MODE: connect_and_run
      TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI0MSIsImlkIjo0MSwidGVu…
    volumes:
      - ./data/:/root/integration-app/data/
      - ./logs/:/root/integration-app/logs/
      - ./config.json:/root/integration-app/config/config.json

Everything in it matters:

KeyWhy it is there
imageThe sensor build to run. Pin it, so a redeploy is a decision rather than a surprise
restart: alwaysThe sensor comes back with the host, and after a crash
network_mode: "host"Gives the container the host's interfaces — needed for the raw sockets active scanning uses and for promiscuous capture. A sensor that will only ever run API integrations does not need it
MODEWhat the container does at startup — see the table below
TOKENThe deployment token from the previous step. Read during enrolment only
volumesThe data directory (which holds the sensor's own API token), the log directory and the config file. These have to live on the host, or replacing the container means enrolling again

The mode decides what a start does:

ModeBehaviour
connect_and_runEnrol if there is no stored token, then run — the usual choice
connectExchange the deployment token for an API token, store it, exit
runStart the polling loop with an already-stored token
resetDelete the stored token, so the host can be enrolled again

Write the config file​

config.json is the sensor's own configuration — which console it reports to, how it gets there, and how often it polls:

config.json
{
  "server": {"host": "https://console.example.com"},
  "secure": true,
  "proxy": null,
  "global": {"sleep_period": 30},
  "logging": {"file": "logs/agent.log", "level": "INFO"}
}
SettingMeaning
server.hostThe console this sensor reports to
secureWhether TLS certificates are verified — leave true outside a lab
proxyProxy settings for every outbound call the sensor makes
global.sleep_periodSeconds between polls

Start it​

docker compose up -d

Within a poll interval the sensor appears in Settings → Sensors with a current last-seen time. If it does not, the sensor's log — in the mounted logs/ directory — is the place to look: a rejected token and an unreachable console fail differently there.

Remove the token once the sensor has enrolled

TOKEN is only read during enrolment. Once the sensor has registered and stored its own API token in the mounted data directory, delete the TOKEN line — the sensor keeps running and restarting without it, and a stale deployment token stops sitting in a file that tends to end up in version control.

If you would rather keep it out of the compose file from the start, put it in a .env file beside it and reference it as TOKEN: ${TOKEN}.

The stored API token is the sensor's identity

It is long-lived by design — the platform's default session length is measured in years — so anyone who copies it can act as that sensor until it is deleted in the console. Treat the data directory as secret, and delete the sensor from the console if a host is decommissioned or compromised.

After the first check-in​

Rename the sensor from its detail view — registration names it Sensor-<hostname>, and something that says where it sits is what you will want when you start assigning integrations to it. Then assign the integrations it is meant to run; see Integrations.

See also​