Skip to main content
This guide starts the Python measurement pipeline and the Next.js application on one machine. Local operator mode is a development concession. It is not the production identity model.

​
Prerequisites

  • Python 3.12 or later
  • Node.js and npm
  • An OpenRouter API key for model calls
  • An Exa API key for Exa measurement and research
  • An AgentMail API key if you want workspace email provisioning
1

Install the pipeline

geo init creates the pipeline database and supporting data directories. The current schema is version 6.
2

Configure operator secrets

Add the keys you need to the repository-root .env file.
OpenRouter, Exa, AgentMail, and PageSpeed keys stay with the operator. They are not workspace credentials and cannot be set through the Connections page.Generate the delivery key with openssl rand -hex 32. It must decode to exactly 32 bytes and must differ from GEO_API_KEY_PEPPER.
Local fallback sessions are accepted only when GEO_OPERATOR_MODE=local, the app is not running as production, and both the host and direct peer are loopback. Do not use this mode to expose a shared deployment.
3

Start the web application

Open http://127.0.0.1:3000. The development server binds to loopback.
4

Create the first workspace

The setup wizard asks for:
  • A slug with 2 to 20 lowercase letters, digits, or hyphens
  • A display name with 2 to 60 characters
  • Between 1 and 8 owned domains
  • Languages and up to 8 regions
  • Between 2 and 12 competitors
  • A Search Console domain property in sc-domain:example.com form
  • A 6 to 12 digit GA4 property ID
  • An active prompt target between 20 and 300
  • A compliance mode of none or eu_medical
  • Intent quotas that sum to 1.0
Products, services, and design details can be completed in Settings after creation. The wizard writes an empty ICP list to brands/<slug>.yaml. Fill icp_summary and icps in that file before starting the research pipeline.When AGENTMAIL_API_KEY is present, the creation service also requests a workspace inbox. It waits for that best-effort attempt, but an unconfigured provider, conflict, or provider failure does not roll back the new workspace.
5

Connect Google properties

Copy the workspace AgentMail address from Settings, then invite it:
  1. Add it as Viewer on the GA4 property.
  2. Add it with Full access on the Search Console property.
  3. Confirm the GA4 numeric property ID and Search Console property in brands/<slug>.yaml. The connection guide provides copyable YAML lines but does not edit the file.
The connection test confirms that the required root environment keys and workspace property value are present. It does not call Google or inspect the property member list. If a later data pull fails, verify the invitation and property value in Google.
6

Add the first prompts

Open Settings > Prompts and add at least two user prompts. A fresh workspace has no active generated prompts, and the smoke preset can use at most two.
Use neutral questions that do not assume the tracked brand is the preferred answer. You can replace this starter set later with research-driven generation.
7

Run a measurement

Open Runs, choose smoke for the smallest test, review the estimated calls and credit reservation, then start the job. The detail page shows engine progress, completed and failed responses, latency, cost, and the linked run report.
Use smoke to verify credentials and metering. Use standard only after the prompt set and engine access are ready.
8

Check the result

After the job settles:
  • Open Dashboard for the GEO score and engine scoreboard.
  • Open Runs for raw response counts and provider errors.
  • Open Reports when the run has a linked report snapshot.
  • Start Research before regenerating an ICP-driven prompt set.
If the run stops for credits, no new provider call is authorized after the available lease is exhausted. Add a mock local top-up from Billing, then start a new operation.
Next: read the Dashboard guide to interpret the result, or set up the MCP server to query it from your assistant.