Installation

View as Markdown

Download

Download the latest .dmg from the GitHub releases page.

Install

1. Open the .dmg file
2. Drag Shiplight to your Applications folder
3. Open the app — macOS will warn that it's from an unidentified developer since the app is not yet code-signed

Bypassing the macOS Gatekeeper Warning

Since the app is unsigned, macOS blocks it on first launch. To open it:

Option A — Right-click to open:

1. Right-click (or Control-click) the app in Applications
2. Select Open from the context menu
3. Click Open in the confirmation dialog

Option B — System Settings:

1. Try opening the app normally (it will be blocked)
2. Go to System Settings > Privacy & Security
3. Scroll down — you'll see a message about Shiplight being blocked
4. Click Open Anyway

You only need to do this once. After the first launch, macOS remembers your choice.

Sign In

When the app launches, you'll see the Shiplight login page. Sign in with your existing account:

• Google — click "Continue with Google"
• Email & password — enter your credentials

This is the same login you use on app.shiplight.ai. Your session persists across app restarts.

Configure AI Keys

The web agent needs an API key to power AI features like verify, ai_extract, and natural language test steps.

1. Open the app and navigate to Settings > AI Keys (or click the key icon in the sidebar)
2. Enter your API key for one of the supported providers:
   • Google API Key — for Gemini models
   • Anthropic API Key — for Claude models
3. Keys are encrypted and stored in your macOS Keychain

TIP

You only need one provider key. Google's gemini-2.5-pro is a good default — it's fast and cost-effective for browser automation tasks.

MCP Server Setup

The desktop app automatically starts an MCP server on localhost:36790 when launched. You can connect your IDE to it for browser automation and test management.

Claude Code

claude mcp add shiplight -s sse -e http://localhost:36790/mcp

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "shiplight": {
      "url": "http://localhost:36790/mcp"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "shiplight": {
      "url": "http://localhost:36790/mcp"
    }
  }
}

INFO

The desktop MCP server uses your app's login session and AI keys — no extra environment variables needed. This is different from the npm CLI package, which requires API_TOKEN and GOOGLE_API_KEY as env vars.

Next Steps

• Desktop App Overview — Features and comparison
• Setup Guide — Install and configure the MCP server
• Debugging — Interactive debugging in the test editor