Signal Setup Guide
Enables your agent to send and receive end-to-end encrypted messages via Signal.
Prerequisites
- A Signal account with a registered phone number
- signal-cli installed on your computer (used for the initial linking process)
Step 1: Install signal-cli
signal-cli is a command-line tool for interacting with Signal. You'll use it to link a device and export the account data for Carapace.
macOS (Homebrew):
brew install signal-cli
Linux: Download the latest release from github.com/AsamK/signal-cli/releases and follow the installation instructions.
Step 2: Link as a Secondary Device
Link signal-cli as a secondary device on your Signal account:
signal-cli link -n "Carapace Agent"
This will output a tsdevice: URI. Convert it to a QR code (or use qrencode) and scan it with Signal on your phone:
- Open Signal on your phone
- Go to Settings > Linked Devices
- Tap Link New Device
- Scan the QR code
Step 3: Export Account Data
After linking, export the account data that Carapace needs:
signal-cli -a +1234567890 jsonRpc
The account data is stored in ~/.local/share/signal-cli/data/ (Linux) or ~/Library/Application Support/signal-cli/data/ (macOS).
Step 4: Connect in Carapace
- Go to Dashboard > Connections
- Find Signal and click Connect
- Enter your phone number (with country code, e.g.,
+1234567890) - Paste the account data
- Click Save Credentials
Credential Fields Reference
| Field | Required | Format | Description |
|---|---|---|---|
phone_number | Yes | E.164 format (+1234567890) | Phone number registered with Signal |
account_data | Yes | JSON | Linked device account data from signal-cli |
Gotchas
Phone number format: Always include the country code with a + prefix (E.164 format). For example, a US number should be +12025551234, not 2025551234.
Secondary device only: signal-cli must be linked as a secondary device — it cannot take over your primary Signal registration. Your phone remains the primary device.
signal-cli version: Ensure you're using a recent version of signal-cli. Older versions may have compatibility issues with the current Signal protocol.
Re-linking: If the linked device is removed from your Signal account (via Settings > Linked Devices), you'll need to repeat the linking process and update the credentials in Carapace.