Devices and klw

KleePay's agent integration is device-based. A device is a local machine authorized to run klw — the KleePay Local Wallet — hold local signing material, and expose the MCP or HTTP interface to agents.

Device setup is usually not the first user onboarding step. A new user should complete KYC and fund Balance first. Then they can either create a card in the dashboard before connecting a device, or connect a device and let the agent create/fund the card.

Device model

• A device is represented in the dashboard under Devices. In the current frontdesk route structure, this surface is served from /dashboard/api-keys.
• The current frontdesk groups device records by device_fingerprint: one physical device should appear as one connected device.
• Pending devices appear as not connected until klw setup finishes.
• Connected devices can be managed from the Devices page.
• A device does not expire. The setup command expires.

Setup command lifecycle

The Connect device dialog gives the user two equivalent setup paths:

1. Tell an agent to read the KleePay skill and set up the device.
2. Run the OS-specific install command manually.

The setup command includes a token and is time-limited (about 30 minutes). The UI shows a countdown; if it expires before setup completes, regenerate the command from the dashboard.

Open the product surface directly: Devices.

Install URLs

Production:

https://klw.kleepay.ai/install.sh
https://klw.kleepay.ai/install.ps1
https://klw.kleepay.ai/skill.md

Staging and development builds may use:

https://klw-stag.kleepay.ai

The frontdesk resolves the base URL from NEXT_PUBLIC_KLW_BASE_URL first, then infers non-production from NEXT_PUBLIC_API_URL.

Local components

Component	Purpose
klw CLI	KleePay Local Wallet — the user and agent-facing local command.
Local signer daemon	Exposes MCP and HTTP interfaces and signs authorization operations locally.
Setup token	Binds a new local device to the user's dashboard account.
Daemon token	Local bearer token used by the HTTP API after setup.
Local keystore password	Unlocks local signing material when klw starts.
OS keychain prompt	macOS or OS-level permission prompt for storing or reading local secrets.

Recovery boundaries

Do not collapse the setup token, OS keychain prompt, and local keystore password into one concept. They fail differently:

• If the setup command expired, regenerate it in the dashboard.
• If the local daemon is not running, start or reinstall klw.
• If the local keystore password is forgotten, the practical recovery path is to reconnect the device with fresh local key material.
• If local keys and server state diverge, a clean uninstall/reinstall can be safer than trying to remove stale keys from a broken daemon state.

After recovery, validate with daemon health and a server-backed command such as listing cards.