Runs as a Moxxy plugin, connecting to the gateway's REST API and SSE event stream. Renders a 2D pixel-art office where each agent appears as an animated character - walking to desks, typing while running tasks, and idling when waiting for work.

Features

• Virtual office - pixel-art 2D environment with desk pods, conference table, and aisles rendered via Phaser 3
• Live agent visualization - agents animate in real time: walking, sitting, typing at desks based on their execution state
• Agent management - create, delete, and monitor agents from the sidebar
• Task execution - launch runs, stream results, and watch agents work with real-time SSE updates
• Chat & mission log - view agent conversation history, tool calls, and execution steps
• Command launcher - send commands to agents directly from the UI
• Agent graveyard - historical snapshots of completed/terminated agents with full chat and log history
• Connection monitoring - live connection status with automatic reconnection and exponential backoff
• Color-coded agents - 6 distinct color palettes for visual differentiation

Install

moxxy plugin install @moxxy/virtual-office-plugin

Usage

# Start the virtual office
moxxy plugin start @moxxy/virtual-office-plugin

# Or use the interactive plugin menu
moxxy plugin

The virtual office opens at http://localhost:17901. Navigate to Settings to configure your gateway URL and API token if they aren't injected automatically.

Development

Requires Node.js 22+ and npm.

git clone <repo>
cd virtual-office-plugin
npm install
npm run dev

The dev server starts on port 17901 with a proxy that forwards /v1/* requests to the gateway at localhost:3000.

Build

npm run build

Produces a production bundle in dist/.

Preview production build

npm run plugin:start

Serves the built dist/ directory using a zero-dependency static server.

Testing

npm run test              # Unit tests
npm run test:watch        # Watch mode
npm run test:integration  # Integration tests
npm run test:e2e          # Playwright end-to-end tests

How it works

The plugin is a single-page application built with React 19, Phaser 3, and Zustand. At runtime it ships pre-built static assets and a lightweight Node.js file server (serve.js) - no build tools or framework dependencies are required.

When started by the Moxxy CLI, the plugin receives environment variables (MOXXY_API_URL, MOXXY_TOKEN, PORT) and serves the virtual office on the allocated port. The app subscribes to the gateway's SSE event stream and maps agent state changes to character animations in the Phaser scene.

Architecture

┌─────────────────────────────────────────────────────┐
│                    App.tsx                           │
│  ┌──────────┐  ┌────────────────┐  ┌─────────────┐ │
│  │  Agent   │  │    Phaser      │  │   Agent     │ │
│  │ Sidebar  │  │ OfficeScene    │  │  Detail     │ │
│  │ (left)   │  │  (center)      │  │  Panel      │ │
│  └──────────┘  └────────────────┘  │  (right)    │ │
│                                    └─────────────┘ │
└────────────────────┬────────────────────────────────┘
                     │
              ┌──────┴──────┐
              │ WorldStore  │  Zustand - agents, chat, missions
              └──────┬──────┘
                     │
              ┌──────┴──────┐
              │EventAdapter │  Maps SSE events → state updates
              └──────┬──────┘
                     │ SSE / REST
              ┌──────┴──────┐
              │  Gateway    │  Moxxy gateway API
              │  Client     │
              └─────────────┘

Environment variables

Set automatically when launched via moxxy plugin start:

| Variable | Description | |---|---| | MOXXY_API_URL | Gateway base URL (e.g. http://localhost:3000) | | MOXXY_TOKEN | API bearer token | | PORT | Port to serve the virtual office on | | MOXXY_PLUGIN_NAME | Plugin package name (@moxxy/virtual-office-plugin) | | MOXXY_PLUGIN_PORT | Allocated port (same as PORT) | | MOXXY_HOME | Moxxy data directory (default ~/.moxxy) | | VITE_MOXXY_API_URL | Gateway URL exposed to browser code during development | | VITE_MOXXY_TOKEN | API token exposed to browser code during development |

Links

• Documentation
• Website
• GitHub

License

Dual-licensed under MIT or Apache 2.0 at your option.