Run a Linux fleet

This path is for whoever is responsible for a set of Linux servers - in a cloud, on bare metal, in a rack in your own building, or all three. It does not assume you have connected a cloud account to Sencai, and it does not assume Sencai provisioned any of these machines. The fleet agent treats a host you built by hand exactly the same as one it created.

By the end you will have one agent enrolled and reporting, a package search that answers “which of my hosts still have this installed” across the whole estate, a per-host view of how many updates are pending, and a hardening score per host with its top warnings. You will also have decided how much a machine is allowed to do on its own, which is a separate question from what any single agent is allowed to be asked to do.

It assumes you already have an organization and can sign in at app.sencai.space. If you do not, Your first hour with Sencai gets you there; the fleet-agent branch of that page is the same starting point as step 2 here.

Before you start

Three things have to be true on your side:

• A Linux host you have root on, amd64 or arm64, that can make outbound connections to Sencai. No inbound port has to be opened - the agent always initiates its own connection.
• The Owner or Admin role in the organization the host should belong to. Generating an enrollment token needs it, and so does granting any capability later. A Member cannot do either. See Roles & permissions, and note that Auditor sits below Member - it is a read-oriented role, not a shortcut to Admin.
• A certificate fingerprint from whoever issued the token, if the host will enroll across a network you do not control. Without one, the first connection is trust-on-first-use; Enrollment explains the tradeoff and prints a warning rather than refusing.

Two gates are worth knowing about before you invest the afternoon:

Caution

Hardening scores need Lynis already installed on the host. The agent runs it; it does not install it. A host without the binary is skipped silently - no error row, no zero score, it simply never appears in the table. Scanning depth also differs by plan: Starter covers baseline CIS checks, while Professional and Business add deeper Lynis coverage. See Plans and sencai.space/pricing.

Note

Everything this path produces is a read of your fleet, and none of it needs an account-team request. Acting on hosts is a different story - remote command dispatch and quarantine are gated per environment and can fail outright where they are not switched on. Those pages are listed under What’s next, deliberately outside this path.

The path

The order is reading before controlling. The first page defines the capability model that decides whether every later page has any data in it at all, so skipping it turns the rest into guesswork. Connection status comes before the data pages because it is what lets you tell “this host is not reporting” apart from “this capability was never granted” - two very different problems that look identical from a table of empty rows. Inventory comes before patching because it is the query you will actually reach for the morning a disclosure lands. Hardening is last of the read pages because it is the one with a prerequisite on the host itself. Only then do policies and releases, which are about governing the fleet rather than looking at it.

0 of 8 read

1. 1 Understand what the agent does What it collects, how often, its outbound-only network posture, and the capabilities you grant per agent. Open →
2. 2 Enroll your first host Generate a token, run the install script, verify the fingerprint, and confirm the agent registered. Open →
3. 3 Read connection status and telemetry These are two different tables. One tells you the agent is alive; the other tells you what the host is doing. Open →
4. 4 Search packages across every host One query across the whole estate, once the inventory capability is granted to the agent. Every capability beyond basic monitoring is granted per agent. Inventory shows nothing until you grant it. Open →
5. 5 Read patch-scan results Package manager, updates available, scan errors, and maintenance windows. Open →
6. 6 Check hardening scores A score per host with its top warnings, so you can see which hosts are furthest from a sane baseline. Open →
7. 7 Set autonomy policies Autonomy levels, freeze windows, maximum blast radius, and which action types are allowed at all. Open →
8. 8 Manage agent versions The release catalog, its rollout stages, and how to move a specific agent to a specific version. Open →

What to watch out for

A newly enrolled agent does almost nothing, on purpose. It starts with monitoring only. Every other capability - inventory scanning, patch scanning, CIS scanning, remote execution, quarantine - is granted per agent by an Owner or Admin from Fleet → Agents (/gravity/agents). An agent without the inventory capability never uploads its package list, so it is missing from a software search while looking perfectly healthy on the Agents page. This is the single most common reason a fleet screen looks broken when it is not.

Nothing useful appears in the first ten minutes. The first patch scan runs about five minutes after the agent starts and the first inventory scan about ten minutes after it starts; both then repeat roughly every 24 hours, as does the hardening scan. Judge the setup tomorrow, not this afternoon.

Two tables, two meanings. Connection status on Fleet → Agents tells you the host is reachable. Host telemetry on Fleet → Agent Telemetry (/gravity/fleet/telemetry) tells you what the host is doing. They are collected on separate cycles, so a connected host can sit next to an empty telemetry row without anything being wrong. Telemetry collection is a platform-side setting for your environment rather than a per-agent grant - if it stays empty across every agent, contact support rather than re-granting capabilities.

A heartbeat older than about 90 seconds marks a host stale on Fleet → Agents. Usually that is a network blip the agent recovers from on its own within a minute or two. If it persists for more than a few minutes, go look at the host. Monitoring has the full reading.

The patch screen reports; it does not patch. There is no button on Infrastructure → Patches (/gravity/patches) that applies updates to a host, and no scheduled apply happens behind your back either. The maintenance windows shown in a scan’s details are informational - nothing reads them, and there is no screen to configure them. Granting the patch-apply capability is a prerequisite for a future apply, not a trigger for one. Apply updates on the host the way you do today; the next scan reflects the lower count within about a day. Plan your patching around that, and read Patch management before you promise anyone a patch window driven from this screen.

Agent policies are not capability grants. They look adjacent in the sidebar and they are not the same control. A capability grant decides what a specific agent may be asked to do. An agent policy on Fleet → Agent Policies (/gravity/settings/agent-policies) decides how much an automated action may do on its own - autonomy level, freeze windows, blast radius. Start new policies at L0 or L1. If you go to L2 or L3, pair it with a tight blast radius and at least one freeze window.

Custom probes have no per-agent targeting. A probe defined on Fleet → Custom Probes (/gravity/fleet/probes) runs as root on every enrolled agent in the organization, on your schedule. Only the binary is allow-listed; the arguments are not. Read the exact command the screen previews before saving, the same way you would review a command before dispatching it.

The release catalog does not move anything. Fleet → Agent Releases (/gravity/fleet/releases) tracks which versions exist and how far each has rolled out. To actually move a host, select it on Fleet → Agents and use Force Update. There is no pin toggle either - pinning is force-updating to a version and then not pushing a newer one. A separate screen with the same trap: Fleet → Cohorts (/gravity/fleet/cohorts) records a cohort as active but does not execute anything against your fleet. For a recurring fleet-wide check, use custom probes.

Caution

The browser terminal is grouped under Fleet, but it does not run over the agent’s connection. It needs the machine to be registered as a cloud instance as well; a host that is only fleet-enrolled cannot be reached from it. It is also a Professional-tier feature and up. See Browser terminal before you plan an incident response around it.

What’s next

• Remote execution and runbooks - acting on hosts rather than reading them, and the environment gate that decides whether dispatch works for you at all
• Quarantine - cutting a suspected host off at the network level, including why you want both the isolate and release grants before you need either
• Kubernetes clusters - a separate in-cluster agent with a separate enrollment path, for the clusters this path does not cover
• Learning paths - the other routes through this documentation, if cloud accounts or compliance evidence come next for you