Spawner UI – Orquestração Visual de Pipelines Claude
vibeforge1111/vibeship-spawner-ui
Dashboard visual para orquestração e execução de pipelines Claude em tempo real
Ver no GitHubPlataforma de execução e dashboard local para orquestração visual de chains e pipelines Claude. Funciona como plano de execução do Spark stack, coordenando fluxos multi-step, construção de missões e controle de ciclo de vida através de APIs locais integradas com Telegram e LLM providers.
Instalação
npx convez-ai vibeforge1111/vibeship-spawner-ui1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir e controlar fluxos de execução multi-step de forma visual
- Coordenar múltiplos providers de LLM em pipelines integrados
- Monitorar e debugar ciclo de vida completo de missões (Telegram → Builder → Execução)
Veredito

Ferramenta madura para casos de uso avançados que exigem orquestração visual de pipelines em escala. Requer familiaridade com arquitetura Spark, APIs locais e ciclo de vida de missões; essencial para equipes que automatizam fluxos complexos envolvendo múltiplos LLMs e persistência de estado.
README
A tradução para o português deste README ainda está na fila.
Spawner UI
Spawner UI is the execution plane and local dashboard for the Spark stack.
In the current supported starter architecture:
spark-telegram-botowns Telegram ingressspark-intelligence-builderis the Spark runtime corespawner-uiruns mission execution and the local visual control surface
Spawner UI does not own the Telegram bot token and does not receive Telegram webhooks directly.
Where It Fits
flowchart LR
Telegram["spark-telegram-bot"] --> Run["/run goal"]
Run --> API["Spawner UI APIs"]
API --> Mission["Mission builder and executor"]
Mission --> Canvas["Canvas / project workspace"]
Mission --> Events["Mission events"]
Events --> Telegram
What It Does
- provides the mission-building and mission-control UI
- exposes the local APIs used by the Telegram gateway for
/run,/board, and/mission - runs multi-step execution flows behind the gateway and Builder
- receives mission lifecycle callbacks from Spawner to Telegram through the local relay URL configured by Spark CLI
- loads PRD/project plans into the visual canvas
- coordinates configured LLM/provider runtimes through the mission orchestration layer
Current Role In The Spark Stack
Telegram
-> spark-telegram-bot
-> spark-intelligence-builder
-> spawner-ui when execution is needed
Spawner UI is the execution backend in that shape, not a competing ingress surface.
Spark CLI starter setup writes:
MISSION_CONTROL_WEBHOOK_URLSpointing at the Telegram relayTELEGRAM_RELAY_SECRETshared withspark-telegram-bot- non-secret LLM provider metadata such as provider, model, and base URL
Do not put Telegram bot tokens or cloud LLM API keys in Spawner UI env unless a specific provider integration explicitly requires them.
First Run
Most users should let Spark CLI install and wire this module:
spark setup
spark start spawner-ui
spark status
Manual local development:
git clone https://github.com/vibeforge1111/vibeship-spawner-ui
cd vibeship-spawner-ui
npm install
npm run dev
Then open the local URL printed by Vite.
Agent Operating Guide
If you are an LLM agent reading this repo:
- Use the APIs below only from a local trusted environment unless explicitly deploying.
- Keep
TELEGRAM_RELAY_SECRETsecret; it authenticates callbacks to Telegram. - Do not add Telegram bot token handling here.
- Prefer
npm run test:run,npm run check, andnpm run buildbefore claiming the UI is ready. - Use the canvas/PRD bridge for project setup instead of inventing a second mission format.
Key local API surfaces:
/api/spark/run- start a mission from a goal./api/mission-control/status- mission status./api/mission-control/command- pause/resume/kill/status./api/mission-control/board- board summary./api/mission-control/trace- stitched mission state across Telegram, PRD, Canvas, Dispatch, Kanban, and providers./memory-quality- Spark memory recall quality dashboard; see docs/memory-quality-dashboard.md./voice-system- redacted Spark voice runtime dashboard. Spawner UI reads the latest Builder snapshot plus live voice profile and delivery proof, so Telegram only needs/voice dashboardwhen the operator wants to refresh broader setup context. Spawner UI does not own voice credentials, Telegram tokens, or provider selection./api/prd-bridge/write- write a PRD into the workspace./api/prd-bridge/load-to-canvas- load a PRD/project into the visual canvas./api/spark-agent/*- Spark agent session bridge for canvas, mission, MCP, and event stream control.
Local Development
- Copy
.env.exampleto.envfor manual local development only. - Fill in only the provider keys and local settings you actually need, and keep secrets out of docs, command arguments, screenshots, and issue reports.
- Start the app:
npm install
npm run dev
Useful scripts:
npm run build
npm run check
npm run test:run
npm run smoke:routes
npm run smoke:mission-surfaces
Railway / Docker
This repo includes a Dockerfile for a hosted Spawner UI service. The production
container uses SvelteKit's Node adapter and starts with npm start.
For a two-service Railway deploy, keep spark-telegram-bot and spawner-ui in
the same project environment and communicate over Railway private DNS:
MISSION_CONTROL_WEBHOOK_URLS=http://spark-telegram-bot.railway.internal:8788/spawner-eventsTELEGRAM_RELAY_SECRET=<same value as the bot>SPARK_HOSTED_PRIVATE_PREVIEW=1SPARK_WORKSPACE_ID=<private non-guessable workspace slug>SPARK_BRIDGE_API_KEY=<same long value as the bot>SPARK_UI_API_KEY=<private browser/API access key>SPARK_UI_PAIRING_CODE=<optional one-time browser pairing code>SPAWNER_STATE_DIR=/data/spawnerSPARK_WORKSPACE_ROOT=/data/workspacesSPARK_ALLOW_EXTERNAL_PROJECT_PATHS=0
Mount a persistent volume at /data for Spawner state and workspaces. Hosted
preview links are served from the Spawner public domain and backed by files in
SPARK_WORKSPACE_ROOT.
Do not put SPARK_UI_API_KEY in browser URLs. Browser bootstrap links may use
?workspaceId=...&pairCode=... only when SPARK_UI_PAIRING_CODE is configured;
the server consumes that code once, sets an opaque session cookie, and redirects
to a clean URL.
For hosted smoke checks, run npm run health:spark inside the Spawner service.
Set SPARK_HEALTH_DEEP=1 to start a tiny mission smoke. The deep smoke uses
SPARK_HEALTH_PROVIDER when set, then the selected Mission provider, then
codex as a fallback.
For the full two-service Railway setup, provider guidance, preview-link checks, and Telegram end-to-end smoke tests, see docs/RAILWAY_HOSTED_RUNBOOK.md.
Documentation Map
- ARCHITECTURE.md - current Spark execution-plane architecture.
- SECURITY.md - local control surface and secret-handling rules.
- CLAUDE.md - instructions for coding agents working in this repo.
- docs/MISSION_LIFECYCLE.md - canonical mission and task status vocabulary.
- docs/SPARK_MISSION_CONTROL_TRACE.md - Telegram to PRD to Canvas to Dispatch to Kanban to Trace map.
- docs/SPARK_AGENT_BRIDGE_API.md - Spark agent bridge API contract.
- docs/SPARK_AGENT_CANVAS_LOCALHOST_RUNBOOK.md - local Spark agent canvas smoke.
- docs/RAILWAY_HOSTED_RUNBOOK.md - hosted Railway deploy, provider, and preview smoke runbook.
- docs/archive/retired-external-bridge/README.md - retired bridge archive notes.
Spark CLI Install Note
If you are installing the Telegram starter stack through spark setup, the
installer configures this module behind the gateway. You should not need to
hand-wire relay URLs, Telegram ownership, or repo-to-repo boundaries yourself.
Security Notes
- Do not commit
.env, provider keys, screenshots with tokens, local mission state, or private project files. - Keep mission relay URLs on localhost for the launch stack.
- Treat browser-facing APIs as local operator surfaces unless explicitly hardened for hosting.
License
MIT. See LICENSE.
Spark Swarm is AGPL-licensed. Other Spark repos are MIT unless their LICENSE file says otherwise. Spark Pro hosted services, private corpuses, brand assets, deployment secrets, and Pro drops are not included in open-source licenses. Pro drops do not grant redistribution rights unless a separate written license says so.