Storyboard AI — Desktop Bridge

This tiny program lets a hosted Storyboard AI webapp run on your own Claude Code / Gemini CLI login. It runs on your computer, connects out to the app, and answers the app's AI requests by running your local CLI under your own subscription. No API key. Nothing listens for inbound connections — the bridge dials out, so it works behind home routers and firewalls with no setup.

Prerequisites (one-time)

1. Node.js 18+
2. A logged-in AI CLI — at least one of:
   • Claude Code — install, then claude once and sign in.
   • Gemini CLI — install, then gemini once and sign in.

Run

# easiest — always runs the latest published version
npx storyboard-bridge --server https://your-app.example.com

# or install once and run
npm i -g storyboard-bridge
storyboard-bridge --server https://your-app.example.com

Leave it running while you use the webapp. (It auto-reconnects if the connection drops.)

Options

| Flag | Env | Default | Meaning | |------|-----|---------|---------| | --server <url> | STORYBOARD_SERVER | http://localhost:8787 | The app's URL (https→wss is derived automatically). | | --token <tok> | STORYBOARD_TOKEN | (none) | Pairs the bridge to one browser. Copy it from the app's Connect desktop panel. Omit to run a shared bridge that powers every session (handy when self-hosting just for yourself). | | --provider <name> | LLM_PROVIDER | claude | claude or gemini — which CLI to serve jobs with. | | --model <name> | LLM_MODEL | CLI default | Optional model override passed to the CLI. | | --files <dir> | STORYBOARD_FILES | (none) | A local folder to store & serve your assets (e.g. a OneDrive folder). With this set, your uploads + generated images/videos/audio live on your machine — the hosted app keeps only keys. Omit it and the app stores assets server-side. | | — | CLAUDE_BIN / GEMINI_BIN | on PATH | Path to the CLI binary if it isn't on your PATH. |

Local asset storage (keep your media on your own machine)

Point --files at a folder — ideally a synced one like OneDrive — and the bridge becomes the file store for your assets. The hosted backend never holds the bytes: it asks your bridge to read/write them over the same connection. Use your OS's native path:

# Windows (PowerShell/cmd)
npx storyboard-bridge --server https://your-app.example.com --token <tok> ^
  --files "C:\Users\You\OneDrive\Storybuilder-ai"

# WSL
npx storyboard-bridge --server https://your-app.example.com --token <tok> \
  --files "/mnt/c/Users/You/OneDrive/Storybuilder-ai"

# macOS
npx storyboard-bridge --server https://your-app.example.com --token <tok> \
  --files "/Users/you/OneDrive/Storybuilder-ai"

Caveat: your assets are only viewable/generatable while this bridge is running — if your machine is off, the app can't reach your files. (The same is already true for the AI: jobs run on your CLI.)

The easiest path: open the app, click Connect desktop, and copy the ready-made command (it already includes the right --server and --token).

Updating

npx storyboard-bridge always fetches the latest version. If you installed globally, run npm i -g storyboard-bridge again. When you connect, the server tells the bridge the latest version and it prints a notice if yours is older — so new features land by simply updating this one small package.

How it works

  your desktop (this bridge + your logged-in CLI)        hosted Storyboard AI
        │                                                       │
        │── dials out, "hello" (version + which CLIs) ─────────▶│
        │◀──────────── job: { id, prompt } ─────────────────────│   (you click generate)
        run `claude -p` / `gemini -p` locally
        │── result: { id, text } ──────────────────────────────▶│── shows up in the app

Your CLI login never leaves your machine; only prompts in and text out cross the wire.