Skip to content

Bot Setup and the Signal Account

How to configure the Signal bot, keep its Signal account registered, and keep both backed up.

The tooling lives in selfhost/messaging-apps/signal-messenger/setup/. In the repo, setup/README.md is the reference and setup/MAINTENANCE.md is the upkeep guide.

Terminal window
cd selfhost/messaging-apps/signal-messenger
./deploy.sh setup

This opens the start screen. It shows, at a glance:

  • Signal account: mode (primary or linked), number, registration and PIN.
  • The bot: whether it’s running.
  • Configuration: errors, warnings and features.
  • Backup: when the account backup last ran.

It also gives the most useful next step and a menu:

Signal ● primary on +1… · registered · PIN set
Bot ● running · up 3 hours, healthy
Config ● no errors · no warnings · 20/20 features on
Backup ● account backup 2 h ago · pushed off-site nightly
1 Open the web portal 4 Signal account
2 Guided setup 5 Health check (doctor)
3 Ask the AI assistant 6 Apply config to the bot

./deploy.sh setup … works on the bot host’s .env over SSH. Run on the host itself, node setup/cli.mjs … edits the local one.

WayCommandBest for
Web portal./deploy.sh setup portalSeeing everything at once. Opens a local page (127.0.0.1 only, one-time token) with forms, features, health check and Signal account.
Terminal wizard./deploy.sh setup wizardGuided, step by step. Asks only for what each chosen feature needs.
AI assistant./deploy.sh setup agentBeing walked through it. Uses Claude Code when installed, or a built-in chat. It never sees secret values, and it proposes changes for you to approve.

How changes are handled:

  • Same rules everywhere: all three use the same settings catalog and validation.
  • Saving: keeps a backup of the previous .env (the newest 30 are kept).
  • Applying: Apply (or Save & apply in the portal) recreates the bot container. A plain restart is not enough, because env_file is read when the container is created. It reports success only once the bot is running again.

Secrets: they are never displayed, sent to the AI, or written to logs. In the terminal, use setup set-secret KEY; it prompts without echoing.

CommandWhat it does
setup statusFeatures on/off and configuration problems
setup doctorEvery health and maintenance check, with fixes (--live also tests each service and key)
setup describe KEYWhat a setting means and where to get it
setup set KEY=VALUE / set-secret KEY / generate KEYChange settings (validated, backed up)
setup applyRecreate the bot with the saved .env
setup signalSignal registration, device and bot health
setup pinSet the registration-lock PIN (--remove to remove it)
setup devicesDevices linked to the bot’s account
setup primaryRegister the bot as the primary device, or move it to a new number (--dry-run to rehearse)
setup captchaOpen Signal’s captcha page through the bot host

The bot holds its number in one of two ways:

  • Primary device: the bot owns the number itself, with no phone involved. IrregularChat’s bot has run this way since 2026-10-11.
  • Linked device: the bot is a secondary device of a phone, like Signal Desktop. If the phone removes it, or Signal drops it, the bot goes silent until someone relinks it with that phone (./deploy.sh link).

Both keep the same account ID. Signal keeps the ID when a number is re-registered or changed, so groups and admin roles carry over.

Registering, or re-registering, the number

Section titled “Registering, or re-registering, the number”

./deploy.sh setup primary (or the portal’s Signal account page) walks through it:

  1. Confirm, and paste a captcha in the same step. Signal almost always asks for one.
  2. Solve the captcha from the bot host’s IP. A captcha solved on another network is refused with a 403. Setup checks this and offers to open the captcha page in a separate browser that goes out through the host. After Copy Link, the terminal picks it up from the clipboard; the portal has a Paste button.
  3. Enter the SMS code sent to the number. Add the Signal PIN only if the number has registration lock.
  4. Set a registration-lock PIN (recommended).

What setup does around the steps:

  • Before: stops the bot, pauses the host monitor and backs up the account.
  • During: clears stuck verification sessions and sets aside a stale account key. It always shows signal-cli’s own error message.
  • After: checks that the account ID and profile survived, backs up the new keys, and starts the bot again.
  • Interrupted: a run that stops partway can be resumed.
  • One at a time: only one run can hold the bot.

Moving to a new number (setup primary → “move the bot to a new number”):

  • The account ID, groups and admin roles stay.
  • It needs a code sent to the new number.
  • A PIN alone can never register or change a number.

Without a PIN, anyone who gets control of the number (a SIM swap, or a lapsed number) can register it and take over the bot. Set one with ./deploy.sh setup pin. It goes through the running bot, with no downtime. Keep it in the password manager. The lock lapses after 7 days of inactivity, which an always-on bot never reaches.

Run ./deploy.sh signal-status or ./deploy.sh setup doctor. The bot also reports signal_account in /health, and posts a “relink” or “re-register” alert to ntfy.

ModeFix
Linked device, link revoked./deploy.sh link with the phone, or make the bot primary
Primary, registration lost./deploy.sh setup primary

./deploy.sh setup doctor checks:

  • configuration, and settings no code reads any more
  • Signal registration, PIN and linked devices
  • the signal-cli version
  • the bot and the host monitor
  • the account backup and the off-site copies
  • the weekly restore drill and the scheduled jobs
  • leftover files and disk space

For each problem it offers the fix it can make.

Scheduled on the bot host, with ntfy alerts on failure and when a job stops running:

JobWhenWhat
Account backupdailyencrypted restic snapshot of the Signal account and .env; pushed off-site nightly
Restore drillweeklyrestores the latest snapshot to a sandbox, verifies everything, deletes it
Doctorweeklythe checks above; posts any problem to ntfy

Alerts. Re-registering, changing the number, and setting or removing the PIN each post to ntfy, naming who did it. Every config save (key names only), apply and account action is written to /var/log/signal-setup.log on the host.

  • Signal account: an encrypted, deduplicated restic snapshot every night, kept for 14 days, 8 weeks and 12 months. It is pushed off-site, restored and verified weekly by the drill. The backup password must be in the password manager: the off-site copies are unreadable without it.
  • Database: the postgres-backup container dumps it daily, keeping 7 days, 4 weeks and 6 months, and the dumps go off-site too.
  • Restore: signal-data-restore.sh restores either to a sandbox (the default) or --live, and verifies every file, the databases and the account store. The runbook is docs/runbooks/signal-data-backup.md.
  • Self-Hosting Guide: first-time setup
  • Deployment Guide: deploy.sh, health, backups, recovery
  • Troubleshooting
  • In the repo:
    • setup/README.md
    • setup/MAINTENANCE.md
    • docs/runbooks/signal-primary.md
    • docs/runbooks/signal-relink.md
    • docs/runbooks/signal-data-backup.md

Recent changes

  1. docs: Signal bot setup, Signal account, backups and maintenance; v5.33.0 notes @sac