CovenDocs
CLI ReferenceMachineDevices

Devices

Reference for coven device list, inspect, rename, suspend, resume, revoke, grant reissue, and rotate.

6 min read

coven device manages devices already enrolled with this COVEN_HOME and the grant each one holds. Enrollment can use the mobile gateway pairing flow (coven memory mobile pair) or the owner-reviewed trusted-device introduction flow below.

coven device list                    # id, status, grant status, and name (--json available)
coven device inspect <device>        # one device and its grant (--json available)
coven device rename <device> <name>
coven device suspend <device>
coven device resume <device>
coven device revoke <device> --reason lost
coven device grant reissue <device> --scope memory-read --expires-in-days 30
coven device rotate <old-device> <replacement-device>

<device> is the device's exact id or exact display name. A name shared by more than one device fails; use the id instead.

Suspend or revoke

In the CLI release that includes OpenCoven/coven#1139, suspend takes a device offline without ending its enrollment. Its grant and authorization key stay in place, so resume restores access without pairing again. Requests from a suspended device fail with device_suspended. Resuming grants nothing new: every request is still checked against the grant's scopes, assurance floor, and expiry, so a grant that expired or was tightened during the suspension stays unusable.

revoke is permanent. It ends the device's grant and authorization key, and the device has to pair again to regain access. A revoked device cannot be suspended or resumed. revoke does not ask for confirmation, so check the id with coven device list first. --reason records why in the device audit trail: ordinary (default), lost, suspected-compromise, or retired.

Reissue a grant

coven device grant reissue replaces the device's grant with exactly the policy you pass. Options you omit take their defaults, not the previous grant's values.

OptionValues
--scope (required)One or more of memory-read, session-metadata-read, conversation-read, message-send, tool-invocation-request, tool-execution-approve, secrets-read, familiar-memory-admin, device-admin, identity-admin, memory-export, identity-export. Repeat the flag or comma-separate values; duplicates are rejected.
--expires-in-days (required)Whole days from now, 1 to 365.
--minimum-assurancepossession (default), recent-user-verification, fresh-user-verification, fresh-biometric, or step-up.
--require-fresh-user-verification-forScopes that require fresh user verification.
--direct-onlyRestrict the grant to direct authenticated transport.

Each reissue creates a new grant id and advances the device's revocation epoch, which invalidates the device's outstanding sessions.

Replace a device

Pair the replacement device first. coven device rotate <old-device> <replacement-device> then revokes the old device and moves its grant policy to the replacement under a new grant id.

Trusted-device introduction policy

coven device owner-root generate --out <path> creates the offline owner-root credential. Keep it offline and private. coven device introduction-policy show --json inspects the installed policy. introduction-policy install registers the first owner-root-backed policy; replace signs a replacement and may deliberately downgrade it. In builds containing threshold introduction, both changes require --root-key, eligible --introducer device ids, an explicit --required-approvals threshold, allowed --scope values, and review of the grant lifetime, assurance, and step-up age. There is no default approval threshold: it must be at least one, no more than the eligible introducer count, and at most sixteen. Read coven device introduction-policy install --help or replace --help for the complete current flags and defaults. The printed review requires typed confirmation unless the owner explicitly chooses --yes.

coven device introduce --request <envelope.json> submits a reviewed enrollment request over the owner-local socket. Every named trusted-device approver must approve the same exact request on its own device under the installed policy; possession of the request or owner-local transport alone is not approval. Review the displayed request before confirming. Do not copy an owner-root private credential into a request, client, or introduction envelope.

Threshold approval and optional assurance attributes

These source-build capabilities may be absent from an installed release. A version-1 introduction names one introducer and is valid only for a one-approval policy. Version 2 binds distinct named approvers and their exact grants/epochs to one request; the destination also proves possession. A policy change, revocation or suspension during approval cannot be bypassed by an earlier approval.

coven device passkey register --registration <file> --assertion <file> --root-key <offline-key> registers an optional recovery factor after review and owner-root signing. coven device passkey list --json reports registered factors and whether each is synced. A passkey is not a device identity and can fill at most one approval of a threshold introduction that still requires a trusted device; it never enrolls a device by itself.

coven device attestation show --json inspects optional trust configuration. The add-android-root, add-official-android-app, add-apple-root, add-official-apple-app, and clear subcommands manage owner-supplied anchors and explicitly named official apps; inspect each subcommand's help before changing trust. No vendor root is compiled in and Coven does not contact Apple for verification. Device inspection exposes unattested_device, verified_hardware_key, or verified_official_app as an assurance attribute, never identity or authority. The introduction policy's default --minimum-attestation unattested-device keeps self-built/unattested clients usable; a stricter floor is an explicit policy decision, and lowering it is a reviewed policy broadening.

Access recovery and owner-root rotation

coven device recover --request <signed-envelope.json> --root-key <offline-key> is a separate, audited access-recovery operation when no trusted introducer is available. The recovering device proves possession, and the owner-root approval binds the current installed policy head and exact requested grant. The CLI displays the signed fields and requires typed recover confirmation unless the owner explicitly selects --yes. Recovery enrolls that one device within the current policy's allowed scopes and grant-lifetime bound; it does not rotate the owner root, revoke other devices, or change familiar identity.

coven device owner-root rotate --root-key <installed-offline-key> --new-root-key <new-offline-key> requires both keys to sign the same reviewed action, with typed rotate confirmation unless the owner explicitly selects --yes. The installed policy, devices, grants and familiars stay unchanged; unused approvals bound to the previous policy head become stale. Keep the new key offline and outside COVEN_HOME. A lost root cannot be rotated through this command; it requires a separate trust-domain reset rather than an implicit identity change. See the owner-policy source and access-recovery source. Local fixtures, device UX, independent review, and released-client availability remain distinct gates.

Experimental mobile authority restore

Source builds with v2 returning-device transport provide an explicit offline restore ceremony. This is distinct from coven device recover, which enrolls one device, and from relay-configuration reset. Inspect coven memory mobile restore export --help and install --help in the build you will use. Keep the selected snapshot, latest authority and destination separate, and retain a previously pinned installation fingerprint.

From an intact current installation, coven memory mobile restore export --output /private/backup-directory/authority.json --json creates a new signed authority artifact. Its parent must already be private, its destination must be outside mobile state, and an existing file is never overwritten. It preserves registry/key revocations, grant restrictions, owner-policy metadata and retained routing-generation floors. It contains private device/grant metadata, but no host private key, Noise private key or routing seed. The selected snapshot supplies the matching installation identity separately. A valid signature, digest or capture time proves neither external freshness nor that an old authentic export contains the latest revocations.

Stop the destination daemon and other Coven commands, then select the offline destination with COVEN_HOME and run coven memory mobile restore install --snapshot-home /private/selected-snapshot --authority /private/backup-directory/authority.json --installation-fingerprint <previously-pinned-base64url-fingerprint> --operation-id <stable-non-nil-uuid> --json. Supply the complete latest signed authority. The command rejects overlapping homes, a mismatched pin and known older authority. It durably fences installation before copying captured identity/listener settings, and installs latest signed registry/key/policy data rather than treating the snapshot's old authority or routing secrets as current. Policy capture includes approvals and root history; removal, older revisions and equal-revision conflicting digests are refused. Snapshot identity validation checks the actual TLS key/certificate binding. It leaves the selected snapshot unchanged and restores only mobile authority, not unrelated Coven data.

Installation advances epochs and routing generations without discarding retained floors. Keep the same operation id and exact original authority/snapshot for every retry after an uncertain result; a different operation cannot replace an incomplete installation. A fence with missing or corrupt journal state fails closed. After installation, start the daemon and complete fresh authenticated direct handover for every usable pairing; revoked pairings stay revoked. The ceremony cannot recover current revocations from an old authentic export alone. Controlled native process-loss and snapshot fixtures remain distinct from physical power-loss, Windows filesystem and physical-device acceptance.

Was this page helpful?No

Last updated on

On this page