Isolated Tester

Vision and control for any model: drive macOS apps and VMs on isolated virtual displays over MCP

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

One-click editor setup isn’t available for this listing yet — we don’t have a confirmed install command, and we’d rather show nothing than point your editor at the wrong package or host. Follow the project’s own setup instructions, linked above.

Manual Client & Custom JSON ConfigExpand JSON ▾

No confirmed setup config for this listing yet. We only publish a config block when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for isolated-tester, and we’d rather show nothing than a guess you’d paste into your client. Follow the project’s own setup instructions for the current steps.

Documentation Overview

IsolatedTester

AI-powered isolated app testing for macOS. Launch any .app on a virtual display, control it with vision-based AI, and verify behavior — without taking over your screen.

Quick Install (Claude Code Plugin)

bash

git clone https://github.com/AgewellEPM/IsolatedTester.git && cd IsolatedTester && ./install.sh

This builds from source, installs binaries to ~/.local/bin/, and configures the MCP server in Claude Code automatically. Then grant Screen Recording and Accessibility permissions in System Settings.

Update

bash

cd IsolatedTester && git pull && ./install.sh

Uninstall

bash

cd IsolatedTester && ./uninstall.sh

Slash Commands

Once installed, these slash commands are available in Claude Code:

Command	Description
`/test-app <path> <objective>`	Launch and test a macOS app in an isolated virtual display
`/test-screenshot [session-id]`	Capture a screenshot from a running session
`/test-elements [session-id]`	Inspect accessibility elements of a running session
`/test-cleanup`	Stop all active test sessions

Verify Setup

Ask Claude Code to call the setup_status tool — it reports version, permissions, virtual display availability, and active sessions.

What It Does

IsolatedTester creates invisible virtual displays using private CoreGraphics APIs, launches your app there, and lets an AI agent (Claude, GPT-4, or Claude Code CLI) drive the UI through a screenshot → reason → act loop. Your physical screen is never touched.

Code

┌──────────────────────────────────────────────────────┐
│  You (CLI / HTTP / MCP)                              │
│    ↓                                                 │
│  SessionManager (actor)                              │
│    ↓                                                 │
│  TestSession                                         │
│    ├── VirtualDisplayManager  → invisible display    │
│    ├── AppLauncher            → launch .app on it    │
│    ├── InputController        → CGEvent synthesis    │
│    ├── ScreenCapture          → ScreenCaptureKit     │
│    └── AITestAgent            → vision → action loop │
│         ├── Anthropic API                            │
│         ├── OpenAI API                               │
│         └── Claude Code CLI                          │
└──────────────────────────────────────────────────────┘

Advanced Installation

Build from Source (Manual)

bash

git clone https://github.com/AgewellEPM/IsolatedTester.git
cd IsolatedTester
swift build -c release
cp .build/release/isolated .build/release/isolated-mcp .build/release/isolated-http ~/.local/bin/

Grant Permissions

IsolatedTester requires two macOS permissions:

Screen Recording — for capturing screenshots via ScreenCaptureKit
Accessibility — for synthesizing mouse/keyboard input via CGEvent

Check status: isolated displays (will prompt if needed)

Usage

CLI

bash

# List available displays
isolated displays

# Launch an app on a virtual display
isolated launch /Applications/Calculator.app

# Run an AI test
isolated test /Applications/Calculator.app \
  --objective "Calculate 5 + 3 and verify the result is 8" \
  --provider anthropic \
  --api-key $ANTHROPIC_API_KEY

# Take a screenshot
isolated screenshot --display 1

HTTP Server

bash

# Start the server (default port 7100)
IST_TOKEN=my-secret-token isolated-http

# Create a session
curl -X POST http://localhost:7100/sessions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"appPath": "/Applications/Calculator.app"}'

# Take a screenshot
curl -X POST http://localhost:7100/sessions/{id}/screenshot \
  -H "Authorization: Bearer my-secret-token"

# Run an AI test
curl -X POST http://localhost:7100/sessions/{id}/test \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Calculate 5 + 3 and verify the result is 8",
    "provider": "anthropic",
    "apiKey": "sk-ant-..."
  }'

See docs/openapi.yaml for the full API specification.

MCP Server (Claude Code / Editor Integration)

Add to ~/.claude/settings.json:

config.json

{
  "mcpServers": {
    "isolated-tester": {
      "command": "/path/to/isolated-mcp",
      "args": []
    }
  }
}

Then in Claude Code:

"Launch Calculator.app, click the 5 button, then +, then 3, then =, and screenshot to verify the result is 8"

Claude Code will use the MCP tools (create_session, click, screenshot, etc.) to execute the test autonomously.

See docs/mcp-tools.md for all available MCP tools.

Configuration

Create .isolatedtester.yml in your project directory or ~/.isolatedtester.yml:

yaml

provider: anthropic
model: claude-sonnet-4-20250514
max_steps: 25
action_delay: 0.5

display:
  width: 1920
  height: 1080
  ppi: 144

retry:
  max_retries: 3
  backoff_multiplier: 2.0

timeouts:
  api_call: 60
  app_launch: 10
  session_total: 600

API Key Resolution

Keys are resolved in priority order:

Explicit --api-key flag or request parameter
Environment variable (ANTHROPIC_API_KEY or OPENAI_API_KEY)
Config file (.isolatedtester.yml)
macOS Keychain (com.isolatedtester.apikeys)

Environment Variables

Variable	Description	Default
`IST_PORT`	HTTP server port	`7100`
`IST_TOKEN`	Bearer token for HTTP auth	(none, auth disabled)
`IST_CORS_ORIGINS`	Allowed CORS origins (comma-separated)	`http://localhost:,http://127.0.0.1:`
`IST_RATE_LIMIT`	Max requests per second per client	`10`
`IST_RATE_BURST`	Rate limit burst size	`100`
`IST_SESSION_IDLE_TIMEOUT`	Idle session timeout in seconds	`1800` (30 min)
`IST_SESSION_MAX_AGE`	Maximum session age in seconds	`7200` (2 hr)
`IST_LOG_FORMAT`	Log format: `text` or `json`	`text`
`IST_ENV`	Config profile (loads `.isolatedtester.{env}.yml`)	(none)
`ANTHROPIC_API_KEY`	Anthropic API key	(none)
`OPENAI_API_KEY`	OpenAI API key	(none)

Architecture

Code

Package Targets:
  CLI                    → isolated binary (ArgumentParser)
  IsolatedTesterKit      → Core library (no dependencies)
  IsolatedServerCore     → Shared server logic (depends on Kit)
  IsolatedMCPServer      → MCP binary (depends on ServerCore)
  IsolatedHTTPServer     → HTTP binary (depends on ServerCore + SwiftNIO)

Key Components

Component	Location	Purpose
`SessionManager`	`ServerCore/`	Actor managing concurrent test sessions
`TestSession`	`Kit/Session/`	Orchestrates display + app + input + capture
`AITestAgent`	`Kit/Agent/`	Vision-based AI test loop
`VirtualDisplayManager`	`Kit/Display/`	CGVirtualDisplay (private API) wrapper
`InputController`	`Kit/Input/`	CGEvent-based mouse/keyboard synthesis
`ScreenCapture`	`Kit/Capture/`	ScreenCaptureKit screenshot capture
`RequestValidator`	`ServerCore/`	Input validation for all request types
`CircuitBreaker`	`Kit/Resilience/`	Fault tolerance for AI provider calls
`AXIntrospector`	`Kit/Accessibility/`	macOS accessibility tree introspection
`RateLimiter`	`HTTPServer/`	Token bucket rate limiting

macOS Compatibility

macOS Version	Status
macOS 15 (Sequoia)	Fully supported
macOS 14 (Sonoma)	Fully supported
macOS 13 (Ventura)	Supported (CGVirtualDisplay may be unavailable)
macOS 12 and earlier	Not supported

Security

See SECURITY.md for the full security policy.

Key points:

HTTP server binds to 127.0.0.1 only (not network-accessible)
Bearer token authentication for HTTP API
Input validation on all request parameters
Rate limiting to prevent abuse
Session timeouts to prevent resource leaks
API keys stored securely in macOS Keychain

Privacy Policy

See PRIVACY.md for the full privacy policy.

Key points:

Local-first: all captures and reports are owner-private files on your machine
No telemetry, no analytics, no developer-operated servers — we never see your data
Only run_test sends session screenshots to the AI provider you configure, with your API key
Captures come only from apps/VMs you explicitly launch in isolated sessions — never your real desktop
You control retention; delete local data directories or run ./uninstall.sh at any time

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Isolated Tester

We don't have a confirmed install command for isolated-tester yet, so we don't publish a generated one — a guessed package name would point at the wrong package or none at all. Follow the project's own README or setup instructions (https://github.com/AgewellEPM/IsolatedTester) for the current steps.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/isolated-tester?style=directory)](https://allmcps.com/mcp/isolated-tester)

HTML Embed

<a href="https://allmcps.com/mcp/isolated-tester"><img src="https://allmcps.com/api/badge/isolated-tester?style=directory" alt="Isolated Tester on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Isolated Tester →Install in Claude Desktop Install in Cursor Install in VS Code Setup guides for all 13 MCP clients

Isolated Tester

Vision and control for any model: drive macOS apps and VMs on isolated virtual displays over MCP

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Manual Client & Custom JSON ConfigExpand JSON ▾

Documentation Overview

IsolatedTester

AI-powered isolated app testing for macOS. Launch any .app on a virtual display, control it with vision-based AI, and verify behavior — without taking over your screen.

Quick Install (Claude Code Plugin)

bash

git clone https://github.com/AgewellEPM/IsolatedTester.git && cd IsolatedTester && ./install.sh

Update

bash

cd IsolatedTester && git pull && ./install.sh

Uninstall

bash

cd IsolatedTester && ./uninstall.sh

Slash Commands

Once installed, these slash commands are available in Claude Code:

Command	Description
`/test-app <path> <objective>`	Launch and test a macOS app in an isolated virtual display
`/test-screenshot [session-id]`	Capture a screenshot from a running session
`/test-elements [session-id]`	Inspect accessibility elements of a running session
`/test-cleanup`	Stop all active test sessions

Verify Setup

Ask Claude Code to call the setup_status tool — it reports version, permissions, virtual display availability, and active sessions.

What It Does

Code

┌──────────────────────────────────────────────────────┐
│  You (CLI / HTTP / MCP)                              │
│    ↓                                                 │
│  SessionManager (actor)                              │
│    ↓                                                 │
│  TestSession                                         │
│    ├── VirtualDisplayManager  → invisible display    │
│    ├── AppLauncher            → launch .app on it    │
│    ├── InputController        → CGEvent synthesis    │
│    ├── ScreenCapture          → ScreenCaptureKit     │
│    └── AITestAgent            → vision → action loop │
│         ├── Anthropic API                            │
│         ├── OpenAI API                               │
│         └── Claude Code CLI                          │
└──────────────────────────────────────────────────────┘

Advanced Installation

Build from Source (Manual)

bash

git clone https://github.com/AgewellEPM/IsolatedTester.git
cd IsolatedTester
swift build -c release
cp .build/release/isolated .build/release/isolated-mcp .build/release/isolated-http ~/.local/bin/

Grant Permissions

IsolatedTester requires two macOS permissions:

Screen Recording — for capturing screenshots via ScreenCaptureKit
Accessibility — for synthesizing mouse/keyboard input via CGEvent

Check status: isolated displays (will prompt if needed)

Usage

CLI

bash

# List available displays
isolated displays

# Launch an app on a virtual display
isolated launch /Applications/Calculator.app

# Run an AI test
isolated test /Applications/Calculator.app \
  --objective "Calculate 5 + 3 and verify the result is 8" \
  --provider anthropic \
  --api-key $ANTHROPIC_API_KEY

# Take a screenshot
isolated screenshot --display 1

HTTP Server

bash

# Start the server (default port 7100)
IST_TOKEN=my-secret-token isolated-http

# Create a session
curl -X POST http://localhost:7100/sessions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"appPath": "/Applications/Calculator.app"}'

# Take a screenshot
curl -X POST http://localhost:7100/sessions/{id}/screenshot \
  -H "Authorization: Bearer my-secret-token"

# Run an AI test
curl -X POST http://localhost:7100/sessions/{id}/test \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Calculate 5 + 3 and verify the result is 8",
    "provider": "anthropic",
    "apiKey": "sk-ant-..."
  }'

See docs/openapi.yaml for the full API specification.

MCP Server (Claude Code / Editor Integration)

Add to ~/.claude/settings.json:

config.json

{
  "mcpServers": {
    "isolated-tester": {
      "command": "/path/to/isolated-mcp",
      "args": []
    }
  }
}

Then in Claude Code:

"Launch Calculator.app, click the 5 button, then +, then 3, then =, and screenshot to verify the result is 8"

Claude Code will use the MCP tools (create_session, click, screenshot, etc.) to execute the test autonomously.

See docs/mcp-tools.md for all available MCP tools.

Configuration

Create .isolatedtester.yml in your project directory or ~/.isolatedtester.yml:

yaml

provider: anthropic
model: claude-sonnet-4-20250514
max_steps: 25
action_delay: 0.5

display:
  width: 1920
  height: 1080
  ppi: 144

retry:
  max_retries: 3
  backoff_multiplier: 2.0

timeouts:
  api_call: 60
  app_launch: 10
  session_total: 600

API Key Resolution

Keys are resolved in priority order:

Explicit --api-key flag or request parameter
Environment variable (ANTHROPIC_API_KEY or OPENAI_API_KEY)
Config file (.isolatedtester.yml)
macOS Keychain (com.isolatedtester.apikeys)

Environment Variables

Variable	Description	Default
`IST_PORT`	HTTP server port	`7100`
`IST_TOKEN`	Bearer token for HTTP auth	(none, auth disabled)
`IST_CORS_ORIGINS`	Allowed CORS origins (comma-separated)	`http://localhost:,http://127.0.0.1:`
`IST_RATE_LIMIT`	Max requests per second per client	`10`
`IST_RATE_BURST`	Rate limit burst size	`100`
`IST_SESSION_IDLE_TIMEOUT`	Idle session timeout in seconds	`1800` (30 min)
`IST_SESSION_MAX_AGE`	Maximum session age in seconds	`7200` (2 hr)
`IST_LOG_FORMAT`	Log format: `text` or `json`	`text`
`IST_ENV`	Config profile (loads `.isolatedtester.{env}.yml`)	(none)
`ANTHROPIC_API_KEY`	Anthropic API key	(none)
`OPENAI_API_KEY`	OpenAI API key	(none)

Architecture

Code

Package Targets:
  CLI                    → isolated binary (ArgumentParser)
  IsolatedTesterKit      → Core library (no dependencies)
  IsolatedServerCore     → Shared server logic (depends on Kit)
  IsolatedMCPServer      → MCP binary (depends on ServerCore)
  IsolatedHTTPServer     → HTTP binary (depends on ServerCore + SwiftNIO)

Key Components

Component	Location	Purpose
`SessionManager`	`ServerCore/`	Actor managing concurrent test sessions
`TestSession`	`Kit/Session/`	Orchestrates display + app + input + capture
`AITestAgent`	`Kit/Agent/`	Vision-based AI test loop
`VirtualDisplayManager`	`Kit/Display/`	CGVirtualDisplay (private API) wrapper
`InputController`	`Kit/Input/`	CGEvent-based mouse/keyboard synthesis
`ScreenCapture`	`Kit/Capture/`	ScreenCaptureKit screenshot capture
`RequestValidator`	`ServerCore/`	Input validation for all request types
`CircuitBreaker`	`Kit/Resilience/`	Fault tolerance for AI provider calls
`AXIntrospector`	`Kit/Accessibility/`	macOS accessibility tree introspection
`RateLimiter`	`HTTPServer/`	Token bucket rate limiting

macOS Compatibility

macOS Version	Status
macOS 15 (Sequoia)	Fully supported
macOS 14 (Sonoma)	Fully supported
macOS 13 (Ventura)	Supported (CGVirtualDisplay may be unavailable)
macOS 12 and earlier	Not supported

Security

See SECURITY.md for the full security policy.

Key points:

HTTP server binds to 127.0.0.1 only (not network-accessible)
Bearer token authentication for HTTP API
Input validation on all request parameters
Rate limiting to prevent abuse
Session timeouts to prevent resource leaks
API keys stored securely in macOS Keychain

Privacy Policy

See PRIVACY.md for the full privacy policy.

Key points:

Local-first: all captures and reports are owner-private files on your machine
No telemetry, no analytics, no developer-operated servers — we never see your data
Only run_test sends session screenshots to the AI provider you configure, with your API key
Captures come only from apps/VMs you explicitly launch in isolated sessions — never your real desktop
You control retention; delete local data directories or run ./uninstall.sh at any time

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Isolated Tester

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/isolated-tester?style=directory)](https://allmcps.com/mcp/isolated-tester)

HTML Embed

<a href="https://allmcps.com/mcp/isolated-tester"><img src="https://allmcps.com/api/badge/isolated-tester?style=directory" alt="Isolated Tester on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.