offstage

Product Introduction

1. Definition: Offstage is a macOS-native, open-source MCP (Model Context Protocol) server and CLI tool that creates a secure, isolated desktop environment for AI coding agents. It operates at the system level by managing a secondary, logged-in macOS user account.
2. Core Value Proposition: Offstage exists to solve the fundamental conflict between AI agents performing GUI-based tasks and a developer's need for an uninterrupted workspace. Its core value is enabling headless GUI automation and agent isolation on a single Mac, allowing tools like Claude Code, Codex, and opencode to run simulators, UI tests, and built applications without stealing screen focus or cluttering the primary user's desktop.

Main Features

1. Multi-Lane Command Router: Offstage intelligently routes shell commands to the most efficient execution environment. It parses commands pre-execution using a rules engine. Commands like xcodebuild or open -a are sent to the secondary macOS session. Headful browser tests (e.g., cypress open) are containerized in a Linux Docker environment with a virtual display. Truly headless commands (e.g., npm test) run in-place for zero overhead.
2. Secondary macOS Session Management: The core feature is the automated creation and management of a computeruse account. It uses sudo-elevated Swift daemons to maintain a persistent, logged-in session on the same Mac. This session has its own WindowServer process, providing a fully functional desktop, display buffer, and input event stream completely separate from the console user.
3. Programmatic GUI Interaction via MCP: Offstage exposes MCP tools (offstage_session_screenshot, offstage_session_input) that allow an AI agent to perform visual reasoning and control. The agent can launch an app, capture screenshots (in points, not pixels), decide on actions (clicks, keystrokes), and execute them via synthetic input events posted exclusively to the helper session's event stream.

Problems Solved

1. Pain Point: AI coding agents break developer workflow by popping open windows, taking focus, and hijacking the mouse and keyboard on the primary desktop. This makes continuous, unattended agent operation impractical.
2. Target Audience: The primary user persona is the macOS-based Software Developer or QA Engineer using AI-powered coding assistants (Claude Code, Cursor, etc.) for tasks involving building, testing, or debugging applications with graphical interfaces, particularly iOS/macOS apps or web applications requiring headed browser testing.
3. Use Cases: Essential for running Xcode UI Tests (XCUITest), interacting with iOS Simulators, testing freshly built .app bundles, executing headed Cypress or Playwright tests, and any automation script using osascript or open -a. It enables true continuous integration and testing loops locally with an AI agent.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros: Exceptional performance and efficiency compared to full VMs; near-native execution speed for macOS GUI apps. Lightweight disk footprint (~3GB vs. 70GB+ for macOS VM). Deep macOS integration allows for secure, system-level session isolation. Free and MIT-licensed.
   • Cons: Requires Apple Silicon Macs and Node.js 20+. Both user accounts share the same physical hardware resources (CPU, RAM), which could lead to contention. Cannot run installers (.pkg, .dmg) due to shared system state. Initial setup requires terminal and sudo access.

2. Key Alternatives & Differentiation:

   • Docker with Virtual Display (e.g., Selenium/Headless Chrome): Only solves web testing. Offstage differentiates by natively supporting the entire macOS GUI stack (Simulator, native apps) which cannot run in Linux containers.
   • Full macOS Virtualization (VMware, Parallels, UTM): Provides stronger isolation but with massive overhead in disk space, memory allocation, and boot time. Offstage is dramatically more resource-efficient for the specific use case of agent isolation.
   • Headless Execution Frameworks: Tools like xvfb on Linux or headless flags only work for supported contexts. Offstage provides a universal, session-level solution for any macOS GUI application.

Frequently Asked Questions (FAQ)

1. Is Offstage a virtual machine or emulator? No. Offstage is not a virtual machine. It is a system automation tool that leverages macOS's native multi-user capabilities to create a second, simultaneous login session on the same physical hardware, avoiding the overhead of virtualizing an entire guest operating system.
2. Can the AI agent click on or control my primary desktop? No. The offstage daemon is engineered to post synthetic input events (clicks, keystrokes) exclusively to its own WindowServer session. It cannot inject events into the global input stream that controls the console user's desktop, as verified by WindowServer event logs.
3. What are the security implications of the 'computeruse' account? The helper account is a standard, non-administrator macOS user. It cannot write to your personal files. By default, it can only read files accessible to any local user. Explicit read-only sharing of project directories is required via the offstage session share command, providing controlled access.
4. Which AI coding assistants are compatible with Offstage? Offstage provides native integration via MCP for Claude Code, Codex, and opencode. Any AI agent or shell-based tool can use the underlying offstage CLI (offstage route, offstage run), making it compatible with any system that can execute shell commands.
5. Why does Offstage refuse to run installers or disk image commands? Because both user accounts share the same underlying macOS filesystem and system domain, allowing an installer to run in the helper account could corrupt the system for the primary user. Offstage errs on the side of safety by categorically refusing commands like hdiutil or installer packages.