Quickstart

Option A: CLI (Fastest)

For a new agent or fresh IDE setup, start with the one-command onboarding flow:

npx deepsyte setup --client codex     # or: cursor, vscode, windsurf, claude, claude-code

That flow authenticates if needed, configures the MCP client, and installs or repairs the managed core DeepSyte skill into ~/.agents/skills/deepsyte, including workflows/sitewide-performance-audit/WORKFLOW.md.

The canonical MCP endpoint is https://api.deepsyte.com/mcp. OAuth discovery should use https://api.deepsyte.com; do not use the obsolete https://deepsyte-api-production.up.railway.app host. The valid Railway service domain is https://screenshotsmcp-api-production.up.railway.app, but client setup should prefer the custom API domain.

If you prefer to do onboarding in two steps, run:

npx deepsyte login
npx deepsyte install codex     # or: cursor, vscode, windsurf, claude, claude-code

That reaches the same result as setup --client <client> for most clients. The main nuances are that install codex writes ~/.codex/config.toml and asks you to run codex mcp login deepsyte, install vscode writes a workspace-local .vscode/mcp.json, while install claude-code prints the claude mcp add ... command for you to run manually.

The first packaged workflow is ~/.agents/skills/deepsyte/workflows/sitewide-performance-audit/WORKFLOW.md for repeatable multi-page performance audits.

Note: deepsyte skills ... only manages the local core DeepSyte skill. To discover or install community skills such as Anthropic's frontend-design, use the find-skills workflow or npx skills find ... / npx skills add ....

The CLI also works standalone from the terminal:

npx deepsyte screenshot https://example.com
npx deepsyte fullpage https://example.com
npx deepsyte responsive https://example.com
npx deepsyte auth:test https://example.com
npx deepsyte auth:find-login https://example.com
npx deepsyte auth:authorize-email
npx deepsyte review https://example.com
npx deepsyte browse https://example.com
npx deepsyte browse https://example.com --task-type site_audit --user-goal "Audit public pages for UX regressions" --workflow-name sitewide-performance-audit --auth-scope out --page-set homepage,pricing,docs --required-evidence screenshots,console,network
npx deepsyte browse:console <sessionId> --level error
npx deepsyte browse:network-errors <sessionId>
npx deepsyte browse:a11y <sessionId>
npx deepsyte browse:perf <sessionId>
npx deepsyte browser evidence --label homepage-check
npx deepsyte browser open https://example.com
npx deepsyte balance
npx deepsyte skills sync

Use remote execution first for public websites. The CLI now mirrors the MCP remote workflow directly: start a remote session with browse, keep the sessionId, and then use browse:* commands for interaction, debugging, SEO, performance, accessibility, cookies, storage, and CAPTCHA solving. Add workflow-aware flags like --task-type, --user-goal, --workflow-name, --page-set, and --required-evidence when you want the run UI to persist a verdict, proof coverage, and next actions.

For a simple localhost or private-page screenshot, stay with the natural screenshot command. After website OAuth, DeepSyte automatically routes local-only URLs through an isolated managed local Chrome profile, uploads the evidence screenshot to R2, records the run in the dashboard, prints Run status: completed, and closes the one-shot browser cleanly. Agents should treat process exit code 0 plus Run status: completed as the completion signal:

npx deepsyte login
npx deepsyte screenshot http://localhost:3000 --no-full-page

If the CLI is not authenticated, it will tell the agent to run npx deepsyte login and retry the same command. Do not send localhost, loopback, intranet, or VPN-only URLs to cloud-only commands; the CLI will either use a local implementation or print the exact authenticated local-browser command to run.

When you need multi-step localhost access, private apps, VPN-only environments, or more realistic manual-browser behavior, switch to the managed local browser without installing an extension. Managed local browser commands require a valid DeepSyte website OAuth session:

npx deepsyte login
npx deepsyte whoami
npx deepsyte balance
npx deepsyte browser open http://localhost:3000 --yes
npx deepsyte browser open http://localhost:3000 --record-video --yes
npx deepsyte browser status
npx deepsyte browser goto https://example.org
npx deepsyte browser back
npx deepsyte browser forward
npx deepsyte browser screenshot --grid
npx deepsyte browser move-to 320 480
npx deepsyte browser click-at 320 480
npx deepsyte browser double-click-at 320 480
npx deepsyte browser right-click-at 320 480
npx deepsyte browser drag 320 480 520 620 --steps 16
npx deepsyte browser wheel --x 320 --y 480 --delta-y 600
npx deepsyte browser type "hello@example.com"
npx deepsyte browser hover ".menu-trigger"
npx deepsyte browser wait-for ".results-loaded" --timeout 8000
npx deepsyte browser select "select[name=country]" "Australia"
npx deepsyte browser viewport 393 852
npx deepsyte browser screenshot
npx deepsyte browser text
npx deepsyte browser console --level error
npx deepsyte browser network-errors
npx deepsyte browser network-requests --resource-type fetch --min-duration 200
npx deepsyte browser evidence --label checkout-bug
npx deepsyte browser close --evidence --label checkout-bug
npx deepsyte browser cookies get
npx deepsyte browser storage getAll --type localStorage
npx deepsyte browser eval "document.title"
npx deepsyte browser a11y --max-depth 6
npx deepsyte browser perf
npx deepsyte browser seo
npx deepsyte browser close

This opens an installed local browser in a fresh dedicated DeepSyte profile after an explicit approval prompt, keeps console logs and network activity flowing into the tracked session while that browser stays open, and lets the CLI reconnect for local actions like history navigation, viewport-coordinate mouse control, hover states, wait conditions, dropdown selection, viewport changes, screenshots, text extraction, cookies/storage inspection, script evaluation, accessibility inspection, performance metrics, SEO auditing, and timestamped evidence bundle export. In deepsyte@1.21.7+, browser open returns immediately after the detached browser daemon and session are registered; it does not wait for an initial screenshot unless --initial-screenshot is passed. Agents should call browser screenshot --grid as the next command when they need visual coordinate proof, then use commands like move-to, click-at, drag, wheel, and focused type. browser open and intermediate browser ... commands leave the dashboard run active; browser close is the finalizer and prints Run status: completed. Use browser evidence for a live proof snapshot, or browser close --evidence when you want the finalized local .webm included in the same bundle after recording finishes.

The goal is not just capture. It is verification: run the workflow, inspect what happened, and keep the proof with the result.

Agent-safe browser sessions

Use deepsyte browse <url> for public interactive browser work, then pass the returned run_... session ID to browse:* commands and always close it with deepsyte browse:close <sessionId>. For simple extraction or screenshots, prefer the one-shot screenshot command or REST API.

In deepsyte@1.21.12+, browse exits non-zero when navigation fails before a usable session exists. Expired SSL pages, for example, return a clear error such as Browse failed: Error navigating: SSL certificate has expired for this site. Treat missing Session: or Run URL: output as failure.

Option B: Manual Setup

1. Choose Your Auth Path

For MCP clients, use website OAuth. Raw API keys are for REST API calls and cannot authorize MCP access.

If a browser opens a Railway 404 during OAuth, update the MCP URL to https://api.deepsyte.com/mcp and reconnect.

2. Add to Your IDE

Codex

Add to ~/.codex/config.toml, then run codex mcp login deepsyte:

[mcp_servers.deepsyte]
url = "https://api.deepsyte.com/mcp"
scopes = ["mcp:tools"]
oauth_resource = "https://api.deepsyte.com/mcp"

If a current Codex Desktop build completes OAuth but does not mount mcp__deepsyte tools into a fresh thread, use mcp-remote@0.1.38 as a temporary bridge:

[mcp_servers.deepsyte]
command = "npx"
args = ["-y", "mcp-remote@0.1.38", "https://api.deepsyte.com/mcp"]

If a legacy MCP client says it does not support HTTP transport and asks for SSE, configure https://api.deepsyte.com/sse instead. Keep https://api.deepsyte.com/mcp as the preferred endpoint for clients that support Streamable HTTP.

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "deepsyte": {
      "url": "https://api.deepsyte.com/mcp"
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "deepsyte": {
      "serverUrl": "https://api.deepsyte.com/mcp"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "deepsyte": {
      "url": "https://api.deepsyte.com/mcp"
    }
  }
}

3. Start Using It

Ask your AI assistant:

Open https://stripe.com, inspect the page, and tell me what you see

Or ask for a more evidence-heavy workflow:

Test my checkout flow and capture proof if anything fails

For login or sign-up testing, prefer a prompt like:

Start with auth_test_assist for https://example.com, follow its recommended auth path, reuse the saved inbox credentials, test the auth flow end-to-end, and summarize reusable auth heuristics first with site-specific evidence second.

That's it. Your AI can now see websites, run browser workflows, and return evidence instead of guesses.

Option C: Chrome Extension Preview

If you want DeepSyte directly in Chrome, the monorepo includes an unpacked extension preview in packages/chrome-extension.

What it does

• Public URLs use DeepSyte cloud capture after website authorization.
• Localhost and private pages stay local-first so you can still capture dev servers and pages the cloud browser cannot access.
• Page tools in the popup can read visible text and DOM HTML for the active tab.
• Cloud save reuses existing cloud-backed captures when available and can still upload local-only captures from the viewer.

Load it in Chrome

1. Open chrome://extensions
2. Enable Developer mode
3. Click Load unpacked
4. Select packages/chrome-extension
5. Pin the extension to your toolbar

Authenticate it

1. Open the extension popup
2. Open Settings
3. Sign in with your DeepSyte account when prompted
4. Save the authorized session

Use it

1. Open a public page to use the platform-backed Playwright capture path, or open localhost to use the local fallback path
2. Click Screenshot or Full Page Screenshot
3. Use Read Text or Read DOM to inspect the current page

What's Next?

• Browser Sessions — Navigate, click, fill forms, and verify multi-step flows
• Performance Metrics — Measure Core Web Vitals
• SEO Audit — Review search-facing issues with findings
• All 157 Tools — See every tool and setup path available