Fleet — Server Agent

Sencai Fleet is a lightweight Go binary you install on your servers (bare metal or VM). Once enrolled, Fleet reports back to Sencai continuously: software inventory, patch status, CIS security benchmarks, and runbook execution results. You can also open a browser-based terminal to any enrolled server directly from the Sencai UI.

Fleet works on any Linux server — bare metal, cloud VMs, and Kubernetes nodes.

What the agent does

Software inventory: lists installed packages via dpkg-query (Debian/Ubuntu) or rpm -qa (RHEL/Fedora), cross-checked against endoflife.date for EOL risk
CIS benchmark: runs Lynis CIS Level 1/2 hardening checks and reports scores
Patch status: identifies outdated packages and CVE exposure
Browser terminal: click “Connect” for an in-browser SSH session to any enrolled server
Runbook execution: run pre-approved operational tasks remotely, gated by the runbook:execute capability
Quarantine: isolate a compromised server with one click
Heartbeat: sends a liveness ping every 30 seconds — Sencai detects downed servers within about 2 minutes

Capability whitelist

Fleet agents start with zero capabilities. An operator must explicitly grant capabilities per agent (or per agent group) before the agent will perform the corresponding scan or action. Grants are managed as agent-policy records, configured from the Agents page (/gravity/agents) and the capability/policy settings page at /gravity/settings/agent-policies.

Available capabilities:

Capability	What it unlocks
`monitor`	Metrics/process/service monitoring heartbeat data
`patch_management:scan`	Scanning for available OS package updates
`patch_management:apply`	Applying patches
`inventory:scan`	Software inventory collection
`log_shipping:system`	Shipping system logs
`log_shipping:app`	Shipping application logs
`runbook:execute`	Executing runbooks on the host
`agent:update`	Self-updating the agent binary

If a capability has not been granted, the agent silently skips that scan or action rather than failing loudly — check the granted capability list on the Agents page if expected data isn’t showing up. Runbook execution in particular requires the runbook:execute capability to be granted before any runbook can run on that agent.

Installing the agent

Prerequisites

Linux server (amd64 or arm64)
Outbound network access to your organization’s agent-gateway endpoint (default port 4400)
Root or sudo access on the server
An enrollment token from your organization admin

Step 1: Install

The recommended install method is the .deb/.rpm package for your distribution, built via nfpm. Alternatively, use the install script:

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

This installs the sencai-agent binary to /usr/local/bin/sencai-agent and creates a systemd unit (sencai-agent.service).

Step 2: Enroll

If you installed via the .deb/.rpm package, or want to enroll manually:

sudo sencai-agent enroll --gateway https://agent-gateway:4400 --token <your-org-enrollment-token>

There is no --url or --name flag — enrollment only takes --gateway and --token.

During enrollment:

The agent sends the enrollment token plus hostname/OS/arch/version to agent-gateway’s /enroll endpoint
agent-gateway issues an mTLS client certificate and CA bundle, and returns the initial capability grant
Certificates and config are written to /etc/sencai-agent/
The agent begins its heartbeat loop once started

You’ll see the server appear on the Agents page (/gravity/agents) shortly after the first successful heartbeat.

Step 3: Enable the systemd service

sudo systemctl enable --now sencai-agent
sudo systemctl status sencai-agent

The agent starts automatically on boot and reconnects (with exponential backoff) after network interruptions.

Kubernetes deployment

For Kubernetes clusters, a separate k8s-agent (Helm chart / manifests) handles fleet management at the cluster level — this is a distinct component from the host-level sencai-agent binary described above. Consult your organization admin or the Kubernetes fleet documentation for enrollment steps specific to k8s-agent.

Enrolled agents view

Go to Agents (/gravity/agents) to see all enrolled agents with the following columns:

hostname
os
version
status
last_heartbeat_at
cloud_instance — link to the associated cloud instance if the agent was enrolled on a Sencai-provisioned instance; agents enrolled directly on on-prem/bare-metal hosts show an explicit On-Prem chip here instead of a blank dash, since that’s a fully supported enrollment path, not a missing/incomplete one

From this page you can also manage per-agent capability grants and trigger available actions (Connect, Quarantine, Run Runbook, etc.).

Other fleet-operational pages:

/gravity/fleet/quarantine — quarantine management
/gravity/fleet/remote-exec — remote command execution
/gravity/fleet/telemetry — agent telemetry
/gravity/fleet/cohorts — cohort/ring rollout management
/gravity/fleet/kubernetes — Kubernetes fleet view
/gravity/fleet/config — fleet configuration
/gravity/fleet/releases — agent release management
/gravity/fleet/secret-injections — secret injection management

Browser terminal

To open a terminal session to a server:

Go to Agents (/gravity/agents)
Click on an agent
Click Connect — a terminal panel opens in your browser
Type commands — full interactive shell, exactly like SSH

Under the hood, your browser opens a WebSocket connection to ssh-proxy-service, which authenticates your JWT and opens an SSH connection to the target server via the Fleet agent’s tunnel. All keystrokes and output are logged to the audit trail.

Inventory and scanning

Software inventory

With the inventory:scan capability granted, Fleet collects installed packages every 24 hours using dpkg-query (Debian/Ubuntu) or rpm -qa (RHEL/Fedora/CentOS/SUSE) — there is no osquery dependency. Collected packages are cross-checked against endoflife.date to flag EOL and soon-to-be-EOL software.

View inventory from the Agents page and drill into a specific agent.

CIS benchmark scans

Lynis CIS scans run automatically every 24 hours and on demand. Results show:

Overall CIS score (0–100%)
Per-control pass/fail status
Remediation suggestions for failed controls
Score trend over time (improving / stable / degrading)

Patch status

With the patch_management:scan capability granted, the agent checks for available OS updates daily. The Patches view shows:

Available updates by package
CVE IDs for security patches
Age of the patch (days since release)
Estimated risk level (critical / high / medium / low)

Applying patches requires the separate patch_management:apply capability.

Runbooks

Runbooks are pre-written scripts that can be executed on enrolled agents. They live at the top-level Runbooks page (/gravity/runbooks) — not under a “Fleet” section.

Common examples:

System update
Service restart
Log collection and bundle
Certificate rotation
Custom scripts

Executing a runbook

An agent must have the runbook:execute capability granted (via agent-policy, from the Agents page or /gravity/settings/agent-policies) before it will accept a runbook dispatch. If the capability is missing, agent-gateway rejects the dispatch request outright.

All runbook executions are logged in the audit trail: who triggered it, which agent, output, exit code, and timestamp.

Quarantine

If a server is compromised or behaving abnormally, quarantine isolates it at the network level:

Go to /gravity/fleet/quarantine (or the agent’s row on the Agents page)
Click Quarantine
agent-gateway triggers an OS-level iptables OUTPUT DROP rule on the agent host, tagged with a comment (sencai-quarantine-<agentID>) so it can be identified and removed later
Alert is sent to organization admins

Quarantine is Linux-only and requires the agent host to have passwordless (NOPASSWD) sudo rights for iptables. On non-Linux hosts, quarantine fails with an explicit error and makes no system modification — it does not silently no-op.

To release quarantine: click Release Quarantine after remediation (requires appropriate role). This removes the tagged iptables rule.

Troubleshooting

Q: Agent enrolled but shows offline immediately

A: Check that the agent service is running: sudo systemctl status sencai-agent. Check outbound connectivity to your agent-gateway endpoint (default port 4400). Review logs: sudo journalctl -u sencai-agent -f.

Q: CIS scan is not running

A: Lynis must be installed on the server. Install it via your package manager: sudo apt install lynis or sudo yum install lynis.

Q: Browser terminal shows “Connection failed”

A: Ensure the agent is online (recent heartbeat on the Agents page). No inbound ports are needed — only outbound access to the gateway. If still failing, check the agent logs.

Q: I don’t see the agent after enrollment

A: Wait for the first heartbeat and refresh. If still missing, check the enrollment command output for errors. Common issue: wrong or expired enrollment token (tokens are org-scoped).

Q: A capability I expect isn’t doing anything

A: Ungranted capabilities cause the agent to silently skip the corresponding scan or action. Confirm the capability is granted for that agent via /gravity/settings/agent-policies.

Q: How do I update the agent?

A: Run sencai-agent update on the host, or re-run the install script/package upgrade — the agent supports ring-based rollout for self-updates. Confirm the agent:update capability is granted; the systemd service restarts automatically after a successful update.