KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #macos #ai-agent #deepseek-harness #open-source

my-virtual-office

★ 322 Open GitHub ↗

A self-hosted 2D AI workspace for AI Agents

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# My Virtual Office

🌐 **[myvirtualoffice.ai](https://myvirtualoffice.ai/)**

A self-hosted 2D AI workspace for AI Agents. Turn invisible agent work into a living, breathing office.

![My Virtual Office](https://raw.githubusercontent.com/eliautobot/my-virtual-office/main/screenshot.png)

## What Is It?

Virtual Office gives your AI agents a physical presence. Instead of watching logs scroll by, you see agents walking between desks, grabbing coffee, sitting in meetings, and chatting in a charming 2D style office that runs in your browser.

It connects to supported agent harnesses and visualizes what your agents are doing in real time.

## Supported Agent Harnesses

### OpenClaw

Virtual Office connects to OpenClaw through the OpenClaw gateway and the mounted OpenClaw home directory. The gateway provides live chat and activity events, while the home directory lets Virtual Office discover agents, read safe profile metadata, load model settings, and surface workspace tools in the UI.

For Docker deployments, mount your OpenClaw home directory into the container and set `VO_OPENCLAW_PATH`, `VO_GATEWAY_URL`, and `VO_GATEWAY_HTTP` when the defaults do not match your setup. Virtual Office automatically translates host workspace paths recorded by the Gateway into the container mount. If the host OpenClaw home cannot be inferred from `openclaw.json`, set `VO_OPENCLAW_GATEWAY_PATH` to the absolute OpenClaw home path as seen by the Gateway.

### Hermes Agents

Virtual Office connects to Hermes as an external client of Hermes' authenticated API Server. Hermes itself owns each profile, gateway process, tools, sessions, credentials, model configuration, and terminal environment. Virtual Office uses `/v1/runs`, SSE events, approvals, stops, and the documented session API; it never starts Hermes or runs the Hermes CLI inside the Virtual Office container.

Run one native Hermes gateway per profile and add one connection per gateway in **Settings → Integrations → Hermes**. Each connection has a stable ID, display name, API URL, and `API_SERVER_KEY`. Docker deployments commonly use `http://host.docker.internal:<port>`; host-network deployments can use `http://127.0.0.1:<port>`. You may also supply the repeatable connection list through `VO_HERMES_CONNECTIONS_JSON`. Do not mount the Hermes home directory or CLI into Virtual Office.

Virtual Office also ships a Hermes Messaging Gateway platform plugin under `integrations/hermes-platform/my_virtual_office/`. This is a different mode: Hermes gateway connects to Virtual Office as a messaging platform, so the `Hermes Gateway` office agent can receive queued Virtual Office messages and post replies back into visible office chat. Configure `VO_HERMES_PLATFORM_TOKEN` on Virtual Office, copy the plugin into `~/.hermes/plugins/my_virtual_office/`, set `MY_VIRTUAL_OFFICE_URL` and `MY_VIRTUAL_OFFICE_TOKEN` for Hermes, then run `hermes gateway`.

### Codex

Virtual Office can create Codex-backed office agents when the Codex CLI is available to the app. Chat uses Codex's native `codex app-server` JSON-RPC protocol for thread start/resume, live progress, approval requests, and interrupt support. `codex exec` is retained only as an explicit compatibility fallback.

Discovery includes Virtual Office-created Codex agents, Codex's standard `$CODEX_HOME/agents/*.toml` custom agents, and a synthesized `Main` entry for the default Codex root agent. Newly created Virtual Office Codex agents can use the default Codex agents directory or a custom parent directory. Default-directory creation registers a native custom-agent TOML file under `$CODEX_HOME/agents` when `VO_CODEX_REGISTER_NATIVE_AGENTS=1`; custom-directory creation writes a project-local `.codex/agents/<profile>.toml` and keeps a small Virtual Office registry so the agent remains discoverable.

For Docker deployments, install Codex inside the container image or set `VO_CODEX_BIN` to a Codex executable path available inside the container. Set `VO_CODEX_HOME` to a deployment-specific Codex home so auth and config stay out of the repo and are not tied to any developer's machine. Useful variables: `VO_CODEX_BIN`, `VO_CODEX_HOME`, `VO_CODEX_WORKSPACE_ROOT`, `VO_CODEX_MAIN_WORKSPACE`, `VO_CODEX_INCLUDE_MAIN`, `VO_CODEX_INCLUDE_NATIVE_AGENTS`, `VO_CODEX_REGISTER_NATIVE_AGENTS`, `VO_CODEX_PREFER_APP_SERVER`, `VO_CODEX_SANDBOX`, and `VO_CODEX_APPROVAL_POLICY`. The Docker example defaults `VO_CODEX_SANDBOX` to `danger-full-access` because Codex's bubblewrap sandbox usually needs extra container privileges; set it to a stricter Codex sandbox mode when your deployment supports it.

### Claude Code

Virtual Office can create Claude Code-backed office agents when the Claude Code CLI is available to the app. Chat uses Claude Code's native non-interactive stream protocol, `claude -p --output-format stream-json --include-partial-messages`, so text deltas, tool calls, tool results, usage, session IDs, interrupts, and local Virtual Office chat history work like the other native harness providers.

Discovery includes Virtual Office-created Claude Code agents, Claude Code's native `$CLAUDE_CONFIG_DIR/agents/*.md` subagents, and a synthesized `Main` entry for Claude Code's default workspace agent. Newly created Virtual Office Claude Code agents can use the default managed workspace root or a custom parent directory. Standard creation writes `AGENTS.md`, `CLAUDE.md`, project `.claude/agents/<profile>.md`, and, when `VO_CLAUDE_CODE_REGISTER_NATIVE_AGENTS=1`, a native `$CLAUDE_CONFIG_DIR/agents/<profile>.md` subagent file. Custom creation writes the project-local subagent file and a small Virtual Office registry entry so the agent remains discoverable.

For Docker deployments, install Claude Code inside the container image or set `VO_CLAUDE_CODE_BIN` to a Claude executable path available inside the container. Set `VO_CLAUDE_CODE_HOME` to a deployment-specific Claude config directory so auth and config stay out of the repo and are not tied to any developer's machine. Useful variables: `VO_CLAUDE_CODE_BIN`, `VO_CLAUDE_CODE_HOME`, `VO_CLAUDE_CODE_WORKSPACE_ROOT`, `VO_CLAUDE_CODE_MAIN_WORKSPACE`, `VO_CLAUDE_CODE_MODEL`, `VO_CLAUDE_CODE_PERMISSION_MODE`, `VO_CLAUDE_CODE_INCLUDE_MAIN`, `VO_CLAUDE_CODE_INCLUDE_NATIVE_AGENTS`, and `VO_CLAUDE_CODE_REGISTER_NATIVE_AGENTS`.

## Features

### 🏢 Live Office Canvas
- Real-time 2D style office with agents that walk, sit, work, and interact
- Agents move to their desks when working, wander when idle, visit the kitchen, lounge on the couch
- Smooth A* pathfinding with collision avoidance
- Wall occlusion: agents behind walls get naturally shadowed
- 100 FPS rendering with configurable canvas size

### 🎨 Full Office Editor
- Drag-and-drop furniture placement with snap-to-grid
- 25+ furniture items: desks, boss desk, meeting table, couches, bookshelves, whiteboards, filing cabinets, plants, vending machines, kitchen appliances, ping pong table, dart board, TV, and more
- Interior wall builder: create rooms, hallways, and departments with doors
- Wall color picker per section with accent and trim colors
- Floor tile color customization
- Rotation support for select furniture (couch)
- Text labels for naming rooms and areas
- **Layout Marketplace** tab with the bundled Default Office and a persistent personal layout library
- Select furniture, text labels, and walls as one group, save their exact arrangement, then place the group elsewhere
- Place layouts without replacing the current office, agents, branches, floor, or canvas settings
- Upload and download portable `.mvo-layout.json` files to share layouts between Virtual Office installations

### 👤 Agent Customization
- Full character appearance editor: skin tone, hair style/color, eye color, eyebrows
- Facial hair, glasses, headwear options
- Costumes (lobster suit, capes, etc.)
- Held items and desk accessories (coffee mug, envelope, clipboard, plant, etc.)
- Gender-aware sprite rendering
- Each agent gets a unique color tag and emoji

### 🐾 Office Pet
- Choose from Cat, Pug, or Lobster
- Realistic behavior: sleeping, sitting, grooming, wandering, greeting agents, investigating furniture
- Agents interact with the pet: petting (♥) and playful chasing
- Full pathfinding and collision avoidance, same as agents
- Directional walking sprites (front, back, side views) for cat and pug
- Custom naming: default pet is a lobster named Clawy

### 💬 Chat with Agents
- Click any agent to open a chat window
- Full markdown rendering with syntax highlighting
- Inline image support: send images and see thumbnails in the chat
- Click images for full-size lightbox view
- Voice input via Whisper STT (premium)
- File attachments with drag-and-drop or paste
- Audio file auto-transcription
- Streaming responses with live typing indicator
- Tool activity feed showing what the agent is doing (exec, read, write, search, etc.)
- Movable/snappable chat window with float mode
- Agent selector dropdown to switch between agents

### 📊 Dashboard Panel
- **PC Performance**: live CPU and RAM monitoring
- **API Usage**: track agent API calls and costs
- **Branch Management**: organize agents into departments/teams with color-coded borders
- **Agent Directory**: see all agents with live status (working, idle, meeting, break)
- **Activity Log**: real-time feed of office events

### 🌦️ Dynamic Environment
- **Interactive windows** with live weather pulled from your location
- **Day/night cycle**: ambient lighting shifts throughout the day
- **Animated furniture**: TV with 5 channels (sports, news, cooking, cartoon, movie) that agents walk over to watch
- **Clock** showing real time

### 📋 Meeting System
- 1-on-1 meetings: agents walk to each other's desks
- Group meetings: agents gather around the meeting table (10 seats, 5 per side)
- Meetings triggered by agent activity or manual scheduling
- Meeting status visible in dashboard

### 🏗️ Branch System
- Create departments (Engineering, Sales, Support, etc.)
- Color-coded wall sections per branch
- Agents assigned to branches with visual grouping
- Branch themes and emoji customization

### 🔧 Additional Tools (Premium)
- **Agent Browser**: embedded browser with live view, URL bar, and remote control
- **SMS Panel**: Twilio integration for SMS/phone from the office
- **Cron Manager**: schedule recurring agent tasks visually
- **Models Panel**: per-agent model switching from the UI
- **Whisper STT**: voice-to-text input in chat

## Quick Start

### Docker Compose (recommended)

```bash
git clone https://github.com/eliautobot/my-virtual-office.git
cd my-virtual-office
docker compose up -d
```

Then open `http://localhost:8090/setup` to run the setup wizard.

### Docker Image / Platform Support

The published Docker image is available at:
- `ghcr.io/eliautobot/my-virtual-office:latest`

Multi-arch images are published for:
- `linux/amd64`
- `linux/arm64`

That means the same image tag works on standard x86_64 machines and ARM64 devices like a Raspberry Pi 5.

### First Run

1. Open `http://localhost:8090/setup`
2. Follow the setup wizard to connect your OpenClaw instance, Hermes Agents, or both
3. Enter a license key or skip for demo mode
4. Customize your office, add agents, and watch them come to life

### Provider SDK

The built-in Provider SDK supports OpenClaw, Hermes, Codex CLI, Claude Code,
OpenCode, and Antigravity. Open **☰ Menu → Provider SDK** to configure
connections, models, permissions, native discovery, and active-session
behavior. The New Agent and Agent Desk screens use each provider's manifest
for native agent creation, allowlisted files, and AgentSkills.

CLI authentication remains native to each framework. For Docker deployments,
the CLI executable and any native home/config directory must be installed in
or mounted into the container, then mapped with the matching environment
variables below. Virtual Office does not copy or expose provider credentials.

## Remote Access and Security

**Recommended remote access: use [Tailscale](https://tailscale.com/).**

Virtual Office is a control surface for your local agent harnesses. If you want to reach it away from home, the safest default is to keep it on your private machine or LAN and access it over a private tailnet such as Tailscale.

### Recommended setup
- Keep Virtual Office bound to your local machine, LAN, or private tailnet
- Use Tailscale to reach the host remotely instead of opening router ports
- Keep your agent harnesses and Virtual Office behind trusted access controls
- Use strong device/account security on the machines that can reach your tailnet

### Warning
- **Do not expose Virtual Office directly to the public internet unless you fully understand and accept the security risk**
- Avoid simple port forwarding for ports `8090`, `8091`, or your agent harness gateways
- If someone can reach your Virtual Office deployment, they may be able to interact with a live control surface for your agents

This project is designed first for self-hosted local/private-network use. You are responsible for securing any remote deployment.

## Modes

### Free Demo
Works without a license key:
- Up to 3 agents
- Branch management
- Weather and day/night cycle
- Chat with any agent
- API usage monitoring
- Setup wizard

Demo mode shows a watermark and demo banner.

### Full License
Unlocks everything:
- Unlimited agents
- Full office editor and furniture
- Agent customization and appearance editor
- Office pet
- Agent Browser panel
- SMS / Twilio panel
- Cron Job Manager
- Whisper STT voice input
- No watermark or demo banner

### How to Activate
Activate during the setup wizard or later from **☰ Menu → Settings**.

License keys are provided after purchase and look like this:
```
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

Enter your key during setup or in **☰ Menu → Settings**. The key is validated once online with Lemon Squeezy, then works offline forever. Premium features unlock immediately and persist across restarts and updates.

## Configuration

All settings live in `vo-config.json`. Environment variables override config values.

| Variable | Default | Description |
|----------|---------|-------------|
| `VO_OFFICE_NAME` | Virtual Office | Office display name |
| `VO_PORT` | 8090 | HTTP server port |
| `VO_WS_PORT` | 8091 | WebSocket proxy port |
| `VO_GATEWAY_URL` | ws://127.0.0.1:18789 | OpenClaw gateway WebSocket URL |
| `VO_GATEWAY_HTTP` | http://127.0.0.1:18789 | OpenClaw gateway HTTP URL |
| `VO_OPENCLAW_PATH` | ~/.openclaw | Path to OpenClaw home directory |
| `VO_OPENCLAW_GATEWAY_PATH` | auto-detected | OpenClaw home path in the external Gateway's filesystem namespace |
| `VO_HERMES_ENABLED` | true | Enable native Hermes API connections |
| `VO_HERMES_CONNECTIONS_JSON` | `[]` | JSON list of native gateway connections (`id`, `name`, `apiUrl`, `apiKey`) |
| `VO_HERMES_TIMEOUT_SEC` | 600 | Timeout for Hermes API runs |
| `VO_HERMES_LOCAL_PROFILES_ENABLED` | false | Discover local Hermes profiles in `VO_HERMES_HOME` |
| `VO_HERMES_HOME` | /data/hermes-home | Hermes native home visible inside the container |
| `VO_HERMES_BIN` | hermes | Hermes executable visible inside the container |
| `VO_HERMES_PLATFORM_ENABLED` | false unless token is set | Enable the separate Hermes Messaging Gateway platform bridge |
| `VO_HERMES_PLATFORM_TOKEN` | *(none)* | Shared token required by the Hermes `my_virtual_office` platform plugin |
| `VO_HERMES_PLATFORM_AGENT_ID` | hermes-gateway | Office agent ID for the Hermes Messaging Gateway platform |
| `VO_CODEX_ENABLED` | true | Enable the Codex CLI adapter |
| `VO_CODEX_HOME` | /data/codex-home | Standalone Codex home visible inside the container |
| `VO_CODEX_BIN` | codex | Standalone Codex executable visible inside the container |
| `VO_CLAUDE_CODE_ENABLED` | true | Enable the Claude Code adapter |
| `VO_CLAUDE_CODE_HOME` | /data/claude-code-home | Claude Code native config directory |
| `VO_CLAUDE_CODE_BIN` | claude | Claude Code executable visible inside the container |
| `VO_OPENCODE_ENABLED` | false | Enable the OpenCode adapter |
| `VO_OPENCODE_CONFIG_DIR` | /data/opencode-config | OpenCode native config directory |
| `VO_OPENCODE_BIN` | opencode | OpenCode executable visible inside the container |
| `VO_ANTIGRAVITY_ENABLED` | false | Enable the Antigravity adapter |
| `VO_ANTIGRAVITY_HOME` | /data/antigravity-config | Antigravity native config directory |
| `VO_ANTIGRAVITY_BIN` | agy | Antigravity executable visible inside the container |
| `VO_STATUS_DIR` | /data | Directory for presence/status data inside the container. By default this is backed by the `vo-data` Docker volume. |
| `VO_WEATHER_LOCATION` | *(none)* | Weather location for window display |

## Updating

```bash
docker compose down
docker compose pull
docker compose up -d
```

Or pull the image directly:

```bash
docker pull ghcr.io/eliautobot/my-virtual-office:latest
```

Your license key, office layout, and all settings persist across updates. They're stored in the `vo-data` volume.

## Roadmap

- More office themes and skins
- Premium character packs and costumes
- More pet species and behaviors
- Agent-to-agent visible interactions
- Deeper IDE integrations
- More idle activities and office events

## License

GNU Affero General Public License v3.0 or later (`AGPL-3.0-or-later`).

Virtual Office remains open source. You may use, modify, host, and
redistribute it under the AGPL. If you modify the app and make it available
to users over a network, you must offer those users the corresponding source
code for your modified version.

Paid license keys unlock the hosted/product feature set and support the
official distribution. Commercial licensing is available separately for
organizations that need terms outside the AGPL.

my-virtual-office

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README