OpenToad Pet

A global npm package that puts the OpenToad desk companion on your desktop and lets any machine join the OpenToad resource pool through terminal config.

npm install -g opentoad-pet
pet

What it does

• Desk pet on Apple Silicon Macs: a frameless, draggable, pixel-art toad that lives on your desktop.
• Resource-pool node on any platform: Linux, macOS Intel, and Windows can join the pool with pet --pool-node.
• Interactive setup asks for workspace, server URL, allowed commands, and permissions before the pet starts.

Commands

| Command | What it does | |---|---| | pet | Launch the desk pet (Apple Silicon) or run pool-node setup | | pet --pool-node | Onboard this machine as a compute node | | pet --configure | Rerun the setup wizard | | pet --status | Show this node and registered pool nodes | | pet --help | Show usage |

Install

npm install -g opentoad-pet

The first time you run pet, it walks you through:

1. Node name — how this machine appears in the pool.
2. Workspace — the directory OpenToad can read and write.
3. Server URL — where the local OpenToad Python backend runs (http://127.0.0.1:8765).
4. Permissions — which commands, shell access, installs, network, cloud, and GPU are allowed.
5. Pool resources — what this machine offers (CPU, file watcher, GPU).

Configuration is saved to ~/.config/opentoad/pet.json and the pool registry is at ~/.config/opentoad/pool.json.

Desk pet interactions

• Drag the toad to move its window around.
• Click it to ribbit (Web Audio) and puff its throat.
• Drop files on it — the tongue shoots out, grabs the file, and POSTs it to /api/feed on the OpenToad backend.
• Stare — the toad’s eyes follow your cursor when it’s close.
• Breathe — its belly expands and contracts like a real frog.

Platform support

• Desk pet GUI: Apple Silicon (darwin + arm64) for now.
• Pool node: any platform that can run Node.js and the OpenToad Python backend (opentoad serve).

To add a Linux or Windows box to the pool:

npm install -g opentoad-pet
pet --pool-node
# then start the OpenToad Python server on that machine
opentoad serve

Auto-start on login (macOS)

pet --install-service     # start the pet at every login
pet --service-status      # check the service
pet --uninstall-service   # remove the login service

This creates ~/Library/LaunchAgents/com.opentoad.pet.plist and loads it with launchctl. Logs are written to ~/Library/Logs/opentoad-pet.log.

Publish to npm

A GitHub Actions workflow (.github/workflows/publish-npm.yml) publishes the package when a GitHub Release is published. Add an NPM_TOKEN secret in the repo settings, then:

cd desktop-app
npm version patch   # or minor / major
npm publish

Or trigger the workflow manually from the Actions tab.

Development

cd desktop-app
npm install
npm run dev        # launch the pet with dev tools
npm run build:mac  # build a DMG

Files

• bin/pet.js — CLI entry point
• lib/config.js — config / pool registry loading and saving
• lib/wizard.js — interactive setup
• lib/prompts.js — synchronous terminal prompts
• main.js — Electron main process
• preload.js — Electron preload / safe IPC bridge
• renderer/pet.html — the pixel-art toad