Install Pepper

This page takes you from a fresh Mac to your first brief, the rundown Pepper sends you three times a day with your open items. Do it on a laptop first if you like; the steps are the same on the always-on Mac that will run Pepper. Set that Mac up with Setting up the Mac that runs Pepper as well.

There are two ways through it. The short way is one line in Terminal and then the guided setup. By hand is the same steps one at a time, for when you want to see each one or do one over.

• A Mac with Apple Silicon. The base Mac mini is enough; see which Mac
• An account with Beeper, the app that brings your chat apps (Telegram, Signal, ...) together so Pepper can read the chats you connect
• A Telegram account, for Pepper's own chat with you
• An Anthropic API key, which is how Pepper reaches Claude, the model it runs on. Other models are planned, with no code yet.

Open Terminal (Spotlight, type Terminal) and paste this one line:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/rdyplayerB/pepper/main/scripts/bootstrap.sh)"

It installs the tools Pepper needs (Homebrew with Apple's command line tools, nvm and Node 24) and Pepper's code in ~/pepper, then starts the guided setup (npm run setup) in the same window. Run it again and it skips what is installed, pulls the latest code and goes through setup again, so run npm run backup first if Pepper is already running. Setup then goes through seven parts, from connecting Beeper to starting Pepper, and checks that each one worked before saving:

Tokens and keys are hidden as you type and go straight into .env, Pepper's settings file, which only you can read; your Mac password goes to macOS and is not saved. Your saved answers are kept if setup stops halfway. To do one part again later: npm run setup beeper, npm run setup telegram and so on. npm run setup -- --help lists them.

Keep the new bot's username to yourself until setup finishes: the first person to message it becomes the owner, and setup prints the id it chose. The first digest sends the text of those conversations to Anthropic, as every brief does.

Commands on these pages run from the Pepper folder. In a new Terminal window, start with cd ~/pepper.

To see the whole thing before you start, watch the setup replay: the one line, then the seven parts, with an invented person's chats.

If you're a tester, unpack the copy you were given, open Terminal in that folder and run scripts/bootstrap.sh from there; it does the same.

Pepper itself asks macOS for no permissions, apart from your Mac password in the Power part. These prompts come from the tools you install on the way:

• Your Mac password, when the Homebrew installer starts. Nothing shows as you type; press Return. You may never see a separate dialog for Apple's command line tools.
• "Beeper" is an app downloaded from the Internet. Are you sure you want to open it?, the first time you open Beeper. Click Open.
• Allow "Beeper" to find devices on local networks?, soon after. Click Allow.

The guides for the optional parts cover any extra prompts.

Every command below goes in Terminal.

1. Homebrew and Apple's command line tools: paste the one-line installer from brew.sh. It installs the command line tools (git and friends) on the way and takes a few minutes. When it ends with Next steps, run the two lines it prints. They add Homebrew to your ~/.zprofile; Pepper's background jobs need that line to find ffmpeg and uv later. Check: brew --version prints a version.

2. Node 24 via nvm. Install nvm with its one-line script. It adds a few lines to your ~/.zshrc, which only a new shell reads, so open a new Terminal tab (or run source ~/.zshrc), then:

   Copy Text

   nvm install 24 && nvm alias default 24

   Check: node -v starts with v24. (The repo has an .nvmrc, and the background job that starts Pepper at login finds Node through nvm.)

3. Get Pepper: git clone https://github.com/rdyplayerB/pepper.git ~/pepper && cd ~/pepper && npm install. Check: it finishes without an error; a note that fsevents has an install script is normal.

4. Beeper Desktop: brew install --cask beeper, then open Beeper, sign in, and add your chat apps. Prefer On-Device Connections when offered, so the connections to your chat apps run on your Mac and not in Beeper's cloud. If your Beeper account already had chat apps, those connections run in Beeper's cloud. To look for an on-device option for one, open Settings -> Accounts and pick that network.

   Then Settings -> Integrations -> Beeper Desktop API -> turn Allow connections on -> Approved connections -> + -> create a token named Pepper:

   • Allow sensitive actions OFF. That makes the token read-only at Beeper's end, so Pepper can't send or change anything even by mistake.
   • Expires In: Never. It starts at 30 days, and when the token expires Pepper stops reading your messages. npm run doctor warns two weeks before a token runs out.

   Beeper has to stay open for Pepper to read anything, so leave it running.

5. Telegram bot: message @BotFather -> /newbot -> copy the token. Open the chat with your new bot and press Start; a Telegram bot can't message you until you do. Message @userinfobot to get your numeric user ID. Only that ID can talk to the bot. (npm run setup telegram handles this step.)

6. Anthropic API key: platform.claude.com -> API keys. A second key from another account is optional; Pepper switches to it when the first runs out of credit or is rate limited.

7. Settings file: cp .env.example .env, open it (nano .env, or open -e .env for TextEdit) and fill it in with the tokens, ID and keys from the steps above, then chmod 600 .env so only you can read it.

8. First run:

   Copy Text

   npm run ingest -- --full     # first pull: seven days of messages for each new account, all chats
   npm run status
   npm run digest -- 12         # prints a 12-hour conversation digest; add --send to push it to Telegram

   Each pull also looks 14 days back in up to 10 unread chats that have nothing stored yet. The digest only summarises recent conversations, and sends their text to Anthropic, as every brief does. Once Pepper is running, send /brief to your bot to preview the regular brief, with your open items.

9. The Mac's power settings: on the Mac that will run Pepper, do the power and login steps now, or the next check reports host as not ok.

10. Check: npm run doctor checks every connection without changing anything in them and spends none of your Anthropic credit. Every line should say ok, or off for a part you haven't turned on.

11. Keep it running: launchd/install.sh starts Pepper at login and restarts it if it stops. (For a quick try, npm run bot in a terminal works too.)

These extras are each off until you set them up, except that spoken replies use the Mac's built-in voice until you install Pepper's. npm run doctor shows a line for each; routines have npm run routines status instead.

After changing .env, restart Pepper: launchctl kickstart -k gui/$(id -u)/com.pepper.agent.

The background service that keeps Pepper running uses built JavaScript from dist/, which takes less memory and starts faster than running the source. scripts/start.sh rebuilds it whenever the code has changed, so after a git pull, run npm install && npm run check, then restart. If a build ever fails, Pepper starts from the source instead and says so in data/pepper.err.log; npm run build shows why.

npm run backup copies the database, the data folder and .env to ~/pepper-backups, and is safe while Pepper is running. Take one before any change you are unsure of. npm run backup -- list shows what you have.

npm run restore -- <name> stops Pepper, moves the current data folder aside (nothing is deleted), and puts the backup back. It leaves .env alone (a copy is in the backup's env file), and it refuses to run while a copy of Pepper you started by hand is still running, so stop that first. It tells you which version of the code to use with the backup. Run launchd/install.sh to start Pepper again.

Backups stay on this Mac, readable only by you, and are not encrypted. Any older than 30 days are deleted while Pepper is running (it checks every hour), or when you take a new backup, so anything /forget (the Telegram command that deletes a person from Pepper) removes is gone from backups within 30 days. Pepper deletes nothing while it is stopped. Keep a copy elsewhere if you want to keep them longer.

Everything Pepper knows lives in the data folder (PEPPER_DATA_DIR, default ./data), including the list of phone callers, the passphrase and the sign-ins in data/connections/. Your keys live in .env. The phone bridge's own passwords are in ~/pepper-phone, and routines kept outside the data folder with PEPPER_ROUTINES_DIR move separately.

1. Stop Pepper on the old Mac first. Only one Pepper can read a Telegram bot at a time; two running copies interfere with each other. On the old Mac:

   Copy Text

   launchctl bootout gui/$(id -u)/com.pepper.agent
   rm ~/Library/LaunchAgents/com.pepper.agent.plist   # or it starts again at the next login

   Routines have schedules of their own there: npm run routines -- uninstall <name> for each, and install them again on the new Mac.
2. On the new Mac, do steps 1 to 3 of By hand: Homebrew, Node and the code.
3. Copy the data folder and .env from the old Mac into the new Pepper folder. If .env sets PEPPER_DATA_DIR or PEPPER_ROUTINES_DIR to a full path, point them at the new place. If it turns on Pepper's voice or semantic search, install those first (step 4), or setup can't start Pepper; npm run setup service finishes it later. Then run npm run setup. It keeps what still works (the bot, your owner ID, the Anthropic keys), asks for a new Beeper token, since a token only works with Beeper on the Mac where it was made, sets the power settings, runs doctor and starts Pepper.
4. Redo the optional parts you use. Their downloads and the phone pairing have to be done again on each Mac.

Never start Pepper again on the old Mac with the same data folder: some sign-ins in data/connections/ stop working when two Macs use them (moving connections).