GenosOS connects to Signal via signal-cli, an open-source command-line interface for Signal. Unlike WhatsApp or Telegram, Signal does not offer an official bot API — signal-cli registers a device on your behalf.
Signal requires a dedicated phone number. Using your personal Signal number with signal-cli will de-authenticate the main Signal app on your phone. Get a separate number (a SIM, VoIP number, or virtual number) for your assistant.
Connect Signal
Tell your assistant you want to connect:
The agent walks you through installing signal-cli and linking a number.
Setup: link an existing account (recommended)
This path is the fastest — you link signal-cli as a second device to an existing Signal number.
Install signal-cli
macOS
Linux (native binary)
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \
https://github.com/AsamK/signal-cli/releases/latest \
| sed 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
Link as a second device
signal-cli link -n "GenosOS"
Configure GenosOS
Tell your assistant the account details:You: "The Signal account is +15551234567, signal-cli is at /usr/local/bin/signal-cli"
channels.signal.account, channels.signal.cliPath, and enables the channel. Setup: register a new number
Use this path if you have a fresh SIM or VoIP number that has never had a Signal account.
Install signal-cli
See the installation step above.
Register the number
signal-cli -a +15551234567 register
# Complete the CAPTCHA at signalcaptchas.org/registration/generate.html
# Copy the signalcaptcha:// link and use it here:
signal-cli -a +15551234567 register --captcha 'signalcaptcha://...'
Verify the SMS code
Signal sends a verification code by SMS:signal-cli -a +15551234567 verify 123456
Configure GenosOS
You: "The Signal account is +15551234567"
External daemon mode
If signal-cli starts slowly (the JVM build can take 5–15 seconds), you can run it as a persistent daemon and point GenosOS at it:
signal-cli -a +15551234567 daemon --http --http-port 8080
channels.signal.httpUrl and channels.signal.autoStart: false.
The native signal-cli binary (Linux) starts in under a second. If startup time is a problem, switch to the native build instead of the JVM build.
DM policy
Signal uses the same DM policy system as other channels:
You: "Set Signal to pairing mode"
You: "Only allow +15559876543 to message me on Signal"
| Policy | Behavior |
|---|
pairing | Unknown senders get a 6-digit code. You approve via the agent. |
allowlist | Only phone numbers you specify can message your assistant. |
open | Accept messages from anyone. |
Security
Signal is a messaging channel. The agent cannot run shell commands, execute processes, or invoke bash scripts from a Signal conversation — regardless of what the message says. This restriction is architectural.
What Signal conversations can do: read files, search memory, send messages, use web tools, query APIs.
Troubleshooting
signal-cli not found
Check the path to the binary. On macOS with Homebrew:
which signal-cli
# typically: /opt/homebrew/bin/signal-cli
autoStart is true (the default), GenosOS starts signal-cli automatically when the gateway starts. Restart the gateway. If you are using daemon mode (autoStart: false), make sure the daemon is running before starting GenosOS.
Slow startup
You are using the JVM build of signal-cli. Either switch to the native binary or increase the startup timeout: tell your assistant “Set the Signal startup timeout to 60 seconds.”
Auth error / needs re-linking
The device link has expired or been revoked. Re-run signal-cli link -n "GenosOS" and scan the QR code again with your Signal app. 