Enrollment & identity
These commands get a device from nothing to enrolled, show what identity it holds, keep its certificate and delegation fresh, and destroy the identity cleanly at end of life. The identity and delegation model itself is described under Security · Identity.
s9 setup
Guided first-run checklist. Walks a new device through what to do, in order, enroll or run sovereign, import a model, verify, and the first commands to try.
s9 setup
Start here on a fresh host.
s9 enroll
Enroll this device against the Edge Agent Gateway. 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, the private key never leaves the device.
| Argument / flag | Description |
|---|---|
--token <TOKEN> | One-time enrollment token from the backend admin API (env S9_EDGE_ENROLL_TOKEN). Required. |
--device-name <NAME> | Override the device name sent in the request. |
--bootstrap-endpoint <URL> | Override the bootstrap gRPC endpoint from the config file. |
--access-mode <MODE> | auto, internal (default), or external: which network path to prefer. |
--reenroll | Replace an existing identity in this profile / state dir. Without it, enrolling over an already-enrolled state dir is refused so a second enrollment cannot silently clobber the first. |
s9 enroll --token "$S9_EDGE_ENROLL_TOKEN" --device-name gateway-07
s9 decommission
Destroy this device's identity, the inverse of s9 enroll. Irreversible. It
overwrites and unlinks the mTLS private key, the signing secret, the delegation
token, and every other enrolled artefact, then verifies they are gone and
writes a signed receipt outside the state directory. It exits non-zero if
anything survived.
| Flag | Description |
|---|---|
--confirm-device-id <ID> | The device id this state dir holds, typed back. Required. |
--scope <SCOPE> | identity (default; preserves audit journals) or state-dir (everything, journals included). |
--receipt <PATH> | Where to write the signed destruction receipt. Must be outside the state directory. |
--dry-run | Print the destruction plan and exit without destroying anything. |
s9 decommission --confirm-device-id device:abc123 --receipt /media/usb/decom-receipt.json
s9 identity
Show the device identity, fingerprint, and enrolled state. --json emits the
machine-readable form.
s9 identity --json
s9 status
Show Edge Agent version, active profile, and known endpoints. Add
--show-schema-hash to also print the vendored wire-schema hash.
s9 status
s9 profile
List and inspect named profiles (see Profiles).
| Subcommand | Description |
|---|---|
list | List every profile (the default plus each named one) and its binding. |
show [NAME] | Show one profile's root, config, and binding in full. Defaults to the active profile. |
s9 profile list
s9 profile show gateway-07
s9 refresh-cert
Refresh the device certificate: generate a new key and CSR, and obtain a new
certificate from the backend. --operational-endpoint <URL> overrides the
endpoint from the config file.
s9 refresh-cert
s9 rotate-delegation
Rotate the delegation token, swap it for a fresh one without changing the certificate.
| Flag | Description |
|---|---|
--scope-name <NAME> | Override the scope name for the new delegation (default: reuse current). |
--ttl-seconds <N> | Requested TTL for the new delegation (default: backend default). |
--operational-endpoint <URL> | Override the operational gRPC endpoint. |
s9 rotate-delegation --ttl-seconds 86400
s9 check-revocation
Check whether the device's delegation has been revoked, over the operational
endpoint. --operational-endpoint <URL> overrides the config value.
s9 check-revocation
s9 revocation
Certificate revocation posture, and the air-gapped delivery route for it. The
apply-bundle subcommand verifies a signed revocation bundle off removable media
with no network.
| Subcommand | Description | Key flags |
|---|---|---|
status | Show this device's revocation posture and what it holds. | |
apply-bundle | Verify and apply a signed revocation bundle from removable media. | --bundle-path <PATH> (required), --dry-run |
# Air-gapped: apply a couriered revocation bundle
s9 revocation apply-bundle --bundle-path /media/usb/revocation.bundle
s9 schema-hash
Print the vendored wire-schema hash, useful when diagnosing a version-skew rejection between a device and a peer.
s9 schema-hash
s9 completions
Generate a shell completion script for bash, zsh, fish, powershell, or
elvish.
s9 completions bash | sudo tee /etc/bash_completion.d/s9
Related topics
- Security · Identity, the entity and delegation model behind enrollment.
- Security · Cryptography, the certificate and signing systems.
- Daemon & fleet lifecycle, running the device once it is enrolled.