Getting Started

Short, opinionated walk-through. For the full list of commands, architecture, and hardening details, read the README. This page is the thing to read before you run the installer.

  1. Prerequisites
  2. Before you start: read MODELS.md
  3. Install
  4. First run
  5. Troubleshooting

Prerequisites

Hardware

  • Apple Silicon Mac (M2 Pro or later recommended)
  • 24 GB+ unified memory for the dual-model stack (8B tool + 9B reasoning, ~10 GB weights loaded simultaneously)
  • macOS 14 (Sonoma) or later
  • FileVault enabled (the installer hard-requires it — all secrets at rest rely on it)
  • An external drive for backups (optional but strongly recommended)
  • A keyboard and display for the initial setup (unplug them when done — the wizard emails you connection instructions for any device)

Accounts

  • A domain name you control
  • Cloudflare account (free)
  • Resend account (free tier: 3k emails/month, shared between sent and received)
  • Telegram bot token, via @BotFather
  • Your Telegram user ID, via @userinfobot
  • Tailscale account (free for up to 3 users / 100 devices)
  • Optional: iCal URLs from iCloud / Google / M365 for read-only calendar sync

Full shopping-list table with pricing and links lives in the README’s Requirements section. Don’t front-load all the sign-ups — the wizard opens the right browser tab at the right moment, and you’ll forget which is which if you try to pre-register everything.

Before you start: read MODELS.md

yabby runs two models simultaneously: Qwen3-8B (tool calling, 86% accuracy) and Qwen3.5-9B (long-form generation). Both are from the Qwen team (Alibaba), released under Apache-2.0 — a genuine open-source license with no click-through acceptance or use restrictions.

For the dual-model rationale, licensing details, and swap instructions, see docs/MODELS.md.

Install

Boot the Mini with keyboard and monitor attached. Sign in as the user who will own the install. Paste this into Terminal:

curl -fsSL https://getyabby.com/install.sh | bash

In roughly 20 minutes it installs Xcode CLT, Homebrew, Tailscale, joins the Mini to your tailnet, flips macOS into server mode, installs the mlx-lm inference backend, and runs the full setup wizard. When the wizard finishes it emails you connection instructions — Tailscale download links, VNC address, SSH command, Telegram bot handle — for whatever device you have (iPhone, Android, Windows, macOS, Linux, Chromebook). Then you unplug the keyboard and display.

Tip: pick up a cheap dummy HDMI plug (~US$10, search that term) and leave it in the Mini’s HDMI port. Without one, macOS reduces GPU clock speeds in headless mode and slows down your AI models.

Full flow with every prompt and what it means is in the README’s Quick Start section.

First run

When the wizard finishes it prints a summary with URLs, your Telegram bot handle, and health-check commands. What to expect next:

  1. Open Telegram, find your bot, send /start.
  2. Send a test message (“what time is it?”) and wait for a reply. If you get one, the inference backend, the gateway, and the Telegram channel are all wired up correctly.
  3. The first scheduled daily post lands at 3 pm local time. Don’t panic if nothing happens the first afternoon — check the cron log with scripts/health-check.sh.
  4. Inbound mail starts flowing once your domain’s MX is pointed at Resend (the wizard prints the exact records). Until then the agent has nothing to triage.

Troubleshooting

If something doesn’t work — and something always doesn’t work the first time — file an issue. Include the output of scripts/health-check.sh and the last 50 lines of ~/Library/Logs/yabby/mlx-lm-tool.out.log.

Open an issue