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
services:
velumedge-agent:
image: ghcr.io/davydovvn/velumedge-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:ro
cap_drop:
- ALL
cap_add:
- NET_RAW
- NET_ADMIN
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
pids_limit: 512
mem_limit: 2g
Everything in it matters:
| Key | Why it is there |
|---|---|
image | The sensor build to run. Pin it, so a redeploy is a decision rather than a surprise |
restart: always | The 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 |
MODE | What the container does at startup — see the table below |
TOKEN | The deployment token from the previous step. Read during enrolment only |
volumes | The 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 |
cap_drop, cap_add | The sensor runs as root only so that scanning can open raw sockets. Every other capability is dropped; NET_RAW and NET_ADMIN are what active scanning, OS detection included, needs |
security_opt, read_only, tmpfs | Nothing in the container can gain privileges, and it cannot change its own files: it writes only to the mounted directories and to /tmp |
pids_limit, mem_limit | An upper bound on what the sensor can take from the host |
The mode decides what a start does:
| Mode | Behaviour |
|---|---|
connect_and_run | Enrol if there is no stored token, then run — the usual choice |
connect | Exchange the deployment token for an API token, store it, exit |
run | Start the polling loop with an already-stored token |
reset | Delete 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:
{
"server": {"host": "https://console.example.com"},
"secure": true,
"proxy": null,
"global": {"sleep_period": 30, "max_concurrent_tasks": 4},
"logging": {"file": "logs/agent.log", "level": "INFO"}
}
| Setting | Meaning |
|---|---|
server.host | The console this sensor reports to |
secure | Whether TLS certificates are verified — leave true outside a lab |
proxy | Proxy settings for every outbound call the sensor makes |
global.sleep_period | Seconds between polls |
global.max_concurrent_tasks | How many scans the sensor runs at once (default 4). Further scans wait as Queued in the console until one finishes. Connection tests have one extra slot of their own, so they never wait behind a long scan |
global.request_timeout | How long, in seconds, the sensor waits on a system it collects from (LDAP, CrowdStrike, Elastic, Microsoft Graph, ...) before giving up on the call (default 180). A system that accepts the connection and never answers would otherwise hold a scan slot until the sensor restarts |
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.
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}.
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
- Upgrade a sensor on Linux (Docker) — when a new build ships
- Sensors — what a sensor does, requirements and placement