Interactive Dashboard

Interactive Dashboard

Build interactive web dashboards inside the sandbox and expose them to the user via GetPreviewUrl. Use this skill for any request involving dashboards, trackers, monitors, live visualizations, or interactive web apps.

When to Use

Use this skill for a live, served web app — one that needs a running server, not a single file:

• User asks for a dashboard, tracker, or monitor that refreshes live data (polling, auto-update)
• The app needs server-side logic — filtering/screening over a large dataset, on-demand fetches, computed endpoints
• Multi-page / routed apps, or anything that needs React-level component interactivity
• The dataset is too large to embed in a single HTML file
• User explicitly says "preview", "web view", "web app", or wants it running at a URL

Do NOT use if:

• User wants a self-contained HTML report — even an interactive one (sortable tables, tabs, hover/zoom charts) over a data snapshot. That's .agents/skills/html-report/SKILL.md: one file in the task directory, keepable, printable, PDF-exportable, share-linkable. Interactivity by itself does not require a dashboard.
• User wants a static chart image → matplotlib/plotly savefig.
• User wants an in-chat figure → inline-widget (ShowWidget).

Dashboard vs. HTML Report

Both can be interactive, so the divide is live served app vs. self-contained snapshot file, not static vs. interactive:

Architecture

Choose the tier based on complexity:

Decision rule: Start with Simple. Escalate to FastAPI + HTML when user needs live data refresh or server-side logic. Escalate to Complex only when user needs React-level component interactivity, client-side routing, or a multi-page SPA.

Port convention: Use port 8050 (default). Range 8050-8059 for dashboards.

CSP / Iframe Safety

The preview iframe enforces Content Security Policy (CSP). Certain patterns are silently blocked — no error banner, just dead UI elements. Always use the safe alternatives:

Quick self-check — run before serving to catch violations:

import subprocess
result = subprocess.run(
    ["grep", "-rnE", r'on(click|input|change|focus|blur|submit|load|error|mouse|key)\s*=',
     "dashboard/"],
    capture_output=True, text=True
)
if result.stdout.strip():
    raise RuntimeError(f"CSP-unsafe inline handlers found:\n{result.stdout}")

Template literal hygiene — when building HTML strings in JS template literals, CSS semicolons inside ${} expressions cause silent parse failures:

// BAD — semicolon inside ${} terminates the expression early
const el = `<div style="color:${positive ? 'green' : 'red'; font-weight:600}">`;

// GOOD — close the expression first, then continue the attribute string
const el = `<div style="color:${positive ? 'green' : 'red'};font-weight:600">`;

Rule: never put a CSS semicolon inside ${} — always close } before the semicolon.

How Preview Serving Works

GetPreviewUrl is a platform-level tool available only to the main agent runtime. It is NOT a Python function — do not import it or call it from execute_code. The agent invokes it as a tool call.

When you call GetPreviewUrl(port, command, title):

1. The command is persisted to the database automatically
2. The platform starts the command in a dedicated sandbox session for that port
3. It polls until the port is listening, then generates a signed URL
4. If the port is already reachable, the command start is skipped entirely

Sub-agent fallback: Sub-agents cannot call GetPreviewUrl. Instead, build the dashboard files, start the server for verification, then return the serve details so the orchestrating agent can call GetPreviewUrl.

All tiers — use the Bash tool with run_in_background=true to start the server:

# Simple tier — Bash tool with run_in_background=true
cd <task> && python -m http.server 8050 --bind 0.0.0.0

# Docker tiers — Bash tool with run_in_background=true
cd <task> && bash start.sh

Then verify it's up in a separate (foreground) Bash call:

for i in $(seq 1 15); do curl -sf http://127.0.0.1:8050/ > /dev/null && echo "Server ready" && exit 0 || sleep 1; done; echo "FAIL"; exit 1

Then return all three fields to the orchestrating agent (it needs the command for DB persistence / restart recovery):

port: 8050
command: "cd <task> && python -m http.server 8050 --bind 0.0.0.0"  # or "bash <task>/start.sh"
title: "AAPL Stock Dashboard"

The orchestrating agent calls GetPreviewUrl(port=8050, command="...", title="...") which persists the command.

On workspace restart (user closes and reopens later):

• The sandbox filesystem persists (files, installed packages, Docker image cache all survive)
• Only processes die — the platform looks up the saved command and re-executes it
• The preview URL auto-recovers

Implication: Write commands that are idempotent — they must work whether run for the first time or re-run after a restart. The platform handles the rest. Docker image cache survives restart so rebuilds are fast (~2-5s with warm cache).

Sandbox Capabilities

All pre-installed in the Daytona sandbox snapshot — no pip install or apt-get needed:

• Python 3.12 + pandas, numpy, plotly, matplotlib, requests, httpx, yfinance
• FastAPI + uvicorn (available via fastmcp transitive dependency)
• Node.js 24 + npm (host sandbox) / Node.js 20 (Docker apt install nodejs) — scaffold Vite/React projects with npm create vite@latest
• Docker Engine — for complex tier containerized dashboards (backend + frontend in one image)
• Playwright + Chromium — available for verification testing

Workflow

Step 1: Clarify Scope

Before writing any code:

• What data? (specific tickers, sector, portfolio, screener results)
• What visualizations? (price chart, comparison table, heatmap, etc.)
• Static snapshot or live refresh?
• How complex? (determines simple vs complex tier)

Step 2: Fetch Data

Use YF MCP servers as the default financial data source (no API keys needed):

from tools.yf_price import get_stock_history, get_multiple_stocks_history
from tools.yf_fundamentals import get_company_info, compare_valuations
from tools.yf_analysis import get_analyst_price_targets, get_news
from tools.yf_market import get_sector_info, screen_stocks

Always fetch and validate data before writing any HTML/React code. Check for empty responses.

Step 3: Process Data

Use pandas to clean, aggregate, and compute derived metrics:

import pandas as pd
import json

# Fetch
history = get_stock_history("AAPL", period="1y", interval="1d")
info = get_company_info("AAPL")

# Process
df = pd.DataFrame(history)
df['change_pct'] = df['close'].pct_change() * 100

# Prepare for frontend
chart_data = json.dumps({
    "dates": df['date'].tolist(),
    "prices": df['close'].tolist(),
    "volumes": df['volume'].tolist(),
})

Step 4: Build Dashboard

Simple tier — write a self-contained HTML file:

html = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AAPL Dashboard</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
    <style>
        /* See references/ui-components.md for the theme foundation CSS */
    </style>
</head>
<body>
    <script>const DATA = {chart_data};</script>
    <script>
        /* Chart rendering code */
    </script>
</body>
</html>"""

with open("dashboard/index.html", "w") as f:
    f.write(html)

FastAPI + HTML tier — write a FastAPI server with API routes + StaticFiles mount, and a single static/index.html with fetch() polling (see FastAPI + HTML Tier section below).

Complex tier — scaffold a FastAPI + Vite/React project (see Complex Tier section below).

Step 5: Verify Before Serving

Tier 1 — Syntax check (required, < 1 second)

Extract <script> blocks from the HTML and check with node --check:

import re, subprocess, tempfile, os

with open("dashboard/index.html") as f:
    html = f.read()

scripts = re.findall(r'<script(?![^>]*src)[^>]*>(.*?)</script>', html, re.DOTALL)
for i, src in enumerate(scripts):
    with tempfile.NamedTemporaryFile(suffix=".js", mode="w", delete=False) as tmp:
        tmp.write(src)
        tmp_path = tmp.name
    result = subprocess.run(["node", "--check", tmp_path], capture_output=True, text=True)
    os.unlink(tmp_path)
    if result.returncode != 0:
        raise RuntimeError(f"JS syntax error in script block {i+1}:\n{result.stderr}")
print("Syntax check passed")

Also run the CSP self-check grep from the CSP section above.

Tier 2 — Browser verification (recommended for interactive dashboards)

Run when the dashboard has buttons, filters, or tabs. Skip for static data displays.

After GetPreviewUrl starts the server, run a Playwright check to catch runtime errors:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    js_errors = []
    page.on("pageerror", lambda exc: js_errors.append(str(exc)))
    page.goto("http://127.0.0.1:8050/", wait_until="networkidle", timeout=20000)
    assert not js_errors, f"JS runtime errors: {js_errors}"
    assert len(page.locator("body").inner_text().strip()) > 20, "Page appears blank"
    page.screenshot(path="dashboard/verify-screenshot.png", full_page=True)
    browser.close()
print("Browser verification passed")

See references/verification.md for extended templates with button-click testing and API response validation.

Step 6: Serve & Expose

# Simple tier
GetPreviewUrl(port=8050, command="cd dashboard && python -m http.server 8050 --bind 0.0.0.0", title="AAPL Dashboard")

# FastAPI + HTML tier / Complex tier
GetPreviewUrl(port=8050, command="bash dashboard/start.sh", title="Stock Dashboard")

Local verification before GetPreviewUrl — if you need the server running for Playwright verification, use the Bash tool with run_in_background=true (see sub-agent fallback above for the pattern). Do NOT use subprocess.Popen from execute_code — the process becomes a zombie when the tool-call shell exits.

Step 7: Iterate

After the user sees the preview, adjust layout, data, or charts based on feedback.

Data Integration — YF MCP Servers

Default data sources for common dashboard needs:

Yahoo Finance Field Conventions

Many fields are already in display units — do NOT multiply by 100:

get_predefined_screen Response Structure

Quotes are nested — not at the top level:

result = get_predefined_screen("day_gainers")
quotes = result["data"]["quotes"]  # nested at result["data"]["quotes"], NOT result["quotes"]
# Each quote: symbol, regularMarketPrice, regularMarketChangePercent, marketCap, ...

Direct yfinance Usage (Docker / without MCP)

Inside Docker containers, MCP tool modules are unavailable. Use yfinance directly:

import yfinance as yf

# Stock screener (yfinance 1.2.0+)
result = yf.screen("day_gainers", count=5)
quotes = result.get("quotes", [])

# Stock data
ticker = yf.Ticker("AAPL")
info = ticker.info
hist = ticker.history(period="1y")

UI Design Rules

Read .agents/skills/ui-design/SKILL.md for design quality (typography, color, avoiding generic AI aesthetics).

Theming

A dashboard must follow the theme it is viewed in — never ship a fixed palette:

• In the app, the viewer injects theme tokens (--color-bg-page, --color-text-primary, …) that flip with the user's light/dark setting.
• Standalone (downloaded and opened directly) no tokens exist, so the dashboard follows the OS via prefers-color-scheme.

The Theme Foundation block in references/ui-components.md §1 implements both: each bridge variable reads the app token first and falls back to an OS-adaptive value. Include that block verbatim in every dashboard, then style only with the bridge variables. Canvas/SVG chart code can't read var() — read the resolved value with the pick() helper (see references/chart-patterns.md). Never hardcode a palette hex in styles.

Light and dark literal values live only in the foundation block — don't restate them elsewhere.

Layout

• KPI cards in a row at top (price, change, volume, market cap)
• Charts in a responsive 2-column grid below
• Tables full-width at bottom
• No horizontal scroll — everything fits the iframe width
• Use CSS Grid with auto-fit and minmax() for responsive columns

Typography

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

Financial Data Formatting

• Prices: 2 decimal places with $ prefix ($182.52)
• Percentages: 2 decimal places with % suffix, color-coded green/red (+2.34% / -1.56%)
• Large numbers: Abbreviated with suffix ($2.87T, $142.5B, $3.2M)
• Volumes: Comma-separated (12,345,678) or abbreviated (12.3M)
• Dates: MMM DD, YYYY format (Mar 15, 2026)

See references/ui-components.md for complete CSS and component code.

FastAPI + HTML Tier — Project Structure

For live-data dashboards without React. FastAPI serves API endpoints and static HTML directly — no npm, no build step. Use the copy-ready template files with .fastapi-html suffix in references/:

<task>/
├── Dockerfile           # cp references/Dockerfile.fastapi-html Dockerfile
├── start.sh             # cp references/start.sh start.sh
├── server/
│   ├── main.py          # cp references/server-main.fastapi-html.py server/main.py
│   └── requirements.txt # cp references/requirements.txt server/requirements.txt
└── static/
    └── index.html       # Single HTML file with fetch() polling

Setup Workflow

1. Copy template files — all four cp commands above, then add your API routes to server/main.py
2. Add your Python deps to server/requirements.txt (append pandas, yfinance, etc.)
3. Write static/index.html with fetch() calls to your API routes for live data
4. Serve: GetPreviewUrl(port=8050, command="bash <task>/start.sh", title="Dashboard")

Template Files

Dockerfile (references/Dockerfile.fastapi-html) — Python 3.12-slim only (no Node/npm). Uses uv pip install for fast deps.

server/main.py (references/server-main.fastapi-html.py) — FastAPI skeleton with CORS, HEAD /, /healthz, and StaticFiles mount for static/ directory. StaticFiles is the last mount (catches all unmatched routes).

start.sh — same references/start.sh template (works unchanged for all Docker tiers).

Key Differences from Complex Tier

• No frontend/ directory — HTML lives in static/
• No npm/Node — Dockerfile uses python:3.12-slim only
• StaticFiles mount — serves static/ directory with html=True (auto-serves index.html)
• fetch() for live data — HTML uses setInterval(() => fetch('/api/data').then(...), 30000) for auto-refresh
• No SPA routing — single index.html, no client-side router needed

Complex Tier — Project Structure

When using FastAPI + Vite/React, scaffold this structure using the copy-ready template files in references/:

<task>/
├── Dockerfile           # Copy from references/Dockerfile
├── start.sh             # Copy from references/start.sh
├── server/
│   ├── main.py          # Copy from references/server-main.py, add your API routes
│   ├── requirements.txt # Copy from references/requirements.txt, add your deps
│   ├── routes/          # API route modules (stocks.py, sectors.py)
│   └── models.py        # Pydantic response models
├── frontend/
│   ├── package.json     # Vite + React + chart libraries
│   ├── vite.config.js   # Copy from references/vite.config.js
│   ├── index.html
│   └── src/
│       ├── App.jsx      # Main app with routing/tabs
│       ├── components/  # Chart, KPI, Table components
│       ├── hooks/       # useStockData, useSectorData, etc.
│       └── utils/       # formatters, color helpers
└── verify.py            # Copy from references/verification.md (optional)