Virtual Client for VS Code

A professional-grade Visual Studio Code extension that streamlines the management and execution of Virtual Client workloads and performance benchmarking experiments across distributed remote machines.

🚀 Overview

Virtual Client for VS Code provides a comprehensive, lightweight, and integrated solution for orchestrating performance testing, benchmarking, and reliability experiments directly from your development environment. Eliminate context switching and manual SSH operations while maintaining full control over your testing infrastructure.

✨ Key Features

🖥️ Remote Machine Management

• Seamlessly add, configure, and manage remote machines via secure SSH connections
• Automatic platform detection (Windows/Linux) with intelligent credential management
• Secure password storage using VS Code's built-in secrets API
• Real-time connection status monitoring and health checks

⚡ Virtual Client Orchestration

• Execute Virtual Client workloads and experiments on single or multiple remote machines
• Stream real-time execution logs directly to VS Code output channels
• Automatic package deployment and extraction on remote hosts
• Support for custom profiles, parameters, and command-line configurations

📋 Experiment Template System

• Create reusable experiment templates with single-role or multi-role configurations
• Visual template builder with JSON schema validation
• Support for complex experiment orchestration with dependencies and sequencing
• Template versioning and sharing across teams

📊 Advanced Monitoring & Logging

• Real-time log streaming with syntax highlighting and filtering
• Automatic log collection and local archival post-execution
• Hierarchical log organization by machine, run, and timestamp
• Export and share logs for collaborative troubleshooting

🏗️ Rack-Based Organization

• Group machines into logical racks for coordinated experiments
• Execute synchronized workloads across rack members
• Simplified management of large-scale test environments
• Role-based machine assignment for distributed testing

🔧 Developer-Friendly Tooling

• Intuitive tree view interface for all operations
• Rich webview forms for configuration and setup
• Command palette integration for keyboard-driven workflows
• Extensible architecture for custom integrations

📋 Prerequisites

Before installing the extension, ensure you have:

Required

• Visual Studio Code: Version 1.96.0 or higher
• Remote Machines: Accessible via SSH with password authentication
• Virtual Client Package: Official Virtual Client distribution (.zip format)
• Network Access: Stable SSH connectivity to target machines

Remote Machine Requirements

• Windows: PowerShell 5.1+ (recommended for full feature support)
• Linux: Bash shell with standard utilities (unzip, tar, etc.)
• SSH Server: OpenSSH or compatible SSH daemon
• Disk Space: Sufficient space for Virtual Client packages and logs (typically 500MB-2GB)

Optional but Recommended

• Git installed on your development machine
• Familiarity with Virtual Client profiles and workloads
• Basic understanding of SSH and remote system administration

🚀 Getting Started

Installation

Option 1: Install from Repository (Recommended)

1. Download the latest virtual-client-0.0.2.vsix from the repository
2. Open VS Code
3. Navigate to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
4. Click the ... menu → Install from VSIX...
5. Select the downloaded .vsix file

Option 2: Build from Source

# Clone the repository
git clone https://dev.azure.com/msazure/One/_git/CRC-VirtualClient-VSCode-Extension
cd CRC-VirtualClient-VSCode-Extension

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package the extension
npx vsce package

# Install the generated .vsix file in VS Code

Quick Start Guide

1️⃣ Add Your First Remote Machine

• Open the Machines view in the activity bar (Virtual Client icon)
• Click the "+" button to add a new machine
• Fill in the connection details:
  • Label: A friendly name for your machine (e.g., "Production Test Server")
  • IP Address/Hostname: The SSH endpoint
  • Username: SSH login username
  • Password: SSH password (stored securely)
  • Platform: Auto-detected or manually specified (Windows/Linux)
• Click Submit to save and test the connection

2️⃣ Execute Your First Workload

• Right-click on your machine in the tree view
• Select "Run Virtual Client"
• Configure the run parameters:
  • Package Path: Full path to your Virtual Client .zip file
  • Profile: Virtual Client profile name (e.g., PERF-CPU-OPENSSL.json)
  • System: Target system identifier
  • Additional Parameters: Any custom command-line arguments
• Click Start Run
• Monitor progress in the Virtual Client Runs view
• View real-time logs in the Output panel

3️⃣ Create an Experiment Template

• Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
• Type "Virtual Client: Create Experiment Template"
• Choose a template type:
  • Single Role: For standalone experiments
  • Multi-Role: For distributed client-server scenarios
• Configure roles, steps, and machine assignments
• Save and reuse templates across similar experiments

4️⃣ Organize with Racks (Optional)

• For large-scale testing, create racks to group related machines
• Right-click in the Machines view → "Add Rack"
• Assign machines to racks for coordinated experiment execution

🔧 Development

Build Commands

# Install all dependencies
npm install

# Compile TypeScript to JavaScript
npm run compile

# Watch mode for active development (auto-recompile on changes)
npm run watch

# Lint code for style and quality issues
npm run lint

Testing

# Run the complete test suite
npm test

# Run tests with coverage report
npm run test:coverage

# Run specific test suite
npm test -- --grep "addMachine"

# Run tests in watch mode during development
npm run test:watch

Packaging & Distribution

# Package the extension into a .vsix file
npx vsce package

# Validate package before distribution
npx vsce ls

# Preview the extension locally
code --install-extension virtual-client-0.0.2.vsix

Debugging

1. Open the project in VS Code
2. Press F5 to launch the Extension Development Host
3. Set breakpoints in your TypeScript source files
4. Test your changes in the development instance

🏗️ Architecture

The extension is built on a clean, modular architecture designed for maintainability, testability, and extensibility:

Layered Architecture

┌─────────────────────────────────────────────────┐
│         Presentation Layer                      │
│  (UI Components, Webviews, Tree Providers)      │
├─────────────────────────────────────────────────┤
│         Domain Layer                            │
│  (Business Logic, Commands, Services)           │
├─────────────────────────────────────────────────┤
│         Infrastructure Layer                    │
│  (SSH, SFTP, Remote Execution, File I/O)        │
├─────────────────────────────────────────────────┤
│         Shared Layer                            │
│  (Utilities, Constants, Type Definitions)       │
└─────────────────────────────────────────────────┘

Key Components

• Presentation Layer (src/ui/, src/webviews/):

  • VS Code tree views, webview panels, and user notifications
  • Rich UI for configuration and monitoring

• Domain Layer (src/commands/, src/services/):

  • Core business logic for workload execution
  • Experiment orchestration and template management
  • Machine and rack lifecycle management

• Infrastructure Layer (src/infrastructure/, src/core/ssh/):

  • SSH/SFTP communication protocols
  • Remote file transfer and execution
  • Platform-specific command adapters

• Shared Layer (src/shared/):

  • Pure utility functions and type definitions
  • Constants and configuration management
  • Error handling and logging utilities

Design Principles

• Separation of Concerns: Clear boundaries between layers
• Dependency Inversion: High-level modules don't depend on low-level details
• Testability: Each layer can be tested independently
• Extensibility: Easy to add new workloads, platforms, and features

For detailed architecture documentation, diagrams, and design decisions, see ARCHITECTURE.md.

📖 Key Workflows

Virtual Client Execution Workflow

The extension automates the complete lifecycle of remote Virtual Client execution:

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Package   │──→   │   Transfer   │──→   │   Extract   │
│   Upload    │      │   via SFTP   │      │   on Host   │
└─────────────┘      └──────────────┘      └─────────────┘
                                                    │
                                                    ▼
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  Download   │◀──   │   Execute    │──→   │   Monitor   │
│    Logs     │      │   Workload   │      │   Realtime  │
└─────────────┘      └──────────────┘      └─────────────┘

1. Package Upload: Transfer Virtual Client package to remote machine via secure SFTP
2. Extraction: Automatically unzip package in dedicated run directory
3. Execution: Launch Virtual Client with specified profile, parameters, and configurations
4. Monitoring: Stream stdout/stderr logs to VS Code output channel in real-time
5. Log Collection: Download, compress, and archive logs locally after completion
6. Cleanup: Optional removal of remote artifacts to free up disk space

Experiment Management Workflow

Orchestrate complex, multi-machine experiments with ease:

Define Template → Assign Machines → Configure Steps → Execute → Analyze

1. Define: Create experiment template with roles, steps, and dependencies
2. Configure: Assign physical machines to logical roles (client, server, observer, etc.)
3. Validate: Pre-execution validation of connectivity and prerequisites
4. Execute: Run experiment steps sequentially or in parallel across all machines
5. Monitor: Real-time progress tracking with step-by-step status updates
6. Collect: Aggregate logs from all participants into organized archives
7. Review: Analyze results with integrated log viewers and export tools

🔐 Authentication & Security

Current Support

• SSH Password Authentication: Full support with secure credential storage via VS Code Secrets API
• Credential Management: Passwords encrypted and stored locally, never logged or transmitted insecurely
• Platform Detection: Automatic detection minimizes credential exposure

Planned Enhancements

• SSH Key Authentication: Coming in future releases
• Certificate-Based Auth: Support for enterprise PKI scenarios
• Multi-Factor Authentication: Integration with MFA providers

Security Best Practices

• Use dedicated service accounts with minimal required permissions
• Regularly rotate SSH credentials
• Restrict SSH access to known IP ranges when possible
• Monitor extension logs for unusual activity

🖥️ Platform Support

Remote Target Machines

• Windows Server (2016, 2019, 2022): ✅ Full support (recommended)
• Windows 10/11: ✅ Full support
• Ubuntu Linux (18.04, 20.04, 22.04): ✅ Full support
• CentOS/RHEL (7.x, 8.x): ✅ Full support
• Other Linux Distributions: ⚠️ Partial support (basic functionality)

Development Environment

• Windows (10, 11): ✅ Fully tested
• macOS (11+): ✅ Fully tested
• Linux (Ubuntu, Fedora): ✅ Fully tested

Known Limitations

• SSH Keys: Not yet supported; use password authentication
• Proxy Environments: Direct SSH connections required (SOCKS/HTTP proxy support planned)
• IPv6: Full support; IPv4 required for legacy systems

🤝 Contributing

This project is maintained by the CRC (Cloud Reliability & Compute) team and welcomes contributions from the community.

Contribution Guidelines

1. Coding Standards:

   • Follow TypeScript best practices and existing code style
   • Reference .github/copilot-instructions.md for project-specific guidelines
   • Use ESLint and Prettier for consistent formatting

2. Testing Requirements:

   • Write unit tests for all new features and bug fixes
   • Maintain or improve code coverage (aim for >80%)
   • Ensure all existing tests pass before submitting PRs
   • Add integration tests for complex workflows

3. Pull Request Process:

   • Fork the repository and create a feature branch
   • Write clear, descriptive commit messages
   • Update documentation for user-facing changes
   • Request review from maintainers
   • Address feedback promptly and professionally

4. Architecture Alignment:

   • Follow the layered architecture described in ARCHITECTURE.md
   • Keep components modular and testable
   • Avoid introducing new dependencies without discussion
   • Document design decisions for significant changes

Areas for Contribution

• 🐛 Bug Fixes: Help us squash bugs and improve stability
• ✨ New Features: Propose and implement new capabilities
• 📚 Documentation: Improve guides, tutorials, and code comments
• 🧪 Testing: Expand test coverage and add edge case tests
• 🎨 UI/UX: Enhance user experience and visual design
• 🌍 Localization: Add support for additional languages

Getting Help

• Review existing issues and pull requests
• Join our team discussions (internal to CRC team)
• Reach out to maintainers listed in owners.txt

📄 License

This project is licensed under the MIT License - see the LICENSE file for full details.

📚 Resources & Documentation

Official Documentation

• 📖 Virtual Client Official Docs - Comprehensive Virtual Client documentation
• 🔧 VS Code Extension API - VS Code extension development guide
• 🏗️ Architecture Guide - Detailed architecture and design documentation
• 🧪 Experiment Builder Guide - Creating and managing experiments

Quick Links

• 🐛 Report an Issue
• 💡 Request a Feature
• 📊 Project Roadmap - Upcoming features and improvements
• 👥 Team & Maintainers - Project owners and contacts

Community & Support

• 💬 Internal Support: Reach out to the CRC team via Teams
• 📧 Email: Contact maintainers listed in owners.txt
• 🎓 Training: Internal workshops and onboarding sessions available