Skip to main content

Quickstart: your first device

The Edge Agent is a small, statically linked, signed binary called s9. It runs on field devices, workstations, gateways, and tactical kit, where a full cell cannot always be reached.

It is not a thin client. A device holds its own cryptographic identity, evaluates policy locally with no round trip, reasons on a local model, keeps a hash-chained journal of everything it did, and can operate with no network at all. What it does not do is serve data: it reads from and reports to a cell.

Stand up a cell first

This page assumes you have a cell from Quickstart: your first cell. You can run a device sovereign with no cell, and Track A below does exactly that, but enrolling against a cell is what shows you the product rather than one corner of it.

Prerequisites​

  • A 64-bit Linux, macOS, or Windows host.
  • The s9 binary on your PATH.
  • For Track B only: a one-time enrollment token from your cell administrator, and network reachability to the cell's gateway.
s9 --version
s9 --help

The two tracks​

Figure: the two tracks. Both start from s9 setup. Track A runs sovereign and offline. Track B enrolls against a cell over mutual TLS to join a fleet. Either way you finish with a verifiable first action.

Table equivalent

FromRelationshipTo
Bare host with s9 on PATHruns9 setup
s9 setupoffersTrack A, sovereign and local only
s9 setupoffersTrack B, enrolled
Track Bmutual TLS enrollYour cell, for fleet, relay, and policy
Either trackconfirmed byA verifiable first action

Start here, either way​

s9 setup

s9 setup is read-only. It inspects the device and prints an ordered checklist covering identity, model, and inference readiness, with the exact next command for anything not yet satisfied. On a fresh host it reports the sovereign, local-only posture, which needs no enrollment.

Track A: run sovereign, with no cell​

The shortest path, and it needs no network at all.

Confirm the device​

These three are pure, offline, and side-effect free.

s9 status            # version, active profile, known endpoints
s9 identity --json   # device identity, fingerprint, and enrolled state
s9 doctor            # full offline diagnostic: config, identity, certs, journal

s9 doctor is the workhorse. It prints a complete health report and, with --fix, offers safe remediations. When something is wrong it names the exact command to run on this device rather than a status code to take to someone else.

Give it a model, then reason locally​

The shipped build has the on-device inference engine compiled in. What it does not ship is a model, so import a signed bundle first.

s9 model-serving import /path/to/model-bundle/   # verify and register a bundle
s9 model-serving list-models --json              # confirm it registered
s9 chat "what can you do on this device?"        # one-shot question
A minimal build links no engine

The shipped default links the sovereign inference backend, and the release build does not strip it. A build made with --no-default-features, for a sensor-class device, links no inference engine at all and falls back to a telemetry-only stub, so if s9 chat returns placeholder output you are on that build rather than missing a model.

Third-party model providers are also linked by default but are posture-gated at run time: under the sovereign or AI-off postures there is no cloud egress path, whatever is compiled in. For an air-gapped build that links no HTTP egress path at all, --no-default-features is the one-flag answer.

Track B: enroll against your cell​

Enrolling gives the device a delegated identity, relay to the fabric, and a place in a fleet. The private key never leaves the device.

Enroll​

s9 enroll --token "$S9_EDGE_ENROLL_TOKEN" --device-name gateway-07

The device generates its own keypair, sends a certificate signing request over a one-time bootstrap channel, and receives a short-lived certificate bound to a delegation token. A hardware fingerprint binds the identity to this physical device.

Enrolling over a state directory that already holds an identity is refused unless you pass --reenroll, so a second enrollment cannot silently clobber the first.

Prove reachability and identity​

s9 heartbeat            # one mutually-authenticated round trip to the cell
s9 status               # now shows the enrolled device and its endpoints
s9 check-revocation     # confirm the delegation is not revoked

A successful s9 heartbeat is your verifiable first action for an enrolled device. It is a real round trip, not a local check.

Run the daemon​

s9 run --max-heartbeats 5

--max-heartbeats exits after a set number instead of looping forever, which is what you want for a smoke test or in CI. For a permanent device, install the supervised OS service:

s9 fleet-releases service render     # preview the unit, plist, or service entry
s9 fleet-releases service install
s9 fleet-releases service status

Prove what the device did​

Whichever track you took, the record is verifiable offline. Any agent turn run with --audit writes a device-signed, hash-chained journal you can export and check.

s9 chat "summarize ./notes.txt" --attach ./notes.txt --audit
s9 audit export --sign --out ./run-record.json
s9 audit verify ./run-record.json --device-key ./device.pub.pem

--device-key is the part that matters. Without it, the signature is checked against the key the bundle carries inside itself, which proves the file is internally consistent and nothing about which device produced it. Supplying the device's enrolled public half, copied from the fleet record, turns self-attested into attributed.

None of those three commands needs a network, an account, or the cell.

What you now have​

A device with its own identity, evaluating policy locally, reasoning on a local model with no vendor egress, keeping a signed journal of what it did, and either reporting to your cell or operating entirely on its own. Suspend it, revoke its delegation, or push a zeroize command from the cell and the effect lands on the device's next request.

Next steps​