Quick Start

This guide gets you from zero to a verified trajectory and Playwright export — on Molar Cloud or a local stack. For deeper concepts, see Core concepts. For every environment variable, see Configuration.

Product page: cartographer.molar.it · Dashboard: app.molar.it/dashboard/cartographer

Choose your path

You can mix paths: many teams use Cloud for daily work and run a local stack for debugging.

Option A — Molar Cloud

1. Sign up and open Cartographer

1. Create an account at app.molar.it.
2. Ensure your organization has a Cartographer entitlement (standalone SKU or full Molar bundle).
3. Open app.molar.it/dashboard/cartographer.

2. Complete onboarding

Work through Mission Control on first login:

Check System status on Mission Control (API, workers, LLM keys) before starting crawls or runs. If workers are offline, jobs stay queued — see Quick start — workers.

3. Connect MCP (optional)

From Integrations → MCP:

1. Pick your IDE client (Cursor, Claude Code, Windsurf, Copilot, or custom).
2. Copy the config snippet (HTTP endpoint https://mcp.molar.cloud or stdio via cartog mcp).
3. Click Authorize to complete OAuth with your Molar account (api.molar.it).
4. Test with cartographer_list_projects.

See MCP tools for the full tool reference.

4. Install the browser extension (optional)

Needed for recorded demos, MFA / payment approvals, and flows that must run in your real Chrome profile. See Browser extension.

Option B — Local development

Prerequisites

Bootstrap and start the stack

# From your Cartographer self-host bundle (contact support@molar.it for access)
make bootstrap   # ~30 min first time (downloads CloakBrowser ~200 MB)
make dev         # Docker stack + database migrations
make seed        # Demo data + smoke test

Open http://localhost:3000/dashboard (product shell) and http://localhost:3000/traces (trace viewer), sign up, and create a project — same APIs as cloud, pointed at your local stack.

Services and ports (local)

Start workers

Cartographer queues work through Hatchet. The API accepts requests immediately; workers execute crawls, agent runs, exports, and trace post-processing. Without workers, jobs stay queued.

Open four terminals (after make dev):

# Terminal 1 — agent runs (LangGraph planner/actor/verifier)
make agent-worker

# Terminal 2 — site crawls and route maps
make crawl-worker

# Terminal 3 — Playwright export pipeline
make export-worker

# Terminal 4 (optional) — trace postprocess and GC
make trace-worker

Verify workers appear in the dashboard health strip (Home or project hub) or Hatchet UI at http://localhost:8080.

Verify end-to-end (verify-e2e)

With the stack and all three core workers running:

# Generic public-site check
make verify-e2e URL=https://example.com GOAL="Load homepage and confirm navigation is visible"

# Production-safe demo target (public homepage only)
make verify-e2e-behtarbroker

What verify-e2e exercises:

POST /v1/crawls     → crawl worker → route map
POST /v1/runs       → agent worker → verified trajectory
POST /v1/runs/{id}/export → export worker → Playwright zip
WS   /v1/runs/{id}/stream → live step events

Phase 0 infrastructure checks (no workers required):

make verify-phase-0

CI-style single invocation (same HTTP API path):

cartog ci "Load homepage and confirm navigation is visible" --project <project-id> --url https://example.com

For acceptance gates and end-to-end architecture detail, contact support@molar.it for the operator runbook.

Local MCP

Stdio (IDE spawns the server):

cartog mcp

HTTP (mounted on the API with make dev):

http://localhost:8000/mcp

Use a personal access token from Settings → API tokens for stdio, or complete OAuth for hosted HTTP. See MCP tools.

Option C — MCP from your IDE

After Option A or B is working:

1. Install MCP config from Integrations → MCP (cloud) or point stdio at cartog mcp (local).
2. Authorize OAuth (cloud) or set cartog config set token <pat> (local/CI).
3. In your IDE, ask: "List my Cartographer projects" → invokes cartographer_list_projects.
4. "Crawl https://staging.myapp.com and run checkout" → cartographer_crawl_site then cartographer_run_test.
5. Open the returned run_id in the dashboard live stream or Trace viewer.

Long-running tools report progress (step counts, export pipeline stages) and return an mcp_task_id when MCP tasks are enabled. Poll cartographer_get_task after a disconnect.

First project walkthrough

This walkthrough applies to cloud and local dashboards.

Step 1 — Create a project

Projects → New project

Step 2 — Configure credentials (if login required)

Settings → Credentials → Add alias

• Store username, password, and optional TOTP seed encrypted server-side.
• On run launch, select the credentials alias — secrets never appear in logs or MCP responses.
• For MFA that cannot be automated, use the browser extension approval queue.

Step 3 — Crawl the site

From the project hub → Start crawl:

When complete, open the route map: page table, interactive graph, screenshots, HAR files, and Discover flows (batch-enqueue agent runs from discovered patterns).

Step 4 — Start an agent run

Start run from the project hub or from a route-map page row:

3. Watch the live execution panel on run detail: step list, tier escalations, and screenshots. If the run enters pending_human, use the HITL panel or extension approvals.

Step 5 — Open Trace and review findings

From run detail in the dashboard, use Open trace (links to /traces/{id}). Today you get:

• Step timeline and filterable Events log
• Video playback when a recording exists
• Debugger chat (AI assistant with trace-scoped tools)
• Layer 2 diff when a replay child trace exists

Network/Console panels, keyboard scrubber shortcuts, and Playwright Source mode are available on app.molar.it/trace.

Findings — passive UX issues (axe, visual diff, sampled VLM) appear under the project Findings section in the dashboard.

Step 6 — Export Playwright tests

On a completed run:

1. Click Export.
2. Choose style (poms or flat), target repo (optional), and CI CloakBrowser opt-in.
3. Watch the pipeline: prune → rank selectors → cluster page objects → generate → lint → verify → heal.
4. Download zip or Open GitHub PR when complete.

Exported tests use stock Chromium in CI by default. Opt into CloakBrowser only for bot-protected targets.

Step 7 — Install MCP for day-two workflows

Repeatable IDE workflow:

cartographer_create_project  →  cartographer_crawl_site
        →  cartographer_run_test  →  cartographer_export_test

Link each run_id to the dashboard for teammates who prefer the UI.

Health checks before you debug

If actions are blocked or jobs stay queued:

Full symptom tables: Troubleshooting & FAQ.

Next steps