Remote execution and runbooks

Sencai gives you two ways to act on a fleet agent remotely: one-off commands from a fixed template, and multi-step runbooks you define once and trigger repeatedly. Both are dispatched over the agent’s existing connection - no inbound port, no separate SSH session - and both are capability-gated per agent, so nothing runs on a host that hasn’t explicitly been allowed to accept it.

Remote commands

Fleet → Remote Exec (/gravity/fleet/remote-exec) dispatches a pre-defined command template to one or more connected agents.

1. Open Fleet → Remote Exec.
2. Choose one or more Target Agents (only currently connected agents are listed).
3. Choose a Command Template - only templates your organization has marked allowed appear here, and the template’s exact command is previewed before you run it.
4. Optionally supply arguments as JSON.
5. Click Execute.

Caution

Dispatching commands to fleet hosts is a gated capability that has to be enabled for your environment. Where it isn’t, Execute records each attempt as failed, with the reason in stderr, rather than running anything. Check with your account team before relying on remote execution.

Where dispatch is enabled, the target agent also needs the remote-exec capability granted (an organization Owner or Admin grants it per agent from Fleet → Agents → Grant Capability); without it, the dispatch is recorded as blocked rather than run.

Note

Commands run as root on the target host and are split on whitespace, never passed through a shell - quoting and escaping in the command template behave literally, not the way they would in an interactive shell.

Reading results

The Execution Results table shows every dispatch: agent, command, status (pending / running / completed / failed / blocked), exit code, and duration. Click into any row for the rendered command, stdout, and stderr.

Runbooks

Runbooks (/gravity/runbooks) are named, reusable action sequences you define once and trigger repeatedly - closer to a saved script than a one-off command.

1. Open Runbooks and click New Runbook.
2. Give it a name and a trigger type: manual (you trigger it yourself) or alert (triggered by the platform’s own alerting, covered in Operations → Auto-remediation).
3. Define its actions as a JSON list. Supported action types are restart_service, clear_disk_space, kill_process, and run_approved_script - the last one is restricted to scripts already staged on the target agent, it can’t run arbitrary paths.
4. Approval is required by default - turn Require approval off if you want a trigger to execute immediately - and set a cooldown so the same runbook can’t be re-triggered too soon after itself.

Triggering a runbook

Open a runbook and click Trigger. You must specify which agent the run targets - there’s no organization-wide “run everywhere” option. You can also run a dry run first, which reports what would happen without actually executing anything.

If the runbook requires approval, triggering it creates a pending execution - nothing runs on the host until an admin approves it.

Caution

Approving a pending execution isn’t functional in the app today - the approval step needs a token that isn’t surfaced anywhere in the UI or the API, so a pending execution has no way to be moved forward. New runbooks require approval by default, so if you want a runbook to actually execute when you trigger it, turn Require approval off. See Runbooks for the full authoring and approval detail.

Creating, editing, and triggering runbooks - like triggering remote commands - requires an organization Owner or Admin role, given the direct access to a host either capability provides.

Audit trail

Every command dispatch and every runbook trigger - who initiated it, on which agent, with what result - is recorded in your organization’s audit trail. See Audit log.

What’s next

• Fleet agent - the capability model this all runs on top of
• Agent policies - autonomy levels, freeze windows, secret injection and custom probes (capabilities are granted on Fleet → Agents)
• Runbooks - authoring, dry runs, approval, and versioning
• Auto-remediation - runbooks triggered by alerts, not by you
• Quarantine - isolating a host instead of running a command on it