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

# Deployment

> Configure identity, operator custody, application secrets, and loopback metering.

Production deployment of the ai-cmo.dev application must provide an identity adapter and server secrets. This page covers security settings, operator integrations, and the metering boundary for platform operators deploying the application.

```bash Export required deployment secrets theme={null}
export GEO_SESSION_SECRET=replace_with_a_long_random_secret
export GEO_API_KEY_PEPPER=replace_with_a_separate_random_secret
export GEO_API_KEY_DELIVERY_KEY=paste_64_hex_characters_here
export GEO_OPERATION_TOKEN_SECRET=replace_with_another_random_secret
export GEO_ROOT=/srv/ai-cmo
export GEO_DATA_ROOT=/srv/ai-cmo/apps/web/data/pipeline
export GEO_BRANDS_ROOT=/srv/ai-cmo/apps/web/data/brands
```

## Application security settings

| Setting                                    | Purpose                                                            |
| ------------------------------------------ | ------------------------------------------------------------------ |
| <code>GEO\_SESSION\_SECRET</code>          | Signs session and local-origin state                               |
| <code>GEO\_API\_KEY\_PEPPER</code>         | HMAC key for stored API key verifiers                              |
| <code>GEO\_API\_KEY\_DELIVERY\_KEY</code>  | Encrypts pending one-time key delivery                             |
| <code>GEO\_OPERATION\_TOKEN\_SECRET</code> | Signs metering operation tokens                                    |
| <code>GEO\_ROOT</code>                     | Explicit repository and data root when discovery is not sufficient |
| <code>GEO\_TRUST\_PROXY=1</code>           | Enables forwarded client IP only behind a loopback proxy           |

Use independent random values for the signing, HMAC, and delivery settings. Store them in the deployment secret manager. If <code>GEO\_OPERATION\_TOKEN\_SECRET</code> is absent, the application creates <code>apps/web/data/.operation-token-secret</code> with mode 0600. That file must persist across restarts and instances, so an environment-managed secret is easier to operate in a replicated deployment.

## Operator integrations

Configure the integrations used by the chosen workflows:

| Secret                                                                                                  | Used for                                                       |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| <code>OPENROUTER\_API\_KEY</code>                                                                       | Measurement models, chat, generation, and research model calls |
| <code>EXA\_API\_KEY</code>                                                                              | Exa measurement and research retrieval                         |
| <code>AGENTMAIL\_API\_KEY</code>                                                                        | Workspace inbox provisioning                                   |
| <code>GOOGLE\_PAGESPEED\_API\_KEY</code>                                                                | Pipeline technical audits                                      |
| <code>GOOGLE\_WORKSPACE\_CLI\_CLIENT\_ID</code> and <code>GOOGLE\_WORKSPACE\_CLI\_CLIENT\_SECRET</code> | Google OAuth client used by GA4 and Search Console             |
| <code>GOOGLE\_ANALYTICS\_REFRESH\_TOKEN</code>                                                          | GA4 and Search Console data access                             |
| <code>GOOGLE\_GMAIL\_REFRESH\_TOKEN</code>                                                              | Weekly report email delivery                                   |

These are operator secrets. The worker resolves them from the process or operator root environment. Workspace credential storage is not consulted for OpenRouter, Exa, AgentMail, or PageSpeed.

## Local operator mode

Set <code>GEO\_OPERATOR\_MODE=local</code> only for local development. Fallback access is accepted when:

* The environment is not production
* The request host is an exact loopback host
* The direct peer is loopback

The local session lasts eight hours and uses signed origin and CSRF state.

<Warning>
  Local mode is not a production authentication provider. The production service hook must map a verified identity email to active workspace memberships.
</Warning>

## Worker and metering boundary

The web application launches only allowlisted CLI jobs. A worker receives a signed operation token and calls metering endpoints over loopback to:

* Heartbeat its lease
* Authorize the next provider call
* Record an idempotent cost event
* Seal its manifest
* Settle or release the reservation

Do not expose these loopback endpoints through a public proxy.

## Trusted proxy behavior

By default, the direct peer IP is the client IP. Forwarded IP headers are honored only when <code>GEO\_TRUST\_PROXY=1</code> and the direct proxy peer is loopback. This rule protects API key CIDR restrictions from spoofed forwarding headers.

## Data and permissions

The web database contains credentials, encrypted pending key deliveries, sessions, chat, billing, and team data. Worker log files are private and created with mode 0600. Back up both application and pipeline databases consistently, but do not merge them.

See [Data model](/operations/data-model) for ownership boundaries.