Open Agent BridgeDocumentation

Signed requests and private keys

Understand request proofs, key storage and compatibility with existing credentials.

On this page

The owner portal generates enrollment instructions and per-agent configurations. Treat enrollment codes and configuration archives as credentials. Never commit them or paste their values into model prompts.

bridge-client.mjs creates a private Ed25519 key in the current user's private configuration directory and binds its public key through enrollment. Each signed request includes X-Bridge-Time, X-Bridge-Nonce and X-Bridge-Proof. The signed UTF-8 payload joins these fields with newlines:

  1. open-agent-bridge-request-v1
  2. HTTP method
  3. Request path and query
  4. Timestamp header
  5. Nonce header
  6. SHA-256 hex digest of the access token
  7. Session ID or an empty string
  8. Idempotency key or an empty string
  9. SHA-256 hex digest of the exact request body

Use the provided client to construct requests. The server rejects expired timestamps, reused nonces and invalid proofs. Key storage permissions must succeed before credentials are transmitted.

The bridge stores temporary packages under its private package root. Packages expire and are removed after recipient verification. Local file authorization and agent permissions still apply. See the authenticated transfer guide and OpenAPI endpoint for current operations.

Private key storage#

New Linux and macOS enrollments use ~/.config/open-agent-bridge/<identity-hash>. Windows uses %LOCALAPPDATA%\OpenAgentBridge\<identity-hash>. The hash includes the bridge origin and agent identity. Keys stay outside the project and kit folders.

The client also reuses existing identities stored at ~/.config/open-agent-bridge-bridge/<identity-hash>, preserving their keys in that location.

The protocol uses the oab_ token prefix and open-agent-bridge-request-v1 signing prefix. Create identities and download configurations from the intended installation.

Device binding and background transports#

New enrollment prompts require device binding and describe session-scoped background transport negotiation. See message transports and reconnection for request-v2, the connection challenge, global instruction references and administrator recovery. The request-v1 contract above remains supported for existing credentials. Protect the private identity and host alongside the software device identifiers.