Skip to content

USER_GUIDE.md

Latest commit

 

History

History
764 lines (546 loc) · 20.9 KB

USER_GUIDE.md

File metadata and controls

764 lines (546 loc) · 20.9 KB

Virtual Office - User Guide

Version: 1.0 Last Updated: February 7, 2026

Welcome to Virtual Office, the visual monitoring dashboard for your AIOS AI agent team. This guide will help you get started and make the most of Virtual Office's features.

Table of Contents

  1. Introduction
  2. Installation
  3. Quick Start
  4. Features Overview
  5. User Interface Guide
  6. Troubleshooting
  7. FAQ

Introduction

What is Virtual Office?

Virtual Office transforms abstract AIOS agent orchestration into a concrete, visual experience. Instead of reading text logs, you can watch your AI agents (dev, qa, architect, pm, po, sm, analyst, devops, data-engineer, ux-design-expert) working in real-time in a virtual office environment.

Key Benefits

  • Visual Clarity: See which agents are active at a glance
  • Real-Time Monitoring: Watch agent activity as it happens
  • Multi-Project Support: Manage multiple AIOS projects from one dashboard
  • Activity Insights: Deep dive into agent operations with detailed logs
  • Export & Analysis: Export activity data for analysis or reporting

System Requirements

Minimum Requirements:

  • Operating System: macOS 11+, Windows 10+, or Linux (Ubuntu 20.04+)
  • Node.js: Version 18.0.0 or higher
  • npm: Version 9.0.0 or higher
  • AIOS Framework: Version 2.0 or higher
  • RAM: 4GB minimum (8GB recommended)
  • Display: 1920x1080 resolution recommended

Supported Browsers (for web version):

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Installation

Option 1: Web Application (Recommended for Quick Start)

  1. Visit the Virtual Office web app at: https://virtual-office.synkra.com
  2. Sign in or create an account
  3. Follow the onboarding wizard to connect your first AIOS project

No installation required!

Option 2: Local Installation (For Development)

Prerequisites Check

First, verify your system has the required software:

# Check Node.js version
node --version  # Should show v18.0.0 or higher

# Check npm version
npm --version   # Should show 9.0.0 or higher

# Verify AIOS installation
which aios      # Should return a path if AIOS is installed

Installation Steps

  1. Clone the Repository
git clone https://github.com/synkra/virtual-office.git
cd virtual-office
  1. Install Dependencies
npm install

This will install all dependencies for frontend, backend, and shared packages.

  1. Configure Environment
# Copy example environment file
cp backend/.env.example backend/.env

# Edit backend/.env with your settings
# Example:
# PORT=3001
# FRONTEND_URL=http://localhost:3000
# AIOS_WS_URL=ws://localhost:8080
  1. Start the Application
# Start both frontend and backend
npm run dev

The application will be available at:

macOS Installation

# Using Homebrew (if Node.js not installed)
brew install node@18

# Clone and install Virtual Office
git clone https://github.com/synkra/virtual-office.git
cd virtual-office
npm install
npm run dev

Windows Installation

# Install Node.js from https://nodejs.org/
# Then in PowerShell or Command Prompt:

git clone https://github.com/synkra/virtual-office.git
cd virtual-office
npm install
npm run dev

Linux Installation (Ubuntu/Debian)

# Install Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clone and install Virtual Office
git clone https://github.com/synkra/virtual-office.git
cd virtual-office
npm install
npm run dev

Quick Start

Your First 5 Minutes with Virtual Office

Step 1: Launch Virtual Office

Step 2: Connect Your First AIOS Project

[Screenshot: Add Project Dialog]

  1. Click the "Add Project" button in the top-right corner

  2. Choose one of the following methods:

    • Auto-Detect: Click "Scan for AIOS Projects" to find projects automatically
    • Manual Entry: Enter the full path to your AIOS project directory
    • Browse: Click "Browse" to navigate to your project folder

  3. Virtual Office will detect the AIOS version and verify the project

  4. Click "Connect" to add the project

Step 3: View Your Agent Team

[Screenshot: Agent Grid View with Agents Online/Offline]

Once connected, you'll see the virtual office with all AIOS agents:

  • Online Agents (green glow): Currently active in your project
  • Offline Agents (gray): Not currently active
  • Agent Monitors: Display recent activity when agents are working

Step 4: Monitor Agent Activity

[Screenshot: Agent Monitor showing activity feed]

When agents are active, their monitors display:

  • Code snippets being written
  • Bash commands being executed
  • Files being read or modified
  • Tool calls and API operations

Activity updates appear in real-time with smooth animations.

Step 5: Deep Dive with Detail Panel

[Screenshot: Agent Detail Panel]

  1. Click on any agent workspace to open the detail panel
  2. View the complete activity history (last 50 operations)
  3. Use filters to find specific operations
  4. Copy logs or export to JSON/CSV for analysis

Congratulations! You're now monitoring your AIOS agents in Virtual Office.

Features Overview

Core Features (Open Source)

1. Agent Status Visualization

What it does: Shows which agents are currently online/offline

How to use:

  • Agents appear "seated" at their desks when active
  • Empty chairs indicate offline agents
  • Hover over agents to see status tooltips

Tips:

  • Green glow = Agent is working
  • Agent name and role displayed below workspace
  • Visual cues update instantly when agents start/stop

2. Real-Time Activity Monitoring

What it does: Displays agent operations on their monitors as they happen

How to use:

  • Watch monitors automatically update as agents work
  • Activity feed shows last 5-10 operations per agent
  • Different colors indicate operation types:
    • Blue: Code operations
    • Yellow: Bash commands
    • Green: File operations
    • Purple: Tool calls

Activity Types:

  • Code: Code snippets being written or analyzed
  • Command: Bash/shell commands being executed
  • File Operation: Reading, writing, or modifying files
  • Tool Call: API calls, database queries, external tools

3. Agent Detail Panel

What it does: Provides deep inspection of agent activity

How to use:

  1. Click any agent workspace to open the panel
  2. Panel slides in from the right side
  3. View full activity history with timestamps
  4. Scroll through past operations
  5. Close with X button, ESC key, or clicking outside

Panel Sections:

  • Header: Agent name, role, and activity count
  • Activity Log: Timestamped list of all operations
  • Footer: Copy and close buttons

Keyboard Shortcuts:

  • ESC - Close panel
  • Ctrl/Cmd + C - Copy visible log
  • Tab - Navigate within panel

4. Activity Filtering & Search

What it does: Helps you find specific operations quickly

How to use:

  1. Open agent detail panel
  2. Use filter controls at the top:
    • Type Filter: Select operation type (Code, Command, File Op, Tool Call, All)
    • Time Range: Last hour, last day, all time
    • Search: Type keywords to find in activity content

Tips:

  • Filters work in real-time as you type
  • Keyword search highlights matching text
  • "Clear Filters" button resets all filters
  • Filters persist when switching between agents

5. Activity Export

What it does: Exports activity logs for external analysis

How to use:

  1. Open agent detail panel
  2. Click "Export" button
  3. Choose format:
    • JSON: Structured data for programmatic analysis
    • CSV: Spreadsheet-compatible format

Export Options:

  • Export respects current filters (only exports visible activities)
  • Filename format: virtual-office-activity-{agent}-{date}.{format}
  • Files download automatically to your Downloads folder

Use Cases:

  • Performance analysis
  • Audit trails
  • Team reporting
  • Debugging workflows

Enterprise Features

6. Multi-Project Workspace (Enterprise)

What it does: Manage multiple AIOS projects from one dashboard

How to use:

  1. Click project dropdown in header
  2. Select different projects to switch between them
  3. Add multiple projects via "Add Project" button
  4. Rename, archive, or remove projects in project management

[Screenshot: Project Switcher Dropdown]

Features:

  • Unlimited projects (vs 1 in Open Source)
  • Quick switching between projects
  • Last-active project remembered
  • Project-specific activity isolation

7. Team Collaboration View (Enterprise)

What it does: Aggregate view across all team projects

How to use:

  1. Select "Team View" from project switcher
  2. View metrics:
    • Total agents active across all projects
    • Tasks completed today
    • Most active agents
  3. Click any project to drill down to detailed view

Benefits:

  • Team productivity insights
  • Cross-project resource monitoring
  • Manager dashboard for team oversight

8. Advanced Filtering (Enterprise)

What it does: More powerful search and filter options

Additional Features:

  • Regular expression search
  • Multi-type filtering (select multiple types)
  • Custom date ranges
  • Save filter presets
  • Agent-to-agent comparison

User Interface Guide

Main Screen Layout

[Screenshot: Main Virtual Office View - Labeled]

  1. Header Bar (Top)

    • Virtual Office logo
    • Project switcher dropdown
    • Add Project button
    • Settings icon
    • User profile menu

  2. Agent Grid (Center)

    • Visual workspace showing all agents
    • Isometric 2D rendering
    • Agents arranged by role:
      • Left: Development agents (dev, architect)
      • Center: Quality & Process (qa, pm, po, sm)
      • Right: Specialists (analyst, devops, data-engineer, ux-design-expert)

  3. Status Bar (Bottom)

    • Connection status (AIOS connection indicator)
    • Active agents count
    • Last activity timestamp

Agent Workspace Components

[Screenshot: Single Agent Workspace - Labeled]

Each agent workspace consists of:

  1. Desk: Base of the workspace (isometric desk graphic)
  2. Monitor: Displays activity feed when agent is active
  3. Chair: Empty when offline, occupied when online
  4. Name Plate: Agent name and role below workspace
  5. Status Indicator: Green glow (online) or gray (offline)

Agent Detail Panel

[Screenshot: Agent Detail Panel - Labeled]

Header:

  • Agent name and avatar
  • Current role
  • Activity count badge
  • Close button (X)

Activity Log Section:

  • Scrollable list of operations
  • Each entry shows:
    • Timestamp (relative or absolute)
    • Operation type icon and label
    • Content preview or full text
    • File path (if applicable)
  • Infinite scroll for older activities

Filter Bar:

  • Operation type dropdown
  • Time range selector
  • Keyword search input
  • Clear filters button

Footer:

  • Copy log button
  • Export button (with format selector)

Settings Screen

[Screenshot: Settings Screen]

Access via gear icon in header.

Sections:

  1. Connection Settings

    • AIOS WebSocket URL
    • Connection timeout
    • Auto-reconnect toggle

  2. Project Directories

    • Add/remove directories to scan for AIOS projects
    • Rescan button

  3. Appearance

    • Theme selector (Light/Dark/Auto)
    • Animation speed (Reduced motion for accessibility)
    • Font size

  4. Notifications

    • Desktop notifications toggle
    • Alert on agent failures
    • Sound effects toggle

  5. License (Enterprise)

    • Current tier (Open Source / Enterprise)
    • License key input
    • Expiration date
    • Upgrade link

  6. Data & Privacy

    • Activity retention period (default: 30 days)
    • Clear activity history button
    • Export all data button

Troubleshooting

Connection Issues

Problem: "Cannot connect to AIOS"

Symptoms:

  • Virtual Office shows "Disconnected" status
  • No agents appear online even when AIOS is running

Solutions:

  1. Verify AIOS is running

    # Check if AIOS process is active
ps aux | grep aios

  2. Check AIOS WebSocket URL

    • Go to Settings > Connection Settings
    • Verify URL matches your AIOS configuration
    • Default: ws://localhost:8080

  3. Check firewall settings

    • Ensure port 8080 (or your configured port) is not blocked
    • On macOS: System Preferences > Security & Privacy > Firewall
    • On Windows: Windows Defender Firewall > Allow an app

  4. Restart backend server (if running locally)

    cd backend
npm run dev

Problem: "WebSocket connection lost"

Symptoms:

  • Virtual Office connected successfully but then disconnected
  • Frequent reconnection attempts

Solutions:

  1. Check network stability

    • Ensure stable internet/local network connection

  2. Increase timeout settings

    • Settings > Connection Settings
    • Increase "Connection Timeout" to 60 seconds

  3. Check AIOS logs

    tail -f ~/.aios/logs/agent.log

  4. Update to latest version

    cd virtual-office
git pull
npm install
npm run dev

Performance Issues

Problem: "UI is slow or choppy"

Symptoms:

  • Agent animations stutter
  • UI takes long to respond to clicks
  • High CPU usage

Solutions:

  1. Enable reduced motion

    • Settings > Appearance > Animation Speed: Reduced

  2. Close detail panel when not needed

    • Panel rendering can be CPU-intensive with many activities

  3. Clear old activity history

    • Settings > Data & Privacy > Clear Activity History
    • This removes activities older than 30 days

  4. Reduce active agents

    • Only run agents you need in AIOS

  5. Check system resources

    # Check CPU and memory usage
top    # macOS/Linux
# or Task Manager on Windows

Problem: "Activity log loads slowly"

Symptoms:

  • Opening detail panel takes several seconds
  • Scrolling through activities is slow

Solutions:

  1. Use filtering

    • Filter by type or time range to reduce data loaded

  2. Export and clear old data

    • Export activities for archival
    • Clear old activity history in settings

  3. Database optimization (local installation)

    # Vacuum SQLite database
sqlite3 ~/.virtual-office/virtual-office.db "VACUUM;"

Display Issues

Problem: "Agent workspaces look distorted"

Symptoms:

  • Agents appear stretched or compressed
  • Layout doesn't fit screen properly

Solutions:

  1. Adjust browser zoom

    • Reset zoom to 100% (Ctrl/Cmd + 0)

  2. Check minimum resolution

    • Virtual Office optimized for 1920x1080 or higher
    • Use fullscreen mode on smaller displays

  3. Clear browser cache

    • Chrome: Settings > Privacy and security > Clear browsing data
    • Firefox: Preferences > Privacy & Security > Clear Data

  4. Update browser

    • Ensure using Chrome 90+, Firefox 88+, or Safari 14+

Data Issues

Problem: "Activity history is missing"

Symptoms:

  • Detail panel shows no activities even though agents were working
  • Activities disappeared after restart

Solutions:

  1. Check data retention settings

    • Settings > Data & Privacy > Activity retention period
    • Data older than retention period is auto-deleted

  2. Verify database file (local installation)

    # Check if database exists
ls -lh ~/.virtual-office/virtual-office.db

  3. Restore from backup (if available)

    # Backups stored in:
ls ~/.virtual-office/backups/

  4. Check WebSocket connection

    • If disconnected, activities won't be logged
    • Verify connection status in bottom status bar

FAQ

General Questions

Q: Is Virtual Office free? A: Yes! Virtual Office has an Open Source version with core features available for free. We also offer an Enterprise version with advanced features like multi-project support and team collaboration.

Q: Do I need AIOS to use Virtual Office? A: Yes. Virtual Office is a monitoring dashboard for AIOS agents. You need AIOS Framework 2.0 or higher installed and running.

Q: Can I use Virtual Office with multiple AIOS projects? A: Multi-project support is an Enterprise feature. The Open Source version supports one project at a time. You can switch projects, but only monitor one at a time.

Q: Does Virtual Office work offline? A: Virtual Office requires a connection to your AIOS instance to display real-time activity. However, historical activity data is stored locally and can be viewed offline.

Q: What data does Virtual Office collect? A: Virtual Office stores activity logs locally on your machine. We do not transmit your code or project data to external servers. See our Privacy Policy for details.

Technical Questions

Q: Which AIOS versions are supported? A: Virtual Office supports AIOS Framework version 2.0 and higher. Check your AIOS version with aios --version.

Q: Can I run Virtual Office on a remote server? A: Yes. The backend can run on a server and multiple users can connect via the web interface. See the Developer Guide for deployment instructions.

Q: What's the difference between web and local installation? A: The web version is hosted and ready to use. Local installation gives you more control, works offline, and is useful for development or custom deployments.

Q: How much disk space does activity history use? A: Activity logs are stored in a SQLite database. Typical usage is 10-50 MB per project per month. Old data is auto-deleted after 30 days (configurable).

Q: Can I export my data? A: Yes. You can export activity logs via the Export button in the detail panel (JSON or CSV format). You can also export all data via Settings > Data & Privacy.

Features Questions

Q: Why are some agents always offline? A: Agents only appear online when actively executing tasks in your AIOS project. If an agent isn't needed for current work, it will show as offline.

Q: Can I customize agent avatars or workspace colors? A: Currently, agent appearance is standardized by role. Custom avatars are planned for a future release.

Q: How do I search for specific code snippets in activity history? A: Open the agent detail panel, use the keyword search filter to find text within activity logs. Enterprise users have regex search for advanced patterns.

Q: Can I get notifications when specific agents start working? A: Enable desktop notifications in Settings > Notifications. You can configure alerts for agent activation, failures, or specific operation types.

Q: What's the maximum number of projects I can monitor? A: Open Source: 1 active project at a time (can switch between saved projects). Enterprise: Unlimited projects.

Troubleshooting Questions

Q: Virtual Office says "AIOS not detected", but I have AIOS installed. What should I do? A:

  1. Verify AIOS is running: ps aux | grep aios
  2. Check the AIOS WebSocket URL in Settings
  3. Ensure AIOS version 2.0+: aios --version
  4. Check project path has .aios-core/ directory

Q: Activity updates are delayed by 5-10 seconds. Is this normal? A: No. Updates should appear within 2 seconds. Check:

  1. WebSocket connection status (should show "Connected")
  2. Network latency if using remote AIOS
  3. System resources (high CPU usage can cause delays)

Q: Can I recover deleted activity history? A: If you have database backups enabled, you can restore from ~/.virtual-office/backups/. Otherwise, deleted activity cannot be recovered.

Q: Virtual Office won't start after updating. Help? A:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
npm run dev

# If still failing, check for port conflicts:
lsof -i :3000  # Frontend
lsof -i :3001  # Backend

Additional Resources

Documentation

  • Developer Guide: Technical setup and architecture
  • API Reference: WebSocket protocol and events
  • PRD: Product requirements and roadmap

Support

Community

  • Discord: Join our community server (link in README)
  • Twitter: Follow @SynkraAIOS for updates
  • Blog: https://synkra.com/blog

Next Steps

Now that you understand the basics:

  1. Explore Features: Try all the functionality described in this guide
  2. Customize Settings: Adjust appearance and notifications to your preference
  3. Learn Workflows: Read the Developer Guide to understand the architecture
  4. Join Community: Connect with other users in our Discord server
  5. Provide Feedback: Help us improve by sharing your experience

Happy monitoring!

Virtual Office User Guide v1.0 © 2026 Synkra AIOS Team. Licensed under MIT License.