Edge command reference (s9)
s9 is the command-line interface to the Edge Agent, the small,
statically-linked, signed binary that runs System9 where a cell cannot always be
reached: field devices, workstations, IoT gateways, and tactical kits. Everything
the Edge Agent does on a host, enrolling its identity, running the steady-state
daemon, reasoning with the on-device agent, serving models, verifying couriered
bundles, is driven through s9.
This section is the operator reference for that binary. It is organised around what you do with the device, not around the internal service each command talks to. For the architectural picture of how the Edge Agent relates to a cell, start with Core and Edge; for where it sits among the deployment shapes, see Deployment topology.
The pages below document each command in isolation. For the task-oriented view, keeping the daemon supervised, draining the journal, refreshing certs, checking revocation, and applying signed upgrades as a recurring discipline. See the Edge operator runbook.
Some command tokens are literals you type (s9 discovery-mapping,
s9 fleet-releases, s9 model-serving, …). Those literals are the interface, so
they are shown exactly. Everywhere else this reference uses the public feature
name, the Discovery & Mapping,
Fleet Releases, and
Model Serving commands, and so on.
Two ways to run it
The Edge Agent has one binary and two operating modes. Every command in this reference is one or the other.
- One-shot commands. You invoke
s9 <command>, it does one thing, prints a result, and exits. Enrolling (s9 enroll), asking the on-device agent a single question (s9 chat "…"), running a mission (s9 do "…"), verifying a bundle, exporting an audit record, all one-shot. This is how an operator drives the device by hand and how scripts and CI jobs use it. - The resident daemon.
s9 runstarts the steady-state loop: it sends periodic heartbeats, serves models locally, watches inboxes, and (when armed) captures sensors and forwards spooled work. This is the process a host's init system supervises for a permanently-deployed device.s9 fleet-releases service installinstalls the OS service entry that keeps it running.
Sovereign and air-gapped by construction
The Edge Agent is the deployment the product is built for, sovereign, on-premises, and frequently air-gapped. That posture shapes the command set:
- Nothing requires a round trip to decide. Offline authorization, signature verification, and classification all evaluate locally.
- Every command that admits new material off removable media is a verified,
offline route. The
apply-bundle/apply-object/applysubcommands take a signed bundle from a courier's USB stick, verify it against the trust roots the device already holds, and apply it with no network in the loop. Field-manual briefings, catalog objects, certificate revocations, fleet releases, model approvals, and spawn delegations all have this offline path. - Work done while dark is spooled and rides home later. Metering records, discovery bundles, and cognition partials accumulate locally and drain to a cell when a link returns.
Figure: the two operating modes and the offline courier route. The daemon and one-shot commands reach a cell when a link exists (solid); the courier route (dashed, "no network") verifies a signed bundle off removable media before the device admits it, so an air-gapped device still receives governed updates.
Table equivalent
| From | Relationship | To | State (meaning) |
|---|---|---|---|
| Operator / script | runs | One-shot command | edge (outlined) |
| Operator / script | runs | Resident daemon (s9 run) | edge (outlined) |
| Resident daemon | heartbeat / drain when linked | A cell | core (filled) |
| One-shot command | when connected | A cell | core (filled) |
| Signed bundle on removable media | no network (air-gap) | apply-bundle verify + admit | refusal / held-apart (amber, dashed) |
apply-bundle (verified) | admits into | Resident daemon / stores | verified (green) |
Global options
Every command accepts the same four global options.
| Option | Environment | Effect |
|---|---|---|
--config <PATH> | S9_EDGE_CONFIG | Use an explicit config file (default ~/.s9/config.yaml). Highest precedence; overrides --profile. |
--profile <NAME> | S9_EDGE_PROFILE | Run under a named profile with its own isolated state dir (~/.s9/profiles/<name>): identity, certs, and binding. Ignored when --config is set. |
-v, --verbose | Increase logging verbosity. Repeatable (-vv, -vvv). | |
-h, --help / -V, --version | Print help for any command / subcommand, or the version. |
Profiles: many instances on one host
A profile gives an Edge Agent instance its own isolated state root, so
several instances (each bound to a different workspace or clean room) coexist
on one host without sharing identity, certificates, sessions, or model-serving
sockets. Selecting --profile <name> (or S9_EDGE_PROFILE) forces the whole
state directory to ~/.s9/profiles/<name>; an explicit --config wins over it
and keeps the config file's own state_dir. Inspect what exists with
s9 profile list and
s9 profile show.
Running bare s9 with no subcommand prints a short welcome that points at
s9 setup; s9 --help lists every command.
The command families
The rest of this section groups the commands by task.
| Family | What you do | Commands |
|---|---|---|
| Enrollment & identity | Bring a device online, manage its cryptographic identity, and tear it down | setup, enroll, decommission, identity, status, profile, refresh-cert, rotate-delegation, check-revocation, revocation, schema-hash, completions |
| Daemon & fleet lifecycle | Run the resident daemon and manage signed releases across the fleet | run, heartbeat, probe, migrate, fleet-releases |
| The on-device agent | Reason locally, run missions, wield tools, coordinate with peers, and consume leased jobs | chat, do, hitl, inbox, mcp, a2a, presence, scheduled-jobs |
| Local intelligence & extraction | Serve models, run federated cognition, and extract from documents | model-serving, cognition, federated-semantics, extract, extract-entities |
| Discovery, catalog & field manuals | Scan sources at the edge, admit catalog objects, and carry standing orders | discovery-mapping, catalog, briefing |
| Governance, audit & telemetry | Prove what the device did, capture consent, and control what leaves it | audit, rewind, consent, telemetry, metering, sensor, doctor |
Related topics
- Core and Edge, one product, two runtimes, and the parity discipline that keeps them aligned.
- Deployment topology, where the Edge Agent sits, including the case where cells are deployed at the edge site.
- The cell model, the instance the Edge Agent reads from.
- Security · Identity and Security · Cryptography, the delegated identity and signing the device holds.
- Agent Platform, the agent runtime that reasons on-device.