Enrolling a fleet agent

This page walks through installing the fleet agent on a Linux host end to end: getting an enrollment token, installing and connecting the agent, confirming it appeared, and re-enrolling or removing it later. For what the agent actually does once connected, see Fleet agent.

Prerequisites

• A Linux host, amd64 or arm64, with root access
• Outbound network access from that host to Sencai (the agent only ever initiates the connection - no inbound port needs to be opened)
• An organization Owner or Admin role, to generate an enrollment token

Getting an enrollment token

1. Go to Fleet → Agents (/gravity/agents).
2. Click Enroll New Agent.
3. Click Generate Token.
4. Copy the install command shown - it already has the token embedded, and the token is shown in full only at this step.

Enrollment tokens are organization-scoped and single-use in the sense that they’re tied to the agent record created when you generate them - don’t share one across organizations, and treat it like any other credential.

Installing the agent

The supported path is the install script, run 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

This downloads the agent binary, verifies its checksum, installs a systemd unit, enrolls the host, and starts the service - you don’t need to run any further commands.

Caution

By default, the very first connection the installer makes to enroll the agent is not verified against a known certificate (trust-on-first-use) - someone able to intercept that one connection could steal the token or substitute their own certificate. If whoever generated the token can also give you a certificate fingerprint out of band, add it to the same command to pin that connection instead:

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

Without it, the installer proceeds anyway and prints a warning - this is a reasonable default for a private network, less so over an untrusted one.

Check that the service is running:

sudo systemctl status sencai-agent

Manual install (advanced)

If you already have the agent binary - for example, deploying it through your own configuration management rather than the install script - the same steps happen as two separate commands:

sencai-agent enroll --gateway https://agent.sencai.space --token <your-token>
sencai-agent start

enroll also accepts --gateway-fingerprint <sha256> (preferred) or --insecure-tofu (explicit opt-in, no certificate verification at all) - one of the two is required. start normally runs under the systemd unit the install script sets up; running it directly is mainly useful for testing.

Verifying the agent appeared

Back in Fleet → Agents, the new host shows up shortly after its first successful heartbeat, initially as pending, then active once it’s reporting normally. If it doesn’t appear within a couple of minutes, see the troubleshooting table below.

On the host itself, you can check the agent’s own view of things:

sencai-agent status

This prints the agent’s ID, which gateway it’s connected to, its granted capabilities, and its certificate’s expiry and reachability - useful for confirming the agent thinks it’s healthy even if the app hasn’t shown it yet.

Re-enrolling

Running enroll again with a fresh token replaces the existing configuration and certificate - useful if you need to move an agent to a different organization, or if its certificate needs replacing. There’s no separate “re-enroll” flow; it’s the same command with a new token.

Uninstalling

1. In Fleet → Agents, find the host and click Disconnect - this revokes the agent’s credentials and removes it from your organization’s fleet view.
2. On the host itself:

sudo systemctl disable --now sencai-agent
sudo rm -f /usr/local/bin/sencai-agent
sudo rm -rf /etc/sencai-agent

Disconnecting from the app is the important step - an agent that’s stopped locally but never disconnected still shows up as disconnected/stale in your fleet view rather than disappearing.

Troubleshooting

Symptom	Likely cause	What to do
Installer exits immediately with a missing-variable error	SENCAI_GATEWAY_URL or SENCAI_TOKEN not set	Re-run with both set; copy the exact command from Fleet → Agents rather than retyping it
”gateway certificate fingerprint mismatch”	The SENCAI_GATEWAY_FINGERPRINT value doesn’t match	Get the correct fingerprint from whoever issued the token - don’t guess or drop the flag to work around it
”enroll failed: gateway returned …”	The token is expired, already used, or invalid	Generate a new token from Fleet → Agents
Service is active (running) but the host never appears in the app	Outbound connectivity to the gateway is blocked, or the token belonged to a different organization	Check outbound firewall/proxy rules for the host; confirm you’re looking at the organization the token was generated for
sencai-agent status/start says “not enrolled”	Configuration is missing or corrupted	Re-run enroll with a fresh token

What’s next

• Fleet agent - what the agent does once it’s connected
• Agent policies - autonomy levels, freeze windows and custom probes (capabilities are granted on Fleet → Agents)
• Monitoring - reading telemetry from your connected agents
• Kubernetes clusters - the separate enrollment path for a cluster