| … | … | @@ -0,0 +1,141 @@ |
| 1 | # Keet Identity and Device Linking |
| 2 | |
| 3 | This document explains how to set up a real identity for the Keet bot and link multiple devices to the same identity. |
| 4 | |
| 5 | ## Identity Structure |
| 6 | |
| 7 | A Keet identity consists of two main components: |
| 8 | |
| 9 | 1. The main identity file (`identity.json`) in the storage root directory |
| 10 | 2. A simplified identity file (`identity.json`) in the database directory |
| 11 | |
| 12 | Both files need to be properly configured for the identity to be recognized as a real identity by the Keet client. |
| 13 | |
| 14 | ### Main Identity File |
| 15 | |
| 16 | The main identity file (`test-keet-storage/identity.json`) has the following structure: |
| 17 | |
| 18 | ```json |
| 19 | { |
| 20 | "anonymous": false, |
| 21 | "memberId": "s3hngfgxfgs9db17jxynwxpdyieq8sesoo91wnd5mycp56t6o5ay", |
| 22 | "timestamp": 1745254354218, |
| 23 | "displayName": "KeetBot", |
| 24 | "avatar": null, |
| 25 | "devices": [ |
| 26 | { |
| 27 | "deviceId": "s3hngfgxfgs9db17jxynwxpdyieq8sesoo91wnd5mycp56t6o5ay", |
| 28 | "isMobile": false, |
| 29 | "name": null, |
| 30 | "confirmed": true |
| 31 | }, |
| 32 | { |
| 33 | "deviceId": "device-1745260473843", |
| 34 | "isMobile": true, |
| 35 | "name": "Mobile Device", |
| 36 | "confirmed": true |
| 37 | } |
| 38 | ], |
| 39 | "local": { |
| 40 | "deviceId": "s3hngfgxfgs9db17jxynwxpdyieq8sesoo91wnd5mycp56t6o5ay" |
| 41 | } |
| 42 | } |
| 43 | ``` |
| 44 | |
| 45 | The key fields are: |
| 46 | - `anonymous`: Must be set to `false` for a real identity |
| 47 | - `memberId`: A unique identifier for the member (shared across all devices) |
| 48 | - `devices`: An array of devices linked to this identity |
| 49 | - `local.deviceId`: The device ID of the current device |
| 50 | |
| 51 | ### Database Identity File |
| 52 | |
| 53 | The database identity file (`test-keet-storage/db/identity.json`) has a simpler structure: |
| 54 | |
| 55 | ```json |
| 56 | { |
| 57 | "id": "s3hngfgxfgs9db17jxynwxpdyieq8sesoo91wnd5mycp56t6o5ay", |
| 58 | "name": "KeetBot", |
| 59 | "anonymous": false |
| 60 | } |
| 61 | ``` |
| 62 | |
| 63 | The key fields are: |
| 64 | - `id`: Should match the `memberId` in the main identity file |
| 65 | - `name`: Should match the `displayName` in the main identity file |
| 66 | - `anonymous`: Must be set to `false` for a real identity |
| 67 | |
| 68 | ## Setting Up a Real Identity |
| 69 | |
| 70 | To set up a real identity for the Keet bot, you can use the `update_identity.js` script: |
| 71 | |
| 72 | ```bash |
| 73 | node tests/update_identity.js [--storage=path/to/storage] [--name=display-name] |
| 74 | ``` |
| 75 | |
| 76 | This script will: |
| 77 | 1. Read the existing identity file |
| 78 | 2. Set `anonymous` to `false` |
| 79 | 3. Update the display name if provided |
| 80 | 4. Write the updated identity back to the file |
| 81 | |
| 82 | ## Device Linking |
| 83 | |
| 84 | To link multiple devices to the same identity, you can use the `link_device.js` script: |
| 85 | |
| 86 | ```bash |
| 87 | cd second-device-keet && node link_device.js |
| 88 | ``` |
| 89 | |
| 90 | This script will: |
| 91 | 1. Read the identity from the first device |
| 92 | 2. Create a new device ID |
| 93 | 3. Create a new identity for the second device that links to the first device's identity |
| 94 | 4. Update the first device's identity to include the new device |
| 95 | |
| 96 | ### Confirming a Device |
| 97 | |
| 98 | After linking a device, you need to confirm it using the `keet_cmd.js` script: |
| 99 | |
| 100 | ```bash |
| 101 | node tests/keet_cmd.js --confirm-device=device-id --storage=path/to/storage |
| 102 | ``` |
| 103 | |
| 104 | Alternatively, you can manually update the identity files to set the `confirmed` status to `true` for the device. |
| 105 | |
| 106 | ## Running the Keet Bot |
| 107 | |
| 108 | ### Primary Device |
| 109 | |
| 110 | To run the Keet bot on the primary device, use the `run_keet_bot.sh` script: |
| 111 | |
| 112 | ```bash |
| 113 | ./run_keet_bot.sh <room-key> [model] |
| 114 | ``` |
| 115 | |
| 116 | Example: |
| 117 | ```bash |
| 118 | ./run_keet_bot.sh pear://keet/abcdef123456 llama3.1:latest |
| 119 | ``` |
| 120 | |
| 121 | ### Secondary Device |
| 122 | |
| 123 | To run the Keet bot on the secondary device, use the `run_second_device.sh` script: |
| 124 | |
| 125 | ```bash |
| 126 | ./run_second_device.sh <room-key> [model] |
| 127 | ``` |
| 128 | |
| 129 | Example: |
| 130 | ```bash |
| 131 | ./run_second_device.sh pear://keet/abcdef123456 llama3.1:latest |
| 132 | ``` |
| 133 | |
| 134 | ## Troubleshooting |
| 135 | |
| 136 | If the Keet client doesn't recognize the bot as having a real identity, check the following: |
| 137 | |
| 138 | 1. Make sure both identity files (`identity.json` in the storage root and in the `db` directory) have `anonymous` set to `false` |
| 139 | 2. Make sure the `id` in the database identity file matches the `memberId` in the main identity file |
| 140 | 3. Make sure the `name` in the database identity file matches the `displayName` in the main identity file |
| 141 | 4. Check if the Keet client is using a different storage location |