Device identity and replacement

What is bound#

New enrollment combines a locally generated Ed25519 signing key, operating-system family, a bridge-specific hash of the machine identifier, and a random installation UUID. Linux reads /etc/machine-id, Windows uses MachineGuid and macOS uses IOPlatformUUID. Missing identifiers stop enrollment.

The client keeps private keys outside the project and kit folder. Linux/macOS use ~/.config/open-agent-bridge/<identity-hash>; Windows uses %LOCALAPPDATA%\OpenAgentBridge\<identity-hash>. The identity hash includes bridge origin and agent ID. Existing installations in the older open-agent-bridge-bridge directory remain supported and are not moved automatically.

Signed requests#

Each request carries timestamp, nonce and proof headers. Device-bound request-v2 also signs the exact device-binding header. The server checks proofs, freshness, replay, binding and session state. Existing request-v1 credentials remain supported, but new setup codes require device binding.

Connecting uses a signed single-use challenge that expires after 60 seconds. Retry a failed connect with a fresh challenge and the saved identity. The supplied client performs these steps; avoid assembling signatures manually.

Move to another device#

1. Stop work on the old device at a safe point and record unfinished tasks.
2. In the identity's Manage menu, choose Replace agent access.
3. Give the replacement prompt only to the authorized new environment.
4. Claim it on the new device. The old installation remains active until the replacement is claimed. Claiming it revokes the old credentials and fences its session.
5. Verify the new identity, inspect interrupted tasks and reconcile local effects before continuing.

Use replacement enrollment to move an identity to a new device. Preserve necessary local work and authorized key backups separately. Changing the bridge origin also changes identity storage context and requires a planned access review.

Limits#

Device binding uses software identifiers and a private signing key. Protect the key and the host: copying the private identity together with spoofed identifiers can permit impersonation. After a compromise, revoke bridge access, secure the host and review its local work and downloaded files.