Enroll your first Linux host

By the end of this tutorial you have one Linux host running the Sencai fleet agent, showing as active in the app, with the inventory-scanning capability granted and a CIS hardening score on its way. The hands-on part takes about 25 minutes. The last two results - the software inventory and the hardening score - arrive on the agent’s own scan schedule rather than on demand, so plan to come back for them.

Each step points at the page that covers it in depth. Read this as the order to do things in, not as a replacement for those pages.

Before you start

• A Linux host, amd64 or arm64, with root access, and outbound network access from it to Sencai. The agent only ever initiates the connection, so you don’t need to open an inbound port - see Enrollment.
• An Owner or Admin role in the organization you’re enrolling into. Generating an enrollment token needs one of those two - see Roles & permissions.
• Lynis installed on the host, if you want step 5 to produce anything. A host with no Lynis binary is skipped silently - see CIS hardening.
• A look at what the agent collects and how often, so nothing in the next half hour is a surprise.

1. Generate an enrollment token

Go to Fleet → Agents (/gravity/agents), click Enroll New Agent, then click Generate Token. Copy the install command it shows you - the token is already embedded in it, and the token is shown in full only at this step.

Enrollment tokens are organization-scoped and tied to the agent record created when you generate them. Don’t share one across organizations, and treat it like any other credential.

Full detail, including what to do when a token is rejected: Enrollment.

2. Install the agent on the host

Run the command you copied, as root, on the target host:

curl -fsSL https://agent.sencai.space/install.sh \
  | SENCAI_GATEWAY_URL=https://agent.sencai.space SENCAI_TOKEN=<your-token> bash

That one command downloads the agent binary, verifies its checksum, installs a service unit, enrolls the host, and starts the service. There is nothing further to run.

Caution

By default the installer’s very first connection is not verified against a known certificate (trust-on-first-use), so anyone able to intercept that one connection could steal the token or substitute their own certificate. If whoever generated the token can give you a certificate fingerprint out of band, pass it as SENCAI_GATEWAY_FINGERPRINT in the same command. Without it the installer proceeds anyway and prints a warning - a reasonable default on a private network, less so over an untrusted one. Enrollment shows the exact command.

Confirm the service came up:

sudo systemctl status sencai-agent

If you deploy binaries through your own configuration management instead, the same work splits into sencai-agent enroll and sencai-agent start - the manual path is documented on Enrollment.

3. Confirm it is heartbeating

Back on Fleet → Agents, the new host appears shortly after its first successful heartbeat - first as pending, then as active once it’s reporting normally. The agent sends a heartbeat every 30 seconds, and that heartbeat is what drives the connected/disconnected status you see here.

A host marked active is treated as stale, and flagged visually, if its last heartbeat is more than about 90 seconds old. Immediately after an install that usually means a brief network blip the agent recovers from on its own; if it stays stale for more than a few minutes, check the host directly. See Monitoring for how to read that distinction.

On the host itself, sencai-agent status prints the agent’s own view - its ID, which gateway it’s connected to, its granted capabilities, and its certificate expiry. That’s the fastest way to tell “the agent is fine, the app just hasn’t caught up” apart from a real failure.

Note

Host telemetry - CPU, memory and disk per agent - lives on a separate screen, Fleet → Agent Telemetry (/gravity/fleet/telemetry), refreshed every 60 seconds. Telemetry collection is a platform-side setting for your environment rather than something you turn on per agent, so this table can stay empty while your agent shows as connected. If that’s what you see, contact support to confirm it’s enabled for your account. Treat any reading here as a point in time, not a trend.

4. Grant the inventory-scanning capability

This is the step that’s easy to skip and easy to misdiagnose afterwards. A newly enrolled agent starts with monitoring only. Every capability beyond that - inventory, patch scanning, CIS hardening, remote execution - is granted per agent, and the agent enforces that allow-list itself.

Grant it from Fleet → Agents → Grant Capability → Inventory: Scan. An agent without it never uploads its package list, so the host simply won’t appear in a software search even though it is connected and reporting normally. Nothing anywhere tells you the capability is missing; the results are just absent.

Re-run sencai-agent status on the host and check the capability now shows in its granted list.

Results land under Compliance & Audit → Software (/gravity/inventory/software), where you search installed packages by name across every enrolled agent. The first inventory scan runs about 10 minutes after the agent starts, after the initial patch scan, and roughly every 24 hours after that - so don’t expect a search to find anything the moment the install finishes. Software inventory covers what each result column means and what to check when a package you expect is missing.

5. Read the host’s hardening score

Open Compliance & Audit → CIS Hardening (/gravity/inventory/cis). Each host gets a score from 0-100 - Good at 80 or above, Warning from 60 to 79, Critical below 60 - with the fleet-wide average and a count per category at the top. Expand a row to see up to the top 10 Lynis warnings for that host, each with its own warning ID and message.

Two things have to be true before your host shows up here: Lynis is installed on it, and the agent has the CIS capability granted, the same way you granted inventory in step 4. A host missing either one doesn’t appear with an error - it just has no score yet.

Caution

There is no manual “scan now” button. Scans run on a recurring schedule, roughly once a day, so the score for a host you enrolled minutes ago will probably not be there during this sitting - allow up to a day and use Refresh once results have landed. The score also reflects the host’s state at scan time, not live.

There’s no one-click fix here either. Lynis warnings are host-level configuration issues that your team resolves on the host, exactly as you would running Lynis standalone. How deep the scanning goes depends on your organization’s plan: Starter includes baseline CIS scanning, Professional and Business add deeper Lynis coverage, and Enterprise scope is custom to your agreement. See Plans, or sencai.space/pricing for the numbers.

Full detail: CIS hardening.

What’s next

• Patch management - the patch-scanning capability on the same agent, and why that screen is a report rather than a control panel
• Agent policies - fleet-wide custom probes, and how much autonomy automated actions get in your organization
• Remote execution - dispatching allow-listed commands and runbooks to the host you just enrolled
• Compliance → Inventory - the separate picture of what’s running in your connected cloud accounts