Skip to content
OpenBuddiesOpenBuddies Docs

Set up OpenBuddies for your family

In this tutorial you’ll install OpenBuddies on a computer at home, set up your household, and pair your child’s phone. By the end, your child will have hatched their first buddy and you’ll be reading their first chat on your parent page.

It takes about 15 minutes.

What you’ll need

Section titled “What you’ll need”
  • A computer that stays at home, running macOS or Linux. An old laptop is fine. Your child never needs to touch it.
  • An AI key from Anthropic or OpenAI, which OpenBuddies is tuned for, or another provider such as Google or OpenRouter. You pay them for what your family uses.
  • Your child’s phone, tablet or laptop, on the same Wi-Fi as the computer.

Install OpenBuddies

Section titled “Install OpenBuddies”

  1. On the home computer, open Terminal (on a Mac, press Cmd+Space and type “Terminal”).

  2. Paste this and press Enter:

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/boyney123/openbuddies/main/install.sh | bash

    It installs OpenBuddies in a folder of its own (~/.openbuddies), along with Node.js if the computer needs it, then starts the setup below. Nothing needs your computer password. Later, openbuddies update moves you to the newest version.

    Already use Node.js 22 or newer? You can install with npm install -g openbuddies instead, then run openbuddies init.

Set up your household

Section titled “Set up your household”

  1. The installer starts the setup for you. (If you installed with npm, or closed it, run openbuddies init.)

  2. Tell it about you: your name, what your child calls you (say, “Dad”), and a parent PIN of 4 to 8 digits. The PIN protects your parent page.

  3. Choose your AI provider (Anthropic or OpenAI are recommended; Another provider lists the rest), keep the suggested models unless you know you want others, and paste your AI key. OpenBuddies checks the key works before going on. It’s saved in the household folder and never leaves this computer.

  4. Add your child: their first name, age and school year, and how much help OpenBuddies should give them:

    • Strict: never gives homework answers.
    • Balanced: shows the answer after real effort.
    • Relaxed: explains freely.

    Pick Strict if you’re not sure. You can change it any time. Add more children if you have them.

  5. Say yes to starting OpenBuddies automatically when the computer starts.

You’ve now got a household folder, ~/openbuddies: everything OpenBuddies knows about your family lives there. Copy it to back everything up. (The program itself is in ~/.openbuddies, which you never need to open. To keep the household somewhere else, set up with openbuddies init --home <folder>.)

Start it and pair your child’s phone

Section titled “Start it and pair your child’s phone”

  1. When the setup finishes, it starts OpenBuddies for you: your parent page opens in the browser, and the terminal shows a QR code for each child. (Any time later, openbuddies start does the same.)

  2. On your child’s phone, open the camera and scan their QR code. The code works once and expires in 10 minutes. If it runs out, make a new one with openbuddies pair <child>.

  3. Hand the phone over. Your child hatches their first buddy: they give it a name and a colour, and can say what it’s like (“a funny pirate”) and what it’s best at.

  4. Let them say hello and ask their buddy something.

Read the chat

Section titled “Read the chat”

Go back to your parent page, enter your PIN, and open Sessions. You’ll see the chat your child just had, every message, with notes on what the buddy decided at each turn. To find your way around, see Find your way around your parent page and Read your child’s chats.

That’s it: your family is set up.

Next steps

Section titled “Next steps”