Bloom Web Dashboard

Bloom is Colony’s web dashboard. Real-time interface for creating, monitoring, and managing colonies. Built with SolidJS and SolidStart, it connects to Mycelium via WebSocket for instant updates using JSON messages.

Overview

Three main views:

• Colony List — Browse all colonies, see states, spawn new ones
• Colony Detail — Live previews, logs, state timeline
• Brood Management — Orchestrate multiple colonies toward a shared objective

Everything updates in real-time. When a colony transitions from provisioning to running, Bloom shows it immediately. No polling.

Getting Started

Start Bloom’s dev server:

cd bloom
bun install
bun run dev

Bloom runs at http://localhost:3000 and expects Mycelium at http://localhost:8000.

Colony List View

The colony list (/colonies) shows all active colonies:

• Name and ID — Human-readable name plus unique identifier
• State Badge — Visual indicator (provisioning, running, stopped, failed)
• Service Count — Number of services in colony.toml
• Created Date — When the colony was spawned

Click any colony to see its detail view. Click Create Colony to spawn a new one.

Colony Detail View

The detail view (/colonies/:id) is Bloom’s centerpiece.

State Timeline

A horizontal timeline showing lifecycle progression:

cloning → provisioning → building → starting → running

Each state includes a timestamp. Failed states show error details.

Preview System

The preview panel uses a tab-per-service model. Tabs are generated dynamically from the [services] section of colony.toml.

If your colony.toml defines:

[services.web]
command = "node server.js"
port = 4001

[services.api]
command = "node api.js"
port = 4002

Bloom renders these tabs:

1. web — Web preview (iframe sandbox)
2. api — API preview (JSON viewer)
3. terminal — Terminal access (xterm.js)
4. agent — Agent execution stream (if enabled)

Web Preview

Web service tabs display an iframe sandbox showing the service’s output. The iframe is configured without allow-same-origin, preventing malicious code from accessing the parent page.

DevTools Toolbar includes:

• URL bar — Shows current URL (e.g., hello-colony-4001.colony.local)
• Refresh button — Reloads the iframe
• External link — Opens preview in a new browser tab
• DevTools toggle — (Future) Inspect element, view console

URL pattern: {colony-name}-{port}.colony.local. Caddy registers these routes when services start.

API Preview

API tabs use the FetchPreview component. It makes an HTTP request to the service endpoint and renders the JSON response with syntax highlighting. Perfect for REST APIs.

Terminal Preview

The terminal tab uses xterm.js v5 with Nerd Font support. It connects via a dedicated binary WebSocket to Mycelium’s PTY endpoint.

Features:

• Full terminal emulation (VT100/xterm-256color)
• Bi-directional communication (keyboard input → PTY, PTY output → screen)
• Auto-reconnect on connection loss
• Fit-to-viewport resize handling

The PTY session is managed by dedicated OTP actors (pty_session and pty_manager) in Mycelium.

Agent Preview

If your colony uses agent-driven development, the agent tab displays a streaming event viewer:

• Text events — Agent reasoning and output
• Tool use events — Tools invoked with input summaries
• Tool result events — Tool execution results with error flags
• Status events — Session lifecycle transitions (working, completed, failed)

Events stream in real-time via the hld daemon’s subscription API. The panel auto-scrolls to keep the latest event visible.

Status Indicator shows current agent state:

State	Color	Meaning
Working	Green pulse	Agent executing
Done	Green solid	Session completed
Failed	Red	Execution failed
Idle	Gray	No active session

Resizable Panels

Bloom uses @corvu/resizable for panel management. Drag the divider to adjust sizes. Panel state persists in localStorage.

Brood Management

Broods orchestrate multiple colonies toward a shared objective. Navigate to /broods to see all active broods.

Brood List

Shows:

• Name and Objective — High-level goal
• State Badge — Planning, running, completed, or failed
• Colony Count — Number of colonies in the brood
• Progress Indicator — Task completion percentage

Brood Detail

The brood detail view (/broods/:id) displays:

• Multi-Colony Grid — All colonies in the brood, each with its own preview panel
• Task Breakdown — Derived plan showing task assignments to colonies
• Brood State — Overall orchestration state (pending, planning, running, completed, failed)

Brood state is derived from constituent colony states:

• All colonies completed → Brood is completed
• Any colony failed → Brood is failed
• At least one colony running → Brood is running

Real-Time Updates

Bloom receives updates via WebSocket using JSON messages. Supported events:

Event	Trigger
colony_state_changed	Colony transitions to new state
colony_deleted	Colony removed
agent_event	Agent text/tool_use/tool_result/status
brood_state_changed	Brood transitions to new state

These events update SolidJS stores (colonies, broods, agent, connection), triggering reactive UI updates.

Log Streaming

Colony logs stream via Server-Sent Events from Mycelium’s /api/colonies/:id/logs/stream endpoint. Bloom’s LogViewer component (accessible via the sidebar) displays:

• Correlation IDs — Track related operations across services
• Log Levels — Color-coded (info, warn, error)
• Timestamps — Precise timing for debugging
• Auto-scroll — Follow mode keeps newest logs visible

Logs are stored in per-colony RingLogger instances (ETS-backed ring buffers) in Mycelium, configurable via max_entries (default: 10,000).

Creating Colonies

Click Create Colony to open the dialog. Provide:

1. Name — Human-readable identifier (alphanumeric + hyphens)
2. Template — Pre-configured setup (web-app, api-service, full-stack, custom)
3. Repository URL — Git/Jujutsu repo to clone
4. Branch — Target branch (default: main)
5. Configuration — TOML config or JSON payload

The dialog validates inputs before submission. Invalid names or unreachable repos get rejected.

Keyboard Shortcuts

Bloom supports keyboard navigation:

Key	Action
c	Focus colony list
t	Focus terminal tab
a	Focus agent tab
/	Focus search/filter
r	Refresh active preview
?	Show keyboard shortcut help

Architecture Notes

Bloom is built with:

• SolidJS — Fine-grained reactivity without virtual DOM
• SolidStart — Meta-framework with file-based routing
• @corvu/resizable — Accessible resize panels
• xterm.js — Terminal emulation Communication flow:

Bloom (SolidJS) ↔ WebSocket + JSON ↔ Mycelium (Gleam/OTP)

Configuration

Bloom reads configuration from environment variables:

Variable	Default	Description
VITE_MYCELIUM_HTTP_URL	http://localhost:8000	Mycelium HTTP endpoint
VITE_MYCELIUM_WS_URL	ws://localhost:8000/ws	Mycelium WebSocket endpoint
VITE_ENABLE_DEMO_MODE	false	Show demo placeholders

Set these in .env.local (gitignored) for local development.

Next Steps

• Configure templates — Customize colony provisioning
• Set up agent backends — Connect Claude Code or other AI agents
• Read the architecture guide — Understand how components communicate

Bloom is Colony’s visual heart. Real-time feedback and interactive debugging for multi-agent development.