# 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

```bash
# 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**:

```bash
# 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.