Install

From a fresh machine, setup takes about 5 minutes. The wizard walks you through every service and validates each credential as you paste it.

1. Run the wizard

# One-shot (no global install)
npx yuna-bot init

# Or install globally
npm install -g yuna-bot
yuna init

The wizard will:

  1. Ask what to call your bot (you pick — Luigi, Jarvis, Alfred, whatever).
  2. Open @BotFather in your browser and prompt for a bot token. The token is validated via getMe before the wizard continues.
  3. Ask for your Telegram user ID (via @userinfobot).
  4. Open console.anthropic.com and prompt for an API key.
  5. Open console.upstash.com and prompt for a Redis REST URL + token. Create a fresh database — don't share with any other project.
  6. Deploy the bundled server template to Vercel via vercel link + vercel deploy --prod, or scaffold it locally if you pass --manual.
  7. Hash the master secret into Redis, register the Telegram webhook, and save ~/.config/yuna/config.json.
Every answer you give the wizard is persisted to ~/.config/yuna/.init-resume.json (chmod 600) as you go. If the deploy step fails, re-run yuna init and the wizard will offer to resume — no re-entering secrets.

2. Prerequisites

  • Node 18+ (20+ recommended for Vercel CLI).
  • Vercel CLI installed and logged in. npm i -g vercel then vercel login. The wizard will detect a missing CLI before asking for any secrets and tell you how to install it.
  • Browser access — for one-time auth flows against BotFather, Anthropic, Upstash, and Vercel. If you're on a headless box, pass the service credentials you already have.

3. Disable Vercel deployment protection

By default, brand-new Vercel projects have SSO-based deployment protection turned on, which bounces Telegram's webhook off an authentication wall. Go to Settings → Deployment Protection in your new project and set both Vercel Authentication and Protection for Deployment URLs to Disabled. The webhook is already authenticated by aTELEGRAM_WEBHOOK_SECRET header check in code.

This is a one-time step and Yuna will detect it automatically in a future release.

4. Register a device

Once the server is live, add a device. On any machine you want to expose:

# 1. From Telegram, send /create-code to your bot
#    → copy the code (e.g. ABCD-1234)

# 2. On the new device
npm install -g yuna-bot
yuna add-device --code ABCD-1234 --url https://your-app.vercel.app

# 3. Start the agent (foreground)
yuna start

The agent long-polls /api/relay/poll and executes any commands it receives. Leave it running, or put it under systemd / launchd for unattended operation.

5. Say hi

From Telegram, try:

/start
/status
what time is it
check my disk usage
@opus explain how this works

First ones answer directly, the disk command routes to your device via tool_use. See commands for the full list.