Fleet management

Fleet management lets an organization view and manage its declared host fleet from the dashboard: a roster of every declared host, per-host detail, and controls to declare or remove hosts. It is always available; who can see and manage the fleet is governed by the fleet permission.

The fleet view

A Fleet section appears in the dashboard for members who hold the fleet:read permission (Owners by default). It surfaces the declared host fleet read-only — viewing the fleet never changes it.

Roster

The fleet roster lists every host declared for the organization.

• Status reflects each host’s current reachability: ready (connected and recently seen), unreachable (a declared host that is not currently connected), or stale (an ephemeral host past its time-to-live).
• An Unconfirmed badge marks a host declared from the dashboard that its agent or an operator has not confirmed yet. Such a host is not a runsOnAll target.
• Labels, hostname, and platform/arch describe how a host is targeted and what it runs on.

Use the filter box to narrow the list by agent id, hostname, or label. Select a host to open its detail view.

The roster reads through the orchestrator that owns the organization’s host fleet, so the status you see is the orchestrator’s live view of each host.

Host detail

The host detail view shows a single host’s full metadata — labels, typed properties, hostname, platform and architecture, lifecycle class, status, and last-seen time — alongside the runs pinned to that host.

It also lists the fan-outs targeting this host: every registered runsOnAll workflow whose selector matches the host. An auto-scaler agent is never a fan-out target, so this list is empty for one. For each match:

• Workflow — links to the workflow’s runs.
• On unreachable — the fan-out’s policy (skip, fail, or hold) for an unreachable host.
• Disposition — whether this host would receive a job right now (target), be held as an unreachable durable host (unreachable-durable), or be skipped as a non-live ephemeral host (skipped-ephemeral).

A host’s recent runs link back to the run detail page so you can trace what each host has executed. The fan-outs list is a read-only, derived view — it never starts a run.

Managing hosts

Members who hold the fleet:write permission can change the host inventory from the dashboard: declare a new static host into the roster, and remove a host that nobody confirmed. The command-line equivalents, kici-admin host declare and kici-admin host remove, can change and remove any host.

Declare a host

Declares a static host into the roster before its agent connects. Enter the agent id the host will register as, optional comma-separated labels and an optional hostname.

A host declared here is unconfirmed: it is not a runsOnAll target, an inventory result or an unreachable-host alarm until its agent registers or an operator confirms it with kici-admin host declare. The dashboard shows the confirming command after a declare. Requires the fleet:write permission.

A host declared with kici-admin host declare --agent-id <id> --labels <a,b> is confirmed at once. It names an expected member of the fleet ahead of time, so a runsOnAll fan-out can target it (and report it as unreachable) instead of silently skipping a host that has not connected yet.

The dashboard only creates hosts. It refuses a declare for an agent id that already exists (HTTP 409 host_exists). It also refuses labels or properties in the reserved kici: namespace (HTTP 400 reserved_property). To change an existing host, or to set reserved keys such as the agent restart commands, use kici-admin host declare. When the agent registers, its own labels, hostname and properties replace the declared ones.

Remove a host

Removes an unconfirmed host from the roster. A confirmation step guards the action. A host that its agent or an operator confirmed shows the kici-admin host remove command instead: the dashboard refuses to remove it (HTTP 409 host_confirmed).

Runs already pinned to the host keep their history; the host leaves the roster. Requires the fleet:write permission.

The command-line equivalent is kici-admin host remove --agent-id <id>.

Per-operation policy

Both writes are governed by the orchestrator’s per-operation dashboard-write policy. An operator can disable either one for an organization with kici-admin org-settings dashboard-writes, which makes the dashboard control render disabled with the matching command-line equivalent to run instead. When an operation is disabled, the dashboard request is refused and the attempt is recorded in the access log.