Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Web Dashboard (torc-dash)

The Torc Dashboard (torc-dash) provides a modern web-based interface for monitoring and managing workflows, offering an intuitive alternative to the command-line interface.

Overview

torc-dash is a Rust-based web application that allows you to:

  • Monitor workflows and jobs with real-time status updates
  • Create and run workflows by uploading specification files (YAML, JSON, JSON5, KDL)
  • Visualize workflow DAGs with interactive dependency graphs
  • Debug failed jobs with integrated log file viewer
  • Generate resource plots from time series monitoring data
  • Manage torc-server start/stop in standalone mode
  • Live event streaming via Server-Sent Events (SSE) for real-time job and compute node events

Installation

Building from Source

torc-dash is built as part of the Torc workspace:

# Build torc-dash
cargo build --release -p torc-dash

# Binary location
./target/release/torc-dash

Prerequisites

  • A running torc-server (or use --standalone mode to auto-start one)
  • The torc CLI binary in your PATH (for workflow execution features)

Running the Dashboard

Quick Start (Standalone Mode)

The easiest way to get started is standalone mode, which automatically starts torc-server:

torc-dash --standalone

This will:

  1. Start torc-server on an automatically-detected free port
  2. Start the dashboard on http://127.0.0.1:8090
  3. Configure the dashboard to connect to the managed server

Connecting to an Existing Server

If you already have torc-server running:

# Use default API URL (http://localhost:8080/torc-service/v1)
torc-dash

# Specify custom API URL
torc-dash --api-url http://myserver:9000/torc-service/v1

# Or use environment variable
export TORC_API_URL="http://myserver:9000/torc-service/v1"
torc-dash

Command-Line Options

Options:
  -p, --port <PORT>           Dashboard port [default: 8090]
      --host <HOST>           Dashboard host [default: 127.0.0.1]
      --socket <PATH>         Listen on a UNIX domain socket instead of TCP (unix only)
  -a, --api-url <API_URL>     Torc server API URL [default: http://localhost:8080/torc-service/v1]
      --torc-bin <PATH>       Path to torc CLI binary [default: torc]
      --torc-server-bin       Path to torc-server binary [default: torc-server]
      --standalone            Auto-start torc-server alongside dashboard
      --server-port <PORT>    Server port in standalone mode (0 = auto-detect) [default: 0]
      --database <PATH>       Database path for standalone server
      --completion-check-interval-secs <SECS>  Server polling interval [default: 5]
      --anthropic-api-key           Anthropic API key [env: ANTHROPIC_API_KEY]
      --anthropic-foundry-api-key  Foundry API key [env: ANTHROPIC_FOUNDRY_API_KEY]
      --anthropic-foundry-resource Foundry resource [env: ANTHROPIC_FOUNDRY_RESOURCE]
      --anthropic-base-url         Override API base URL [env: ANTHROPIC_BASE_URL]
      --anthropic-auth-header      Override auth header name [env: ANTHROPIC_AUTH_HEADER]
      --torc-mcp-server-bin        Path to torc-mcp-server [default: torc-mcp-server]
      --anthropic-model            Claude model [default: claude-sonnet-4-20250514]

Features

Workflows Tab

The main workflows view provides:

  • Workflow list with ID, name, timestamp, user, and description
  • Create Workflow button to upload new workflow specifications
  • Quick actions for each workflow:
    • View details and DAG visualization
    • Initialize/reinitialize workflow
    • Run locally or submit to scheduler
    • Delete workflow

Creating Workflows

Click "Create Workflow" to open the creation dialog:

  1. Upload a file: Drag and drop or click to select a workflow specification file
    • Supports YAML, JSON, JSON5, and KDL formats
  2. Or enter a file path: Specify a path on the server filesystem
  3. Click "Create" to register the workflow

Details Tab

Explore workflow components with interactive tables:

  • Jobs: View all jobs with status, name, command, and dependencies
  • Files: Input/output files with paths and timestamps
  • User Data: Key-value data passed between jobs
  • Results: Execution results with return codes and resource metrics
  • Compute Nodes: Available compute resources
  • Resource Requirements: CPU, memory, GPU specifications
  • Schedulers: Slurm scheduler configurations

Features:

  • Workflow selector: Filter by workflow
  • Column sorting: Click headers to sort
  • Row filtering: Type in filter boxes (supports column:value syntax)
  • Auto-refresh: Toggle automatic updates

DAG Visualization

Click "View" on any workflow to see an interactive dependency graph:

  • Nodes represent jobs, colored by status
  • Edges show dependencies (file-based and explicit)
  • Zoom, pan, and click nodes for details
  • Legend shows status colors

Debugging Tab

Investigate failed jobs with the integrated debugger:

  1. Select a workflow
  2. Configure output directory (where logs are stored)
  3. Toggle "Show only failed jobs" to focus on problems
  4. Click "Generate Report" to fetch results
  5. Click any job row to view its log files:
    • stdout: Standard output from the job
    • stderr: Error output and stack traces
    • Copy file paths with one click

Events Tab (SSE Live Streaming)

Monitor workflow activity in real-time using Server-Sent Events (SSE):

  • Live event streaming - events appear instantly without polling
  • Connection status indicator - shows Live/Reconnecting/Disconnected status
  • Event types displayed:
    • job_started / job_completed / job_failed - Job lifecycle events
    • compute_node_started / compute_node_stopped - Worker node lifecycle
    • workflow_started / workflow_reinitialized - Workflow initialization events
    • scheduler_node_created - Slurm scheduler events
  • Clear button to reset the event list
  • Auto-reconnect on connection loss

Resource Plots Tab

Visualize CPU and memory usage over time:

  1. Enter a base directory containing resource database files
  2. Click "Scan for Databases" to find .db files
  3. Select databases to plot
  4. Click "Generate Plots" for interactive Plotly charts

Requires workflows run with granularity: "time_series" in resource_monitor config.

AI Chat Tab

The AI Chat tab provides an AI assistant powered by Claude that can interact with your workflows using natural language. The assistant uses the Torc MCP server to access workflow data, job logs, and management tools.

Setup:

The AI Chat tab requires an API key so the dashboard can call Claude directly. There are two supported API backends:

Option 1: Direct Anthropic API

export ANTHROPIC_API_KEY="sk-ant-..."
torc-dash

Option 2: Microsoft Azure AI Foundry

If you access Claude through Azure AI Foundry, set the Foundry-specific variables instead:

export ANTHROPIC_FOUNDRY_API_KEY="your-foundry-key"
export ANTHROPIC_FOUNDRY_RESOURCE="your-resource-name"
torc-dash

The dashboard constructs the Foundry endpoint automatically: https://{resource}.services.ai.azure.com/anthropic/v1/messages

When both direct and Foundry keys are set, Foundry takes precedence.

You also need the torc-mcp-server binary in your PATH (built alongside torc-dash when using --all-features or --features mcp-server). If installed elsewhere, specify its location:

torc-dash --torc-mcp-server-bin /path/to/torc-mcp-server

Don't have an API key?

If you use Claude through a subscription (Claude Pro/Max) or GitHub Copilot through an enterprise account, those credentials cannot be used with the dashboard's built-in chat. However, you can still get AI-assisted workflow management by connecting torc-mcp-server directly to your AI tool:

These approaches use the AI provider's own authentication and give you the same Torc tools in your terminal or editor instead of the dashboard.

Usage:

  • Type questions in natural language and press Enter (or click Send)
  • The assistant automatically uses MCP tools to query real data from your Torc server
  • If you have a workflow selected, the assistant uses it as the default context
  • Tool calls are shown as collapsible sections so you can see what data the AI accessed
  • Click "Clear" to reset the conversation

Example questions:

  • "Help me create a workflow"
  • "Show me the failed jobs and their error logs"
  • "Check resource utilization for workflow 42"
  • "Recover the failed jobs with 2x memory"
  • "Create a workflow with 10 parallel jobs"

Configuration:

SettingDefaultDescription
ANTHROPIC_API_KEY(none)API key for direct Anthropic API
ANTHROPIC_FOUNDRY_API_KEY(none)API key for Azure AI Foundry
ANTHROPIC_FOUNDRY_RESOURCE(none)Foundry resource name
--anthropic-modelclaude-sonnet-4-20250514Claude model to use
--torc-mcp-server-bintorc-mcp-serverPath to MCP server binary

At least one of ANTHROPIC_API_KEY or ANTHROPIC_FOUNDRY_API_KEY (with ANTHROPIC_FOUNDRY_RESOURCE) must be set. If neither is configured, the AI Chat tab appears disabled in the sidebar.

Note: The API key is kept server-side and never sent to the browser. All AI requests are proxied through the torc-dash backend.

Configuration Tab

Server Management

Start and stop torc-server directly from the dashboard:

  • Server Port: Port to listen on (0 = auto-detect free port)
  • Database Path: SQLite database file location
  • Completion Check Interval: How often to check for job completions
  • Log Level: Server logging verbosity

Click "Start Server" to launch, "Stop Server" to terminate.

API Configuration

  • API URL: Torc server endpoint
  • Test Connection: Verify connectivity

Settings are saved to browser local storage.

Common Usage Patterns

Running a Workflow

  1. Navigate to Workflows tab
  2. Click Create Workflow
  3. Upload your specification file
  4. Click Create
  5. Click Initialize on the new workflow
  6. Click Run Locally (or Submit for Slurm)
  7. Monitor progress in the Details tab or Events tab

Debugging a Failed Workflow

  1. Go to the Debugging tab
  2. Select the workflow
  3. Check "Show only failed jobs"
  4. Click Generate Report
  5. Click on a failed job row
  6. Review the stderr tab for error messages
  7. Check stdout for context

Monitoring Active Jobs

  1. Open Details tab
  2. Select "Jobs" and your workflow
  3. Enable Auto-refresh
  4. Watch job statuses update in real-time

Security Considerations

  1. Network Access: By default, binds to 127.0.0.1 (localhost only)
  2. UNIX Socket (recommended for HPC): Use --socket /tmp/torc-dash-$USER.sock on shared login nodes. The socket file is created with 0600 permissions, restricting access to your user account. Connect via ssh -L 8090:/tmp/torc-dash-$USER.sock user@login-node.
  3. Remote Access: Use --host 0.0.0.0 with caution; consider a reverse proxy with HTTPS
  4. Authentication: Torc server supports htpasswd-based authentication (see Authentication)

Troubleshooting

Cannot Connect to Server

  • Verify torc-server is running: curl http://localhost:8080/torc-service/v1/workflows
  • Check the API URL in Configuration tab
  • In standalone mode, check server output for startup errors

Workflow Creation Fails

  • Ensure workflow specification is valid YAML/JSON/KDL
  • Check file paths are accessible from the server
  • Review browser console for error details

Resource Plots Not Showing

  • Verify workflow used granularity: "time_series" mode
  • Confirm .db files exist in the specified directory
  • Check that database files contain data

Standalone Mode Server Won't Start

  • Verify torc-server binary is in PATH or specify --torc-server-bin
  • Check if the port is already in use
  • Review console output for error messages

Architecture

torc-dash is a self-contained Rust binary with:

  • Axum web framework for HTTP server
  • Embedded static assets (HTML, CSS, JavaScript)
  • API proxy to forward requests to torc-server
  • CLI integration for workflow operations
  • MCP client that spawns torc-mcp-server as a subprocess for AI Chat

The frontend uses vanilla JavaScript with:

  • Cytoscape.js for DAG visualization
  • Plotly.js for resource charts
  • Custom components for tables and forms

Next Steps