InfiniBot OS — Personal AI Assistant

A personal AI control room you run on your own machine. Chat, voice, video editing, business CRM, kanban projects, mobile companion app, federation across devices, and ~20 more features — all behind one local gateway. Your keys, your data, your hardware.

InfiniBot answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat). It can speak and listen on macOS/iOS/Android, render a live Canvas, edit videos, manage your business pipeline, and run autonomous tasks in the background.

⚡ Quick Start (one-liner via gh)

This repo is private, so the gh CLI is required for the one-liner installs — it transparently auths git, raw downloads, and clones.

0 · One-time prereqs (any OS)

• Node.js 22+ and bun or pnpm
• GitHub CLI — gh
• Authenticate gh once:

  gh auth login          # pick GitHub.com → HTTPS → browser
  gh auth setup-git      # makes git clone use gh's token

1 · One-command install (every device, every update)

macOS / Linux — clone, then run the idempotent setup script:

git clone https://github.com/MrYungCEO/InfiniBot ~/InfiniBot
cd ~/InfiniBot
bash scripts/satellite-setup.sh

Windows (PowerShell) — clone OUTSIDE OneDrive (OneDrive sync corrupts node_modules):

cd C:\
git clone https://github.com/MrYungCEO/InfiniBot
cd InfiniBot
powershell -ExecutionPolicy Bypass -File scripts/satellite-setup.ps1

The script pins origin to the canonical repo, drops stray remotes, hard-resets to main, installs deps, and builds. Re-run it any time to sync that device to the latest main. Same script, same outcome on every machine.

💡 Subscriptions (recommended): Anthropic Claude Pro/Max for the smartest agent, OpenAI as fallback. Single keys also work — paste them in the wizard.

⚠️ npm install -g infinibot is currently unreliable — the auto-publish workflow is paused. Use the clone-based install above until it's restored.

2 · Start the gateway

export GATEWAY_PASSWORD="your-strong-password"   # macOS/Linux
# Windows PowerShell:  $env:GATEWAY_PASSWORD="your-strong-password"

pnpm start gateway --auth password --password "$GATEWAY_PASSWORD"
# Dashboard → http://127.0.0.1:18789

3 · Add a satellite (second device)

After the first device is up and running as master, see docs/federation/satellite-setup.md. The same one-liner above works on the satellite — the wizard's "Add Satellite Node" step on the master generates the connection JSON it needs.

For the full Quick Start with verification, troubleshooting, and platform notes: docs/QUICKSTART.md.

Silence federation-spawn prompts in Claude Code (one-time, per device)

If you drive InfiniBot through Claude Code, the harness will prompt every time it tries to spawn a sub-agent on a remote federated node — both mcp__infinibot__infinibot_sessions_spawn and its alias mcp__infinibot__sessions_spawn are gated separately. Pre-allowlist them once in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__infinibot__infinibot_sessions_spawn",
      "mcp__infinibot__sessions_spawn"
    ]
  }
}

Or run the bundled idempotent helper:

python3 scripts/allow-federation-spawns.py

Works from a clone, or as a one-liner without cloning:

curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/main/scripts/allow-federation-spawns.py | python3 -

The script merges into .permissions.allow, never clobbers existing entries, writes atomically, and keeps a .bak.

Run on every device that hosts a Claude Code session driving the federation (master and each satellite). After that, cross-node spawns go through silently.

Why not automatic? The Claude Code harness intentionally blocks any agent from auto-writing its own permissions.allow — including via memory, sub-agent delegation, or a gateway startup hook. The one-time human-applied edit is the only path it accepts.

Pick your path (deep dive)

| You want… | Go to | |---|---| | The fast one-liner | Quick Start above | | Run from source after git clone | Run from source | | A guided walkthrough with screenshots | Open setup.html in your browser | | Just spin it up in Docker | Docker quickstart (coming soon) |

2 · Run from source

You cloned the repo. Here's the 5-minute path to a running gateway:

# 1. Install dependencies (uses pnpm — install it once if you don't have it)
npm install -g pnpm
pnpm install

# 2. Set your API key (the agent needs at least one)
export ANTHROPIC_API_KEY="sk-ant-..."         # macOS / Linux
# Windows PowerShell:
# $env:ANTHROPIC_API_KEY = "sk-ant-..."

# 3. Pick a gateway password (anything memorable — you'll type it in the dashboard)
export GATEWAY_PASSWORD="your-strong-password"

# 4. Start the gateway. It auto-builds TypeScript on first run (~30s).
pnpm start gateway --auth password --password "$GATEWAY_PASSWORD"

# 5. Open the dashboard
#    macOS:    open http://127.0.0.1:18789
#    Linux:    xdg-open http://127.0.0.1:18789
#    Windows:  start http://127.0.0.1:18789

Type your gateway password on the login screen → you're in.

What you'll see first

The Welcome walkthrough auto-loads on the /learn page — five short steps that teach you the navigation, send your first message, set your language preferences, and point you at the deeper guides. Total time: ~5 minutes.

From there, pick whichever feature matters to you:

• 💬 Chat & Sessions — single chat, multi-session grid, voice, sub-agents
• 🎬 Video Studio — composition editor, AI asset analysis, ComfyUI rendering
• 📋 Projects & Kanban — agent-runnable tasks with criticality + GitHub precheck
• 💼 Business Center — multi-business CRM, Whop/Stripe income sync, Notion two-way
• 📱 Mobile — Expo Go QR pairing or build a personal IPA
• 🌐 Federation — pair multiple machines into one agent fabric
• 🎓 Learn — 19 interactive walkthroughs + a Master Certification

Every feature has a step-by-step walkthrough on the /learn page. Complete the cert-required tracks and the system mints an InfiniBot AI Agent Systems Master certificate with your name and a verification fingerprint.

Common flags

# Accept connections from your LAN (default: localhost only)
pnpm start gateway --bind lan --auth password --password "..."

# Federation master mode — accept satellite pairings from other machines
pnpm start gateway --master-mode --bind lan --tailscale on --auth password --password "..."

# Disable Tailscale binding (if you don't have it installed)
pnpm start gateway --bind lan --tailscale off --auth password --password "..."

# Custom port
pnpm start gateway --port 47913 --auth password --password "..."

Recommended .env for local dev

Drop this in the repo root as .env so you don't have to export keys every shell:

# Required for the agent to talk
ANTHROPIC_API_KEY=sk-ant-...

# Optional — fall through to these when Anthropic rate-limits
GEMINI_API_KEY=...
OPENROUTER_API_KEY=...

# Optional — voice (TTS), revenue providers, image generation
ELEVENLABS_API_KEY=...
STRIPE_SECRET_KEY=sk_...
WHOP_API_KEY=...
GEMINI_API_KEY=...                      # also powers Nano Banana image gen if you have it
COMFY_URL=http://127.0.0.1:8000         # local ComfyUI for storyboard / video studio

.env is gitignored. The gateway loads it on startup.

3 · Docker quickstart

Not shipped yet — see issue tracker for status. For now, the source-run path above is the fastest start.

4 · Federation Code Sync

InfiniBot's Federation Code Sync keeps every device in your federation on the same code revision, using GitHub as the hub:

• Any device can push code changes → GitHub → every other device pulls automatically
• Conflict-safe: detects uncommitted work before pulling, pauses with a clear message
• Cross-OS daemons: systemd (Linux), launchd (macOS), Scheduled Task (Windows)
• Meta tracking: .federation-sync.json records each device's hostname, role, and last sync commit

Bootstrap a new satellite

# 1. Clone the repo and install deps
gh repo clone MrYungCEO/infinibotOS
cd infinibotOS
pnpm install

# 2. Set your identity
export FEDERATION_ROLE=satellite
export FEDERATION_GIT_REMOTE=origin
export FEDERATION_GIT_BRANCH=main

# 3. First sync (dry-run to verify)
pnpm federation-sync sync --dry-run

# 4. Live sync
pnpm federation-sync sync

# 5. Install the auto-sync daemon
bash scripts/bootstrap-federation-sync.sh satellite

Manual commands

pnpm federation-sync status       # Show HEAD, ahead/behind, uncommitted
pnpm federation-sync sync          # Push local commits → pull remote changes
pnpm federation-sync sync --dry-run  # Safe preview
pnpm federation-sync sync --remote origin --branch main
pnpm federation sync-status        # Via CLI (federation sync-status)

Environment variables

| Variable | Default | Purpose | |---|---|---| | FEDERATION_ROLE | master | Device role in the federation tree | | FEDERATION_GIT_REMOTE | origin | Git remote to sync with | | FEDERATION_GIT_BRANCH | main | Branch to track | | FEDERATION_REPO_PATH | cwd | Path to the git repository | | FEDERATION_NODE_ID | — | Federation node ID for metadata |

How it works

1. Device A commits code → runs federation-sync sync → pushes to origin/main
2. Device B's daemon (or manual run) fetches → sees it's behind → fast-forwards
3. If Device B has uncommitted work → sync pauses and prints the conflict
4. .federation-sync.json records each device's identity in the sync trail
5. All operations log to logs/federation-audit/code-sync-YYYY-MM-DD.log

Logs follow the existing logs/federation-audit/ pattern already used by the federation system.

What's actually inside

InfiniBot ships ~20 production-ready feature areas. The full list with a one-line description per feature lives in docs/index.md. Highlights:

| Surface | What it does | |---|---| | Chat / Voice / Grid | Multi-model, multi-session, multi-device chat with wake-word voice | | Agency World | Live 2D world where every agent walks between work zones in real time as it calls tools — the headline mesh view (toggle with the 3D Neural Mesh) | | Projects | Kanban with agent-runnable tasks, GitHub precheck, criticality gates | | Business | Multi-business CRM, revenue sync (Whop/Stripe/Square), Notion two-way | | Video Studio | Composition editor, AI asset analysis, ComfyUI image gen, ProRes render | | Storyboard | End-to-end AI video: prompt → script → scenes → images → VO → MP4 | | Federation | Master/satellite topology, Tailscale meshing, cross-device sessions | | Mobile | Expo Go QR pairing + EAS Build for personal IPAs | | Multi-user | Per-user home dirs, page gating, agent directory locking, language/context | | Learn | 19 interactive walkthroughs + Master certification | | Apps registry | Unified catalog of every project/site/directory you've built | | Skills + MCP | Claude Code skills + MCP servers for richer agent tool surfaces | | Cron + Autonomy | Scheduled tasks, idle-detection-driven work, Telegram approval gates | | Vault | Run a paid community/courses/membership product locally | | Funnels | Sales funnels with AI lead qualification + KPI tracking |

Each one has a dedicated page in the dashboard and a step-by-step walkthrough in /learn.

Documentation

• 📘 setup.html — friendly one-page setup with copy-buttons + FAQ
• 📚 docs/index.md — full feature index
• 🎓 /learn (in-app) — 19 interactive walkthroughs from beginner → master
• 🛠 docs/QUICKSTART.md — single-command install
• 🌐 docs/federation.md — multi-device setup
• 📱 docs/storyboard.md — AI video pipeline
• 🏙 docs/agency-world.md — the live 2D agent-mesh world

Use infinibot doctor to diagnose a misbehaving install.

Operating systems

| OS | Status | Notes | |---|---|---| | macOS (12+) | ✅ Native | iMessage, voice wake-word, all features | | Linux | ✅ Native | All features except iMessage | | Windows 11 | ✅ Native | Most features. WSL2 strongly recommended for federation + mobile | | Windows 10 | ⚠️ Use WSL2 | Native install works but some helpers expect bash |

Runtime: Node 22+. Works with npm, pnpm, or bun.

Troubleshooting

| Symptom | Fix | |---|---| | unknown method: ... on first request | Restart the gateway after pnpm install so the methods registry rebuilds | | Login screen rejects your password | Stop the gateway, restart with --password "<your-password>" — passwords aren't read from .env | | ComfyUI not reachable in storyboard / video studio | Default URL is http://127.0.0.1:8000. Override with COMFY_URL=http://your-host:port | | Voice mode says "no Claude terminal selected" | Voice auto-spawns one when you Connect — give it 2 seconds | | Federation satellite won't pair | Check master is running with --master-mode and the password matches on both sides | | Anything else | infinibot doctor runs every diagnostic and prints what's wrong |

Contributing

Pull requests welcome. The project is a TypeScript monorepo (gateway server in src/, dashboard UI in ui/src/). Run pnpm test before sending PRs. See CONTRIBUTING.md.

License

MIT — see LICENSE.

"It's not a tool. It's a control room." — InfiniBot