> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Local quickstart

> Run the application locally, create a workspace, and complete a first measurement.

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

<Steps>
  <Step title="Install the pipeline">
    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -e '.[dev]'
    cp .env.example .env
    geo init
    ```

    <Note>
      <code>geo init</code> creates the pipeline database and supporting data directories. The current schema is version 6.
    </Note>
  </Step>

  <Step title="Configure operator secrets">
    Add the keys you need to the repository-root <code>.env</code> file.

    <CodeGroup>
      ```bash Core provider access theme={null}
      OPENROUTER_API_KEY=...
      EXA_API_KEY=...
      AGENTMAIL_API_KEY=...
      GOOGLE_PAGESPEED_API_KEY=...
      ```

      ```bash Local application theme={null}
      GEO_OPERATOR_MODE=local
      GEO_SESSION_SECRET=replace_with_a_long_random_secret
      GEO_API_KEY_PEPPER=replace_with_a_separate_random_secret
      GEO_API_KEY_DELIVERY_KEY=paste_64_hex_characters_here
      GEO_OPERATION_TOKEN_SECRET=replace_with_another_random_secret
      ```

      ```bash Google access theme={null}
      GOOGLE_WORKSPACE_CLI_CLIENT_ID=...
      GOOGLE_WORKSPACE_CLI_CLIENT_SECRET=...
      GOOGLE_ANALYTICS_REFRESH_TOKEN=...
      GOOGLE_GMAIL_REFRESH_TOKEN=...
      ```
    </CodeGroup>

    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 <code>openssl rand -hex 32</code>. It must decode to exactly 32 bytes and must differ from <code>GEO\_API\_KEY\_PEPPER</code>.

    <Warning>
      Local fallback sessions are accepted only when <code>GEO\_OPERATOR\_MODE=local</code>, 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.
    </Warning>
  </Step>

  <Step title="Start the web application">
    ```bash theme={null}
    cd apps/web
    npm install
    npm run dev
    ```

    Open <code>[http://127.0.0.1:3000](http://127.0.0.1:3000)</code>. The development server binds to loopback.
  </Step>

  <Step title="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 <code>sc-domain:example.com</code> form
    * A 6 to 12 digit GA4 property ID
    * An active prompt target between 20 and 300
    * A compliance mode of <code>none</code> or <code>eu\_medical</code>
    * 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 <code>brands/\<slug>.yaml</code>. Fill <code>icp\_summary</code> and <code>icps</code> in that file before starting the research pipeline.

    When <code>AGENTMAIL\_API\_KEY</code> 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.
  </Step>

  <Step title="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 <code>brands/\<slug>.yaml</code>. 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.
  </Step>

  <Step title="Add the first prompts">
    Open **Settings > Prompts** and add at least two user prompts. A fresh workspace has no active generated prompts, and the <code>smoke</code> preset can use at most two.

    ```text theme={null}
    Which identity verification services support document and biometric checks?
    How should a marketplace compare identity verification providers for Europe?
    ```

    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](/prompts#icp-driven-generation).
  </Step>

  <Step title="Run a measurement">
    Open **Runs**, choose <code>smoke</code> 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.

    <Tip>
      Use <code>smoke</code> to verify credentials and metering. Use <code>standard</code> only after the prompt set and engine access are ready.
    </Tip>
  </Step>

  <Step title="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.
  </Step>
</Steps>

Next: [read the Dashboard](/dashboard) guide to interpret the result, or set up the [MCP server](/mcp/install) to query it from your assistant.