How do I activate my licence and run the first scan?

Your licence key is created when you order and is shown in the client area, together with the activation command and the list of servers currently using it. It looks like this:

STL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Activate

sudo shelltrap license activate STL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
shelltrap license status

Activation binds the licence to a server fingerprint derived from /etc/machine-id, and the service issues an Ed25519-signed token. The token lands in /etc/shelltrap/license.token, owned by root, mode 0600. Only the key prefix is stored in /etc/shelltrap/license.key, so renewals do not ask you to type the key again. If you would rather not have the key on the server at all, delete that file and renew manually.

The daemon verifies the token offline. The licence service does not have to be reachable for the scanner to work — it has to be reachable to renew.

Check that the host is healthy

shelltrap health
shelltrap status

On a well-configured host expect tier A, a healthy store, two workers running as shelltrap-scan, Landlock active, a site index that matches your CyberPanel database, and an active feed generation. Without a feed generation only ClamAV (in the full profile) and the heuristics run, which is acceptable for a test stage but is reported as degraded rather than glossed over.

Run the first scan

You can scan a single site, a whole account, or an explicit path:

shelltrap scan example.com
shelltrap scan --account customer1
shelltrap scan --path /home/customer1/public_html

Free-form path scanning is deliberately restricted to a root shell on the local socket; a panel or UI user can never make the broker open an arbitrary path.

Look at what it found

shelltrap findings list
shelltrap findings show <id>
shelltrap jobs list

Add --json before the command to get the API response unchanged; without it you get a deterministic human-readable table. Exit codes are 0 success, 1 API or response error, 2 usage error and 3 API unreachable.

What the first run costs

A first start without a clean shutdown marker plans a full reconciliation crawl, and on a busy host that is real work: queue age climbs while it drains and health stays degraded until it has. That is correct behaviour — the scanner really is behind — but it is much nicer if you set cgroup limits in a systemd drop-in before the first start rather than after. On our own reference host with 328 accounts and 1.1 TB, that crawl ran at roughly 114 scans per minute with two workers and about 270 with four.