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.
Start here
Section titled “Start here”cd selfhost/messaging-apps/signal-messenger./deploy.sh setupThis 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 setBot ● running · up 3 hours, healthyConfig ● no errors · no warnings · 20/20 features onBackup ● account backup 2 h ago · pushed off-site nightly
1 Open the web portal 4 Signal account2 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.
Three ways to configure
Section titled “Three ways to configure”| Way | Command | Best for |
|---|---|---|
| Web portal | ./deploy.sh setup portal | Seeing 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 wizard | Guided, step by step. Asks only for what each chosen feature needs. |
| AI assistant | ./deploy.sh setup agent | Being 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_fileis 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.
Useful commands
Section titled “Useful commands”| Command | What it does |
|---|---|
setup status | Features on/off and configuration problems |
setup doctor | Every health and maintenance check, with fixes (--live also tests each service and key) |
setup describe KEY | What a setting means and where to get it |
setup set KEY=VALUE / set-secret KEY / generate KEY | Change settings (validated, backed up) |
setup apply | Recreate the bot with the saved .env |
setup signal | Signal registration, device and bot health |
setup pin | Set the registration-lock PIN (--remove to remove it) |
setup devices | Devices linked to the bot’s account |
setup primary | Register the bot as the primary device, or move it to a new number (--dry-run to rehearse) |
setup captcha | Open Signal’s captcha page through the bot host |
The Signal account
Section titled “The Signal account”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:
- Confirm, and paste a captcha in the same step. Signal almost always asks for one.
- 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.
- Enter the SMS code sent to the number. Add the Signal PIN only if the number has registration lock.
- 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.
The registration-lock PIN
Section titled “The registration-lock PIN”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.
If the bot goes silent
Section titled “If the bot goes silent”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.
| Mode | Fix |
|---|---|
| Linked device, link revoked | ./deploy.sh link with the phone, or make the bot primary |
| Primary, registration lost | ./deploy.sh setup primary |
Health and maintenance
Section titled “Health and maintenance”./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:
| Job | When | What |
|---|---|---|
| Account backup | daily | encrypted restic snapshot of the Signal account and .env; pushed off-site nightly |
| Restore drill | weekly | restores the latest snapshot to a sandbox, verifies everything, deletes it |
| Doctor | weekly | the 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.
Backups
Section titled “Backups”- 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-backupcontainer dumps it daily, keeping 7 days, 4 weeks and 6 months, and the dumps go off-site too. - Restore:
signal-data-restore.shrestores either to a sandbox (the default) or--live, and verifies every file, the databases and the account store. The runbook isdocs/runbooks/signal-data-backup.md.
Related
Section titled “Related”- Self-Hosting Guide: first-time setup
- Deployment Guide:
deploy.sh, health, backups, recovery - Troubleshooting
- In the repo:
setup/README.mdsetup/MAINTENANCE.mddocs/runbooks/signal-primary.mddocs/runbooks/signal-relink.mddocs/runbooks/signal-data-backup.md