> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/environments.md).

# Environments

## Environment Matrix

| Environment       | URL                     | Purpose                   | Status                                       |
| ----------------- | ----------------------- | ------------------------- | -------------------------------------------- |
| Local development | `http://127.0.0.1:5189` | Daily development         | Configured                                   |
| Local preview     | `http://127.0.0.1:4176` | Preview built output      | Port configured; SSR blocked by B010         |
| Wrangler local    | `http://127.0.0.1:8788` | Full Worker SSR testing   | Available via `bun run worker:preview`       |
| Production        | Operator-configured URL | Cloudflare Workers target | Deploy workflow configured; secrets required |

## Local Development Configuration

* Dev server host: `127.0.0.1` (loopback only for security).
* Dev server port: `5189` (strict port mode enabled).
* Preview port: `4176` (strict port mode enabled).
* Wrangler local dev port: `8788`; inspector port: `9231`.
* Generated runtime data: `src/data/live-data.json`.
* Safe fallback data: `src/data/live-data.example.json`.
* Local scheduler timer intent: `data/ai-os.scheduler.example.json` and private `data/ai-os.scheduler.json`.
* Optional saved-time override files: `data/ai-os.time-saved.json` and `data/ai-os.hourly-rate.json` (gitignored private local config).
* Optional Trend Finder visibility file: `data/trend-finder.visibility.json` (gitignored private local config).
* Private aggregate traces: `logs/aggregate-*.jsonl` and `logs/aggregate.latest.jsonl`.
* Dev-only endpoints: `/__live-data`, `/__time-saved-config`, `/__trend-finder-visibility-config`, `/__token`, `/__refresh_data`, `/__run_trend_finder`, `/__refresh_status`, `/__run_dream`, `/__just-installed`, `/__operator-photo`, `/__trend_finder_creator_lens`, `/__hermes_*`, and `/__openclaw_*` endpoints (Vite `configureServer` only).

Local operator capabilities default to full local access, write access, and edit access. Loopback, Host-header, same-run token, validation, confirmation, timeout, redaction, and safe-error controls remain required local safeguards. Public demo safety, third-party source compliance, missing credentials, offline dependencies, and privacy boundaries are explicit exceptions, not the local default.

## Production Configuration

The deployment target is Cloudflare Workers using the following config:

| File             | Purpose                                                         |
| ---------------- | --------------------------------------------------------------- |
| `wrangler.jsonc` | Worker name (`ai-os`), compatibility date, `nodejs_compat` flag |
| `src/server.ts`  | Worker `fetch` handler with SSR error normalization             |

Before first production deployment, configure:

* Cloudflare account and API token.
* GitHub Actions secrets: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, and optional `PRODUCTION_URL` for post-deploy `/health` smoke tests.
* Whether inherited operator telemetry pages remain in the product.
* Whether Trend Finder stores generated reports as static JSON, database rows, or build artifacts.

### Cloudflare Worker Settings

| Setting             | Value                                                         |
| ------------------- | ------------------------------------------------------------- |
| Worker name         | `ai-os`                                                       |
| Compatibility date  | `2026-04-01`                                                  |
| Compatibility flags | `nodejs_compat`                                               |
| Entry point         | `src/server.ts` (resolved to `dist/server/index.js` at build) |
| Static assets       | `dist/client/` (served via Worker assets binding)             |

## Environment Variable Classification

### Required (Production)

None. The app runs with fallback data (`src/data/live-data.example.json`) when no environment variables are set.

### Optional (Private Script Secrets)

These variables are consumed by Bun scripts at dev time. They are not exposed through Vite and are not read by the production Worker bundle. The browser can receive presence/status from generated live data, but never the secret value.

| Variable               | Used By                               | Purpose                                     |
| ---------------------- | ------------------------------------- | ------------------------------------------- |
| `PINECONE_API_KEY`     | `scripts/aggregate.ts`                | Pinecone vector index stats                 |
| `OPENROUTER_API_KEY`   | `scripts/aggregate.ts`                | OpenRouter balance display                  |
| `ANTHROPIC_API_KEY`    | `scripts/aggregate.ts`                | Auth mode detection                         |
| `OPENAI_API_KEY`       | `scripts/aggregate.ts`, Dream tooling | OpenAI-backed local scripts and hero images |
| `APIFY_TOKEN`          | Trend Finder Apify source runtime     | Optional Actor and Dataset collection       |
| `KIE_API_KEY`          | image-generation scripts              | Script-only asset generation                |
| `NOTION_TOKEN`         | `scripts/aggregate.ts`                | Notion integration token for memory graph   |
| `NOTION_API_KEY`       | `scripts/aggregate.ts`                | Backwards-compatible alias for same token   |
| `REDDIT_CLIENT_ID`     | Trend Finder Reddit source runtime    | Optional Reddit API client ID               |
| `REDDIT_CLIENT_SECRET` | Trend Finder Reddit source runtime    | Optional Reddit API client secret           |
| `GITHUB_TOKEN`         | Trend Finder GitHub source runtime    | Optional GitHub API token                   |
| `YOUTUBE_API_KEY`      | Trend Finder YouTube source runtime   | Optional YouTube Data API key               |

OpenAI account-auth credentials generated by `bun run auth:openai -- login` are stored in gitignored `data/openai-account-auth.json`, or in the path set by `AI_OS_OPENAI_ACCOUNT_AUTH_PATH` / `FINDTREND_OPENAI_ACCOUNT_AUTH_PATH` / `FINDTREND_AI_RUNTIME_AUTH_PATH`. The `AI_OS_*` name is the canonical host runtime path selector. The `FINDTREND_*` names remain compatibility names for the Trend Finder runtime.

Codex-account runtime consumers attempt to refresh expired stored auth before reporting the runtime unavailable. If OpenAI rejects the stored refresh token, run `bun run auth:openai -- reauth` to create a fresh browser-account session.

`CODEX_HOME` is separate from Trend Finder runtime auth. It points local Bun scripts at the Codex home used for AI OS host telemetry scans. Keep real values only in `.env.local`; documentation and templates should use placeholders such as `~/.codex`.

`CODEX_APP_SERVER_URL` is optional and separate from `CODEX_HOME`. It lets `bun run aggregate` record Codex app-server readiness metadata when the operator has already started a local listener. The value must be an explicit loopback `http://` or `ws://` endpoint such as `ws://127.0.0.1:4500`. AI OS rejects remote hosts, credentials, paths, query strings, fragments, and unsupported protocols before any probe. Leave it unset for normal CLI-only setups.

### Dev-Only (Local Configuration)

These control local aggregator behavior and are never needed in production.

| Variable                                | Used By                                                                  | Purpose                                                                                             |
| --------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `CLAUDE_OS_OBSIDIAN_PATH`               | `scripts/aggregate.ts`                                                   | Obsidian vault path for memory scan                                                                 |
| `CLAUDE_OS_ANONYMIZE`                   | `scripts/aggregate.ts`                                                   | Toggle username/email redaction (default: on)                                                       |
| `CLAUDE_OS_REDACT_PREVIEWS`             | `scripts/aggregate.ts`                                                   | Toggle file preview redaction (default: on)                                                         |
| `CLAUDE_OS_SHOW_INDEX_NAMES`            | `scripts/aggregate.ts`                                                   | Show real Pinecone index names (default: off)                                                       |
| `CLAUDE_OS_REDACT_NAMES`                | `scripts/aggregate.ts`                                                   | Additional names to redact (comma-separated)                                                        |
| `CLAUDE_OS_OPERATOR_PHOTO_SOURCE_URL`   | `vite.config.ts` via proxy module                                        | Server-side source URL for the local `/__operator-photo` proxy                                      |
| `CLAUDE_OS_PHOTO_ALLOWED_HOSTS`         | `vite.config.ts` via proxy module                                        | Comma-separated host allowlist for `/__operator-photo` proxy (merged with built-in CDN defaults)    |
| `HERMES_HOME`                           | `scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/hermes-scanner.ts`      | Optional Hermes home override for local Hermes status and bridge endpoints                          |
| `HERMES_DASHBOARD_ADMIN`                | `scripts/lib/hermes-admin-bridge.ts`                                     | Current Phase 40 implementation gate for local Hermes write controls; not the future local default  |
| `HERMES_BIN`                            | `scripts/lib/hermes-admin-bridge.ts`                                     | Optional trusted local Hermes executable override for the admin chat endpoint                       |
| `HERMES_DOCUMENTS_DIR`                  | `scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/hermes-admin-bridge.ts` | Optional Hermes documents directory override for reads, deletes, restores, and purge                |
| `HERMES_MIRROR`                         | `scripts/lib/hermes-admin-bridge.ts`                                     | Optional allowed git mirror root for Pantheon persona sync                                          |
| `HERMES_OBSIDIAN_VAULTS`                | `scripts/lib/hermes-admin-bridge.ts`                                     | Optional semicolon/comma/newline-separated allowlist for Obsidian vault connect writes              |
| `HERMES_OBSIDIAN_VAULT`                 | `scripts/lib/hermes-admin-bridge.ts`                                     | Backwards-compatible single-vault Obsidian allowlist value                                          |
| `GIT_BIN`                               | `scripts/lib/hermes-admin-bridge.ts`                                     | Optional git executable override for Hermes Pantheon sync                                           |
| `OPENCLAW_CONFIG_PATH`                  | `scripts/lib/openclaw-scanner.ts`, `scripts/lib/openclaw-dev-bridge.ts`  | Optional direct path to `openclaw.json` for bounded OpenClaw scanner and bridge reads               |
| `OPENCLAW_STATE_PATH`                   | `scripts/lib/openclaw-scanner.ts`, `scripts/lib/openclaw-dev-bridge.ts`  | Optional OpenClaw state directory, or direct config file path, for bounded scanner and bridge reads |
| `OPENCLAW_WORKSPACE_PATH`               | `scripts/lib/openclaw-scanner.ts`, `scripts/lib/openclaw-dev-bridge.ts`  | Optional OpenClaw workspace path used only for sanitized scanner labels                             |
| `OPENCLAW_DASHBOARD_ADMIN`              | `scripts/lib/openclaw-admin-bridge.ts`                                   | Current implementation gate for OpenClaw admin support checks; not the future local default         |
| `CODEX_HOME`                            | `scripts/aggregate.ts` and Codex-aware scanner modules                   | Optional local Codex home path for AI OS host telemetry; falls back to `~/.codex`                   |
| `CODEX_APP_SERVER_URL`                  | `scripts/aggregate.ts` and Codex app-server readiness scanner            | Optional loopback-only Codex app-server health/readiness endpoint; absence is normal                |
| `LOG_LEVEL`                             | `src/lib/logger.ts`                                                      | pino log level (default: `info`)                                                                    |
| `TREND_FINDER_HN_ITEMS`                 | Trend Finder HN adapter                                                  | Hacker News story fetch count per collection run (default: 30, max: 200)                            |
| `AI_OS_AI_RUNTIME_ENABLED`              | AI OS host AI runtime                                                    | Explicit host runtime enable/disable switch                                                         |
| `AI_OS_AI_RUNTIME_PROVIDER`             | AI OS host AI runtime                                                    | Host provider selector (`disabled`, `mock`, `codex-account`, `openai-api`)                          |
| `AI_OS_AI_RUNTIME_MODEL`                | AI OS host AI runtime                                                    | Requested host runtime model                                                                        |
| `AI_OS_AI_RUNTIME_REASONING_EFFORT`     | AI OS host AI runtime                                                    | Requested host runtime reasoning effort                                                             |
| `AI_OS_AI_RUNTIME_BASE_URL`             | AI OS host AI runtime                                                    | Host Codex account-auth backend base URL override                                                   |
| `AI_OS_OPENAI_ACCOUNT_AUTH_PATH`        | AI OS host AI runtime and OpenAI account auth                            | Canonical host path for local account-auth JSON                                                     |
| `AI_OS_DREAM_ENABLED`                   | AI OS Dream scheduler                                                    | Script-only Dream scheduler activation gate                                                         |
| `FINDTREND_APIFY_ACTORS_PATH`           | Trend Finder Apify source runtime                                        | Optional path to editable reviewed Actor source JSON                                                |
| `FINDTREND_APIFY_ACTORS`                | Trend Finder Apify source runtime                                        | Optional inline JSON or compact source config override                                              |
| `FINDTREND_APIFY_DEFAULT_MEMORY_MB`     | Trend Finder Apify source runtime                                        | Default Apify Actor memory in MB                                                                    |
| `FINDTREND_APIFY_DEFAULT_TIMEOUT_SECS`  | Trend Finder Apify source runtime                                        | Default Apify Actor timeout in seconds                                                              |
| `FINDTREND_APIFY_MAX_ITEMS_PER_SOURCE`  | Trend Finder Apify source runtime                                        | Default Dataset item cap per source                                                                 |
| `FINDTREND_AI_RUNTIME_ENABLED`          | Trend Finder AI runtime                                                  | Explicit runtime enable/disable switch                                                              |
| `FINDTREND_AI_RUNTIME_PROVIDER`         | Trend Finder AI runtime                                                  | Provider selector (`disabled`, `mock`, `codex-account`, `openai-api`)                               |
| `FINDTREND_AI_RUNTIME_MODEL`            | Trend Finder AI runtime                                                  | Requested analyst model                                                                             |
| `FINDTREND_AI_RUNTIME_REASONING_EFFORT` | Trend Finder AI runtime                                                  | Requested reasoning effort                                                                          |
| `FINDTREND_AI_RUNTIME_ORIGINATOR`       | Trend Finder AI runtime                                                  | Originator label included with runtime requests and logs                                            |
| `FINDTREND_AI_RUNTIME_BASE_URL`         | Trend Finder AI runtime                                                  | Codex account-auth backend base URL override                                                        |
| `FINDTREND_AI_RUNTIME_AUTH_PATH`        | Trend Finder AI runtime                                                  | Compatibility path for local account-auth JSON                                                      |
| `FINDTREND_OPENAI_ACCOUNT_AUTH_PATH`    | OpenAI account auth and Trend Finder AI runtime                          | Primary path for local account-auth JSON                                                            |
| `FINDTREND_OPENAI_OAUTH_CALLBACK_HOST`  | `bun run auth:openai`                                                    | Loopback host for local OAuth callback                                                              |

For host runtime config, `AI_OS_*` values win over `FINDTREND_*` compatibility values when both are present and valid. Placeholder values such as `auto`, `your_*`, `<provider>`, and `<auth-path>` are ignored. None of these private runtime values have `VITE_` browser aliases.

### Public Browser Configuration

These values are exposed to the browser bundle by Vite, so only put public-safe values here. Restart the dev server after changing `VITE_` values in `.env.local`.

| Variable                            | Used By          | Purpose                                                                                                           |
| ----------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `VITE_CLAUDE_OS_ENABLED_TOOLS`      | Setup wizard     | Enabled tool list                                                                                                 |
| `VITE_CLAUDE_OS_MEMORY_SOURCES`     | Setup wizard     | Memory source list                                                                                                |
| `VITE_CLAUDE_OS_HOURLY_RATE_USD`    | Setup wizard     | Time-value hourly rate, clamped to 20-1500                                                                        |
| `VITE_CLAUDE_OS_DREAM_ENABLED`      | Setup wizard     | Public Dream preference; does not enable scheduler execution                                                      |
| `VITE_CLAUDE_OS_DREAM_FREQUENCY`    | Setup wizard     | `daily` or `weekly`                                                                                               |
| `VITE_CLAUDE_OS_DREAM_TIME`         | Setup wizard     | 24-hour local `HH:mm` time                                                                                        |
| `VITE_CLAUDE_OS_DREAM_WEB_SEARCH`   | Setup wizard     | Public Dream web-search behavior toggle                                                                           |
| `VITE_CLAUDE_OS_DREAM_HERO_IMAGE`   | Setup wizard     | Public Dream hero-image behavior toggle                                                                           |
| `VITE_CLAUDE_OS_OPERATOR_NAME`      | Browser UI       | Dashboard/sidebar display name; overrides onboarding `localStorage`                                               |
| `VITE_CLAUDE_OS_OPERATOR_PHOTO_URL` | Browser UI       | Public avatar/photo URL; overrides onboarding `localStorage`                                                      |
| `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` | Extension system | Extension override list; AI Rogue defaults on unless set to `none`, `trend-finder` opts in, and `all` enables all |

Valid `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` keys are the registered extension IDs in `src/extensions/registry.ts`. Currently `trend-finder` and `ai-rogue` are registered extensions. AI Rogue is production-enabled with no value, a blank value, `all`, `ai-rogue`, or another non-`none` valid list such as `trend-finder`; only `none` removes it from the production default. Trend Finder remains opt-in because its collector is source-backed. Same separator and special-value rules as the tool and memory source lists. Update `.env.local`, not only `.env.local.example`, and restart the dev server after changing this value.

For Trend Finder specifically, this public switch controls browser sidebar visibility, browser enabled state, and script-side collector execution. The extension routes remain statically registered, so direct URLs can still render fixture/demo data from `src/data/live-data.json` when the switch is unset. That fallback route behavior is not collector enablement. The scoped `scheduler:trend-finder:run` path skips when the switch does not enable `trend-finder`, and Apify source execution additionally requires `APIFY_TOKEN` plus explicit reviewed source config.

For AI Rogue specifically, the browser registry enables the extension by default. This public switch controls explicit override behavior only: `none` hides all extension entries, any non-`none` parsed list is merged with the AI Rogue production default, and `all` enables every registered extension. It does not enable collectors, background workers, remote game-content loading, WebGPU-only paths, or any private telemetry export. Phase 34 closed the audited default-enable blockers and recorded the production decision after the closeout gate bundle passed.

Valid `VITE_CLAUDE_OS_ENABLED_TOOLS` keys are `claude_code`, `claude_desktop`, `claude_vscode`, `antigravity`, `codex`, `gemini`, `anthropic_api`, `openai_api`, `openrouter`, and `openclaw`.

Valid `VITE_CLAUDE_OS_MEMORY_SOURCES` keys are `claude_memory`, `chatgpt_memory`, `pinecone`, `obsidian`, `notion`, and `logseq`.

Both list variables accept comma or whitespace separators. Use `none` for an intentional empty list, or `all` for every known key. Boolean Dream values accept `1/0`, `true/false`, `yes/no`, and `on/off`.

### Setup Wizard Precedence

Valid public setup overrides are authoritative on page load. The wizard seeds its state from them, locks the matching controls, and re-applies them after a reload. Browser `localStorage` remains the fallback when no valid override is present.

Empty values, `auto`, invalid-only values, and placeholders such as `your_*` are ignored. Secret values must stay in non-`VITE_` variables. Activation saves the setup result to browser `localStorage` only; it does not write `.env.local`.

If a private script-only value changes, rerun `bun run setup` or `bun run aggregate` so `src/data/live-data.json` can refresh presence/status for the browser.

### Cloudflare-Specific

If future features require runtime secrets (API keys for trend collection), configure them via:

```bash
npx wrangler secret put SECRET_NAME
```

Or in `wrangler.jsonc` under `[vars]` for non-sensitive values.

## Operator Photo Proxy (`/__operator-photo`)

The `/__operator-photo` dev-only endpoint proxies the operator's avatar image configured via `VITE_CLAUDE_OS_OPERATOR_PHOTO_URL` or `CLAUDE_OS_OPERATOR_PHOTO_SOURCE_URL` in `.env.local`. The proxy applies the following safeguards:

| Guard             | Default                                 | Purpose                              |
| ----------------- | --------------------------------------- | ------------------------------------ |
| Host allowlist    | 12 built-in CDN domains                 | Only trusted hosts bypass DNS checks |
| DNS/IP validation | RFC 1918, loopback, link-local rejected | Prevents SSRF to internal networks   |
| Request timeout   | 10 seconds                              | Prevents slow upstream stalls        |
| Redirect limit    | 3 hops                                  | Prevents redirect chain abuse        |
| Response size cap | 5 MB                                    | Prevents memory exhaustion           |
| Scheme validation | `http:` and `https:` only               | Blocks `file:`, `ftp:`, `data:`      |

To extend the host allowlist, set `CLAUDE_OS_PHOTO_ALLOWED_HOSTS` in `.env.local` with comma-separated hostnames. These are merged with the built-in defaults (GitHub, Gravatar, Imgur, Discord, Twitter, LinkedIn, Unsplash, Cloudflare). When no source URL is configured, the endpoint returns an SVG fallback with operator initials.

## Skill Saved-Time File Overrides (`/__time-saved-config`)

The saved-time config endpoint is available only from the local Vite dev server at `http://127.0.0.1:5189`. It supports `GET`, requires loopback access, uses `Cache-Control: no-store`, and reads only these repo-local allowlisted files:

* `data/ai-os.time-saved.json`
* `data/ai-os.hourly-rate.json`

The response reports whether each file was loaded, missing, or invalid. Missing files are a normal `200` response. Malformed files are ignored with sanitized warnings that do not include local paths or raw parse errors.

These files affect only the browser ROI calculator in `useTimeSaved()`. They do not modify observed skill telemetry, `skills.active`, or `src/data/live-data.json`.

## Trend Finder Visibility File Override (`/__trend-finder-visibility-config`)

The Trend Finder visibility config endpoint is available only from the local Vite dev server at `http://127.0.0.1:5189`. It supports `GET`, requires loopback access, uses `Cache-Control: no-store`, and reads only:

* `data/trend-finder.visibility.json`

The file controls optional per-view hidden cards and rows for the Trend Finder browser UI. Missing files are a normal `200` response. Malformed files are ignored with sanitized warnings that do not include local paths or raw parse errors. Browser UI edits still write only to `localStorage` key `ai-os.trend-finder.visibility.v1`.

This file affects only Trend Finder presentation in the local dashboard. It does not mutate generated Trend Finder data, collectors, scores, sources, watchlists, or briefs.

## Trend Finder Creator Lens Bridge (`/__trend_finder_creator_lens`)

The Creator Lens bridge is available only from the local Vite dev server at `http://127.0.0.1:5189`. It supports `GET` and `POST` for the local Creator Lens config used by the next aggregate run. Both methods require loopback access and the per-run `X-Claude-OS-Token` from `/__token`.

The bridge writes only to the gitignored Trend Finder cache directory. It does not expose `.env.local`, account-auth JSON, raw source items, prompts, aggregate traces, or refresh tokens.

## Dream Dashboard Trigger (`/__run_dream`)

The Home Dream Review and Settings buttons post to `/__run_dream` on the local Vite dev server. The endpoint is loopback-only, requires the per-run `X-Claude-OS-Token` from `/__token`, runs the Dream scheduler job with explicit manual enablement, then refreshes live data so the dashboard can show the latest browser-safe Dream projection.

Dream output, runtime state, logs, and auth material remain private local files. The browser receives only the same safe live-data projection used by the rest of the dashboard.

## Hermes Dev Bridge (`/__hermes_*`)

The Hermes dev bridge is available only from the local Vite dev server at `http://127.0.0.1:5189`. It resolves Hermes from `HERMES_HOME` when set and falls back to `~/.hermes`.

Hermes read endpoints read known Hermes files and directories only. Public reads cover connections, Pantheon templates, missions, and documents. Token-gated reads cover profiles, skills, sessions, session detail, memory, and Pantheon. Mutation routes are documented under the current Hermes write bridge below.

| Endpoint                            | Access                                      |
| ----------------------------------- | ------------------------------------------- |
| `/__hermes_status`                  | Loopback only                               |
| `/__hermes_models`                  | Loopback only                               |
| `/__hermes_connections`             | Loopback only                               |
| `/__hermes_pantheon_templates`      | Loopback only                               |
| `/__hermes_missions`                | Loopback only                               |
| `/__hermes_documents`               | Loopback only                               |
| `/__hermes_documents/file?name=...` | Loopback only                               |
| `/__hermes_documents/trash`         | Loopback only                               |
| `/__hermes_profiles`                | Loopback only, `X-Claude-OS-Token` required |
| `/__hermes_skills`                  | Loopback only, `X-Claude-OS-Token` required |
| `/__hermes_sessions`                | Loopback only, `X-Claude-OS-Token` required |
| `/__hermes_session?id=...`          | Loopback only, `X-Claude-OS-Token` required |
| `/__hermes_memory`                  | Loopback only, `X-Claude-OS-Token` required |
| `/__hermes_pantheon`                | Loopback only, `X-Claude-OS-Token` required |

Fetch the token from `/__token` during the same dev-server run. Tokens rotate when the dev server restarts, and Hermes bridge responses use `Cache-Control: no-store`.

### Hermes Write Bridge

The current Phase 40 Hermes write bridge still uses `HERMES_DASHBOARD_ADMIN=1` as an implementation gate. This is not the future local access default. For the current code, set:

```bash
HERMES_DASHBOARD_ADMIN=1 bun run dev
```

or add this to `.env.local` and restart the dev server:

```bash
HERMES_DASHBOARD_ADMIN=1
```

The write bridge is local-only. Every chat, image upload, mission write, Pantheon sync, document mutation, persona write, persona install, and persona delete request requires loopback access and the per-run `X-Claude-OS-Token` from `/__token`.

| Endpoint                       | Access                                           |
| ------------------------------ | ------------------------------------------------ |
| `/__hermes_admin_status`       | Loopback only                                    |
| `/__hermes_chat`               | Loopback, token, and current write gate required |
| `/__hermes_image_upload`       | Loopback, token, and current write gate required |
| `/__hermes_missions/create`    | Loopback, token, and current write gate required |
| `/__hermes_missions/optimize`  | Loopback, token, and current write gate required |
| `/__hermes_missions/tick`      | Loopback, token, and current write gate required |
| `/__hermes_missions/clear`     | Loopback, token, and current write gate required |
| `/__hermes_pantheon_sync`      | Loopback, token, and current write gate required |
| `/__hermes_pantheon/validate`  | Loopback, token, and current write gate required |
| `/__hermes_pantheon/install`   | Loopback, token, and current write gate required |
| `/__hermes_pantheon/create`    | Loopback, token, and current write gate required |
| `/__hermes_pantheon/<id>`      | Loopback, token, and current write gate required |
| `/__hermes_documents?name=...` | Loopback, token, and current write gate required |
| `/__hermes_documents/restore`  | Loopback, token, and current write gate required |
| `/__hermes_documents/trash`    | Loopback, token, and current write gate required |
| `/__hermes_obsidian`           | Loopback, token, and current write gate required |

`HERMES_HOME` is respected by both read and write bridge code. Use a temporary `HERMES_HOME` for local write smoke tests when you do not want writes to touch the default `~/.hermes` directory. `HERMES_BIN` can point chat to a trusted local Hermes executable when the standard install locations are not present.

`HERMES_DOCUMENTS_DIR` overrides the document gallery root for both document views and delete/restore/purge actions. When unset, document reads and writes use `~/Documents/Hermes`.

Pantheon sync needs an allowed local git mirror root. The admin bridge resolves that root from `HERMES_MIRROR`, then `~/.hermes/.mirror_path`, then the default `~/code/hermes-mirror`. The resolved directory must already be a git checkout: the bridge checks for `.git`, copies persona YAML from `~/.hermes/pantheon/personas/` into `pantheon/personas/`, then runs `git add`, `git commit -m "Sync Hermes Pantheon personas"`, and `git push`. A new private repo with only a starter `README.md` and `pantheon/personas/.gitkeep` is enough as long as `git push` works from that checkout.

Obsidian linking is allow-listed separately. Set `HERMES_OBSIDIAN_VAULTS` to a semicolon-, comma-, or newline-separated list of allowed vault roots, or use `HERMES_OBSIDIAN_VAULT` for one vault. The bridge refuses Obsidian write requests for paths outside that allow-list.

Write endpoints are Vite dev middleware only and are not available in the Cloudflare Worker production server. The implemented surface covers chat, image upload, mission orchestration, Pantheon sync, document mutation, and Obsidian actions. Memory editing, session deletion, arbitrary git behavior outside the Pantheon mirror sync, and arbitrary path access remain unimplemented.

## OpenClaw Dev Bridge (`/__openclaw_*`)

The OpenClaw dev bridge is available only from the local Vite dev server at `http://127.0.0.1:5189`. It reads sanitized OpenClaw scanner summaries for the AI OS host cockpit and is not part of Trend Finder extension data.

OpenClaw path overrides are private server-side values. Put them in `.env.local` or the shell environment without a `VITE_` prefix:

```bash
OPENCLAW_CONFIG_PATH=/path/to/openclaw.json
OPENCLAW_STATE_PATH=/path/to/openclaw-state
OPENCLAW_WORKSPACE_PATH=/path/to/workspace
```

Do not add `VITE_` aliases for these values. They are consumed only by server-side scanner and Vite middleware code; the browser receives sanitized summary fields and state labels, never raw path values.

`OPENCLAW_STATE_PATH` may point to a state directory containing `openclaw.json`, or directly to a config file. `OPENCLAW_CONFIG_PATH` takes precedence when set. The bridge falls back to the default OpenClaw config location when no override is configured.

| Endpoint                | Access                                      |
| ----------------------- | ------------------------------------------- |
| `/__openclaw_status`    | Loopback only                               |
| `/__openclaw_dashboard` | Loopback only, `X-Claude-OS-Token` required |
| `/__openclaw_sessions`  | Loopback only, `X-Claude-OS-Token` required |
| `/__openclaw_subagents` | Loopback only, `X-Claude-OS-Token` required |
| `/__openclaw_tasks`     | Loopback only, `X-Claude-OS-Token` required |
| `/__openclaw_skills`    | Loopback only, `X-Claude-OS-Token` required |

Fetch the token from `/__token` during the same dev-server run. Tokens rotate when the dev server restarts, and OpenClaw bridge responses use `Cache-Control: no-store`.

The bridge is metadata-focused. It does not create, update, delete, upload, spawn processes, run shell/git/OpenClaw CLI commands, call Gateway RPCs, or read transcript bodies, raw prompts, command output, logs, repo diffs, credentials, or workspace files.

OpenClaw bridge endpoints are Vite dev middleware only. They are not available from the Cloudflare Worker production server.

### OpenClaw Action Bridge

The current OpenClaw action bridge still uses `OPENCLAW_DASHBOARD_ADMIN=1` as an implementation gate for support checks. This is not the future local access default. For the current code, set:

```bash
OPENCLAW_DASHBOARD_ADMIN=1 bun run dev
```

or add this to `.env.local` and restart the dev server:

```bash
OPENCLAW_DASHBOARD_ADMIN=1
```

The action bridge is local-only. The status endpoint requires loopback access. The action preflight requires loopback access, the per-run `X-Claude-OS-Token` from `/__token`, and the current implementation gate.

| Endpoint                   | Access                                            |
| -------------------------- | ------------------------------------------------- |
| `/__openclaw_admin_status` | Loopback only                                     |
| `/__openclaw_admin_action` | Loopback, token, and current action gate required |

The action endpoint currently validates deploy and spawn preflight requests and returns an explicit unsupported response. It does not create, update, delete, upload, spawn processes, run shell/git/OpenClaw CLI commands, call Gateway RPCs, or write OpenClaw state. Production builds report admin unavailable even when `OPENCLAW_DASHBOARD_ADMIN=1` is set.

That unsupported response is a documented implementation gap, not delivered full-access OpenClaw execution.

`OPENCLAW_DASHBOARD_ADMIN` is also server-only. Do not expose it through a `VITE_` variable or use it as evidence that deploy/spawn execution is implemented.

If a future session proves a real local OpenClaw execution path, smoke tests must use temporary `OPENCLAW_STATE_PATH` and `OPENCLAW_WORKSPACE_PATH` fixtures, not private user OpenClaw state or workspaces.

## Environment File Locations

| File                 | Committed | Purpose                                  |
| -------------------- | --------- | ---------------------------------------- |
| `.env.local.example` | Yes       | Template with placeholder values         |
| `.env.local`         | No        | Local secrets and overrides (gitignored) |
| `.dev.vars`          | No        | Wrangler local dev secrets (gitignored)  |

Keep all real values in `.env.local` or the shell environment.

## Troubleshooting

If `.env.local` changes do not appear in the browser:

* Restart `bun run dev` after changing any `VITE_` value.
* Rerun `bun run setup` or `bun run aggregate` after changing private script-only values.
* Check for ignored placeholders such as `auto`, empty strings, or `your_*`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/environments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.