> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/environments.md). # Environments ## Environment Matrix | Environment | Purpose | Current status | | ----------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Local mock | Server and web development with synthetic events | Supported. | | Local real hooks | Real Claude Code or Codex CLI sessions posted through local hooks | Supported after `factionos init` for Claude Code or `factionos init --cli codex` for Codex CLI. | | Static public demo | Browser-only showcase from `public-demo/` | Supported and deployed by GitHub Pages workflow. | | Static public website | Astro commercial/product site from `public-website/` | Supported as a local workspace package and static build target; Cloudflare Pages is the recommended deploy posture. | | War Room local Worker | Local Worker testing through Wrangler | Supported by `apps/warroom`, requires Wrangler runtime support. | | War Room deployed Worker | Cloudflare Worker and Durable Object relay | GitHub Actions deploy on `main`, with manual `wrangler deploy` fallback. | | Hosted app or hosted auth | Account-backed hosted product surface | Planned, not current core. | | Hosted persistence or public replay | Account-backed storage and public replay hosting | Planned or disabled, not current core. | | Hosted analytics | Umami-backed optional analytics | Optional browser sender is available when public config and consent are ready; disabled by default. | | Hosted operations | Web Push, VAPID, remote access, tunnels, and operator diagnostics | Guardrails implemented; push delivery, tunnels, remote access, and hosted agents are disabled or unavailable. | | Production-hosted smoke validation | Sanitized public demo, Worker, and optional app-shell release smoke | Supported through `npm run release:hosted-smoke`; no-network mode is credential-free and absent app hosts are no-claim. | ## Local Defaults | Config | Default | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Server port | `2468` | | Server bind host | `127.0.0.1`; non-loopback bind requires `FACTIONOS_ALLOW_NON_LOOPBACK_BIND=true` | | Server mock mode | `FACTIONOS_MOCK=false`; synthetic demo events require explicit `FACTIONOS_MOCK=true` | | Web dev port | `5193` | | Public demo local port | `8101` | | War Room Wrangler dev port | `8790` | | War Room local Worker URL | `http://127.0.0.1:8790` | | War Room local health URL | `http://127.0.0.1:8790/health` | | Local Umami port | `3024` when using the local self-hosted example | | CORS origins | `CORS_ORIGINS` when set; otherwise localhost/127.0.0.1 Vite origins on ports 5193 and 5194 | | WebSocket origins | `FACTIONOS_WS_ALLOWED_ORIGINS`, then `CORS_ORIGINS`, then the same local Vite defaults | | Local auth | Off unless `FACTIONOS_AUTH_TOKEN` is set; then HTTP and WebSocket require the bearer token | | Rate limit | Enabled, 240 requests per 60000 ms | | FactionOS home | `FACTIONOS_HOME` or implementation default | | Local history import | Claude Code and Codex CLI imports are on by default outside tests; imports default to the most recent 200 sessions per provider and can be raised to 1000; opt out per provider with `FACTIONOS_IMPORT_CLAUDE_SESSIONS=false` or `FACTIONOS_IMPORT_CODEX_SESSIONS=false` | | Initial WebSocket mission hydration | `FACTIONOS_WS_HYDRATION_MISSION_LIMIT` or `80`; capped at `200`. Non-active mission tool-use arrays are compacted to `FACTIONOS_WS_HYDRATION_TOOL_USE_LIMIT` or `20`, capped at `100`. Full imported history remains available through HTTP mission snapshots. | | Codex hook config home | `CODEX_HOME` when set; otherwise the Codex user config directory | | Backup output | `FACTIONOS_BACKUP_DIR` or `~/.factionos/backups/` | | Backup retention | `FACTIONOS_BACKUP_RETENTION_DAYS` or `30` | | WebSocket URL for adapters | `ws://localhost:2468/` | ## Current Environment Variables ## Local Env File Layout | File | Status | Purpose | | ----------------------------- | ------- | -------------------------------------------------------------------------------- | | `.env.local` | ignored | Primary local source of truth for server, hooks, CLI, and adapters. | | `.env.local.example` | tracked | Commit-safe inventory for the primary local env file. | | `apps/web/.env.local` | ignored | Vite/browser-visible `VITE_` values. Required when local server auth is enabled. | | `apps/web/.env.local.example` | tracked | Commit-safe browser env template. | | `apps/server/.env` | ignored | Server package fallback when running the server in isolation. | | `apps/server/.env.example` | tracked | Commit-safe server fallback template. | | `apps/adapters/.env` | ignored | Adapter package fallback when running adapters in isolation. | | `apps/adapters/.env.example` | tracked | Commit-safe adapter fallback template. | Server, hooks, CLI, and adapters load root env first, then package fallback env. Earlier values win and blank placeholders are ignored. Vite is different: browser-visible values belong in `apps/web/.env.local` unless they are exported into the shell before the web process starts. `scripts/relaunch.mjs` loads root, web, and server local env files before it reads `FOS_` controls, ports, local service settings, and app startup values. Exported shell variables still win, blank placeholders are ignored, and the root `.env.local.example` inventories the supported relaunch values. Relaunch runs its test gate with provider transfer, startup session imports, browser auth defaults, analytics, Umami, Wrangler dev opt-in, and `VITE_FACTIONOS_WARROOM_WORKER_URL` disabled so tests stay deterministic even when private ignored env files configure live local integrations. The subsequent build and app startup receive the loaded local env plus the operator's normal shell environment. ### Server * `PORT` * `FACTIONOS_BIND_HOST` * `FACTIONOS_ALLOW_NON_LOOPBACK_BIND` * `FACTIONOS_MOCK` * `CORS_ORIGINS` * `FACTIONOS_WS_ALLOWED_ORIGINS` * `FACTIONOS_AUTH_TOKEN` * `FACTIONOS_HOME` * `FACTIONOS_SCAN_ROOTS` * `FACTIONOS_LOGS_DIR` * `FACTIONOS_WS_HYDRATION_MISSION_LIMIT` * `FACTIONOS_WS_HYDRATION_TOOL_USE_LIMIT` * `FACTIONOS_BACKUP_DIR` * `FACTIONOS_BACKUP_RETENTION_DAYS` * `FACTIONOS_IMPORT_CODEX_SESSIONS` * `FACTIONOS_CODEX_IMPORT_LIMIT` * `CODEX_HOME` * `FACTIONOS_IMPORT_CLAUDE_SESSIONS` * `FACTIONOS_CLAUDE_IMPORT_LIMIT` * `CLAUDE_HOME` * `FACTIONOS_AUTO_IMPROVE` * `FACTIONOS_RATE_LIMIT_ENABLED` * `FACTIONOS_RATE_LIMIT_MAX` * `FACTIONOS_RATE_LIMIT_WINDOW_MS` * `FACTIONOS_TRUST_PROXY` * `ANTHROPIC_API_KEY` * `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER` * `FACTIONOS_LLM_TIMEOUT_MS` ### Web * `VITE_FACTIONOS_AUTH_TOKEN` * `VITE_FACTIONOS_SERVER_PORT` * `VITE_FACTIONOS_WARROOM_WORKER_URL` * `VITE_FACTIONOS_ANALYTICS_PROVIDER` * `VITE_FACTIONOS_ANALYTICS_ENABLED` * `VITE_FACTIONOS_ANALYTICS_CONSENT` * `VITE_FACTIONOS_ANALYTICS_OPT_OUT` * `VITE_UMAMI_HOST_URL` * `VITE_UMAMI_WEBSITE_ID` * `VITE_FACTIONOS_APP_VERSION` * `VITE_FACTIONOS_BUILD_VERSION` `VITE_FACTIONOS_WARROOM_WORKER_URL` is optional and browser-safe. Leave it blank for local-only War Room mode. When set, use only a public Worker origin such as the local Wrangler URL, the workers.dev URL, or the custom Worker domain. Users can still override or clear the URL through browser War Room hints. ### Hooks And CLI * `FACTIONOS_SERVER_URL` * `FACTIONOS_WEB_URL` * `FACTIONOS_RUNTIME_ROOT` * `FACTIONOS_AUTH_TOKEN` * `FACTIONOS_SESSION_ID` * `FACTIONOS_TTY` * `FACTIONOS_FACTION` * `FACTIONOS_RESTRICTED` * `FACTIONOS_CLI` * `FACTIONOS_HOOKS_ROOT` * `CODEX_HOME` * `CLAUDE_PLUGIN_ROOT` * `FACTIONOS_HOOK_TIMEOUT_MS` * `FACTIONOS_MAX_SPOOL_FILES` * `FACTIONOS_MAX_SPOOL_BYTES` * `FACTIONOS_DISABLE_LISTENER` * `CLAUDE_CODE_MODEL` * `CURSOR_BIN` * `CURSOR_SESSION` * `OPENCODE_VERSION` `CODEX_HOME` is optional and affects where the Codex installer reads and writes user-level Codex hook config. The server also uses it to find historical Codex sessions for startup import. If it is unset, `factionos init --cli codex` uses the Codex user config directory and writes managed hooks to that directory's `hooks.json`; the server imports from the default Codex home. `CLAUDE_HOME` is optional and affects where the server looks for historical Claude Code project transcripts during startup import. If it is unset, the server imports from the default Claude home. `FACTIONOS_CLI=codex-cli` is installer-managed for Codex hook commands. The CLI injects it into managed hook command strings so hook handlers report the provider consistently. Users should not normally export `FACTIONOS_CLI` just to run Codex hooks, and docs should not present it as a manual setup step. ### Adapters * `FACTIONOS_WS_URL` * `FACTIONOS_AUTH_TOKEN` * `FACTIONOS_ADAPTER_MIN_INTERVAL_MS` * `FACTIONOS_ADAPTER_SEVERITY` * `DISCORD_WEBHOOK_URL` * `DISCORD_BOT_NAME` * `DISCORD_BOT_AVATAR_URL` * `TELEGRAM_BOT_TOKEN` * `TELEGRAM_CHAT_ID` * `TELEGRAM_THREAD_ID` * `FACTIONOS_WEBHOOK_URL` * `FACTIONOS_WEBHOOK_AUTH_HEADER_NAME` * `FACTIONOS_WEBHOOK_AUTH_HEADER_VALUE` * `FACTIONOS_WEBHOOK_PAYLOAD_SHAPE` * `FACTIONOS_WEBHOOK_USER_AGENT` * `FACTIONOS_WEBHOOK_TIMEOUT_MS` ### War Room And Future Hosted Surfaces * `FACTIONOS_RUN_WRANGLER_DEV` * `FACTIONOS_WARROOM_LOCAL_URL` * `FACTIONOS_WARROOM_LOCAL_HEALTH_URL` * `CLOUDFLARE_ACCOUNT_ID` * `CLOUDFLARE_API_TOKEN` * `CLOUDFLARE_ZONE_ID` * `CLOUDFLARE_PAGES_PROJECT_NAME` * `CLOUDFLARE_PAGES_CUSTOM_DOMAIN` * `CLOUDFLARE_WARROOM_WORKER_URL` * `CLOUDFLARE_WARROOM_HEALTH_URL` * `CLOUDFLARE_WARROOM_CUSTOM_DOMAIN` * `CLOUDFLARE_WARROOM_CUSTOM_URL` * `CLOUDFLARE_WARROOM_CUSTOM_HEALTH_URL` * `CLOUDFLARE_WARROOM_WORKERS_DEV_HEALTH_URL` * `CLOUDFLARE_WARROOM_WORKER_HEALTH_URL` * `FACTIONOS_PUBLIC_DEMO_URL` * `FACTIONOS_PRODUCTION_APP_URL` * `FACTIONOS_HOSTED_APP_URL` * `CLOUDFLARE_TUNNEL_TOKEN` * `SUPABASE_URL` * `SUPABASE_PUBLISHABLE_KEY` * `SUPABASE_ANON_KEY` * `SUPABASE_SECRET_KEY` * `SUPABASE_SERVICE_ROLE_KEY` * `VITE_SUPABASE_URL` * `VITE_SUPABASE_PUBLISHABLE_KEY` * `FACTIONOS_ANALYTICS_PROVIDER` * `FACTIONOS_ANALYTICS_ENABLED` * `UMAMI_HOST_URL` * `UMAMI_WEBSITE_ID` * `UMAMI_API_KEY` * `VAPID_PUBLIC_KEY` * `VAPID_PRIVATE_KEY` * `VAPID_SUBJECT` ### Local Demos, E2E, And Relaunch Helpers * `FACTIONOS_DEMO_PORT` * `FACTIONOS_DEMO_PREFIX` * `FACTIONOS_E2E_SERVER_HOST` * `FACTIONOS_E2E_SERVER_PORT` * `FACTIONOS_E2E_WEB_HOST` * `FACTIONOS_E2E_WEB_PORT` * `FACTIONOS_E2E_DEMO_PORT` * `FOS_SERVER_PORT` * `FOS_WEB_PORT` * `FOS_WEB_FALLBACK_PORT` * `FOS_ALLOW_BUILD_WARNINGS` * `FOS_RELAUNCH_SKIP_CODEX_INIT` * `FOS_RELAUNCH_SKIP_UMAMI` * `FOS_UMAMI_DIR` * `FOS_UMAMI_PORT` * `FOS_UMAMI_REQUIRED` * `FOS_UMAMI_READY_TIMEOUT_MS` * `FACTIONOS_DEV_SERVER_READY_TIMEOUT_MS` * `FACTIONOS_DEV_QUEST_BOARD_READY_TIMEOUT_MS` `FACTIONOS_WARROOM_LOCAL_URL` and `FACTIONOS_WARROOM_LOCAL_HEALTH_URL` are operator reference values for local Wrangler diagnostics. They are not required for core local development and are not consumed by the browser runtime. Cloudflare credentials and ids are deploy/operations inputs only. Core local server and web workflows do not require them, and the browser must not receive Cloudflare account ids, API tokens, zone ids, or tunnel tokens. `FACTIONOS_PUBLIC_DEMO_URL`, Worker health URL overrides, and optional app-shell URLs are consumed only by `npm run release:hosted-smoke`. Production smoke targets must be HTTPS URLs without credentials, query strings, fragments, or localhost hosts unless an operator explicitly uses the local-compatibility flag for non-release checks. These values are not browser config and do not enable hosted auth, hosted storage, analytics, push, remote access, tunnels, or trusted erasure. `public-website/` has no required environment variables for local development or build-time typechecking. It uses the repository Node baseline and package scripts instead of a dedicated browser-visible env surface. The hosted auth, hosted storage, analytics, push, and tunnel variables are reserved for future phases unless current code explicitly consumes them. Reserved Supabase, OAuth-provider, and hosted-auth-shaped variables do not enable hosted identity, SSO, organization membership, account UI, analytics consent, public replay hosting, push, remote access, or trusted erasure. Phase 07 Session 03 exposes only planned or unavailable hosted identity posture. Reserved Supabase, storage, and public replay placeholders also do not enable hosted persistence, database clients, buckets, migrations, upload endpoints, browser direct storage writes, account-backed persistence, public replay pages, takedown runtime, release-grade deletion, or trusted erasure. Phase 07 Session 04 exposes only planned or unavailable hosted persistence posture and disabled public replay hosting. Reserved analytics placeholders do not enable analytics capture by themselves. The web client can send approved minimized Umami events only when `VITE_FACTIONOS_ANALYTICS_ENABLED=true`, `VITE_FACTIONOS_ANALYTICS_PROVIDER=umami`, `VITE_UMAMI_HOST_URL`, `VITE_UMAMI_WEBSITE_ID`, and granted consent are present, and opt-out is not active. `UMAMI_API_KEY` and `VITE_UMAMI_API_KEY` are not browser sender inputs. Local self-hosted Umami verification uses `http://localhost:3024` and a private website id from the local Umami site record; see `docs/runbooks/local-umami-analytics.md`. Restart Vite after changing `apps/web/.env.local` so browser-visible `VITE_` values are reloaded. `npm run relaunch` starts the external local Umami Docker Compose checkout before the app when `FOS_UMAMI_DIR` or the default `~/src/umami` exists; use `FOS_RELAUNCH_SKIP_UMAMI=1` to leave it untouched. Reserved VAPID and Cloudflare Tunnel placeholders do not enable push delivery, push subscriptions, VAPID private key use, remote access, tunnels, remote executors, hosted diagnostic agents, production-hosted validation, or trusted erasure. Phase 07 Session 06 exposes planned, disabled, unavailable, or local-only hosted operation posture only. `CLOUDFLARE_TUNNEL_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_ZONE_ID`, `CLOUDFLARE_API_TOKEN`, and `VAPID_PRIVATE_KEY` must not be mirrored into browser config or diagnostics. ## Phase 07 Variable Categories | Category | Meaning | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Active local | Consumed by current local source or tooling. These values must not become hosted-service requirements. | | Public-client | Browser-visible values such as `VITE_FACTIONOS_WARROOM_WORKER_URL` or future publishable hosted values. They must be documented, revocable, non-secret, and optional. | | Server-only secret | Bearer tokens, provider keys, webhook secrets, service-role values, VAPID private keys, and future hosted secrets. Never put these in `VITE_` variables, browser bundles, docs examples, logs, diagnostics, replay, exports, archives, or public demo code. | | Deploy-only | Cloudflare account, API, zone, Pages, Worker, and tunnel values for deployment or operations. Core local workflows must not require them. | | Reserved future | Supabase, Umami, VAPID, push, tunnel, public replay, and hosted-service placeholders that current runtime does not consume unless source explicitly says otherwise. | | Blocked | Raw credentials, account ids, zone ids, tunnel tokens, prompts, files, commands, terminal output, transcripts, exports, replay buffers, scan payloads, media drafts, diagnostics, logs, backups, and historical intake. | The Phase 07 Session 01 variable inventory lives in `.spec_system/archive/phases/phase_07/hosted_services_requirements_privacy_baseline.md`. Presence in `.env.local.example` is not proof of runtime support. Phase 07 Session 07 closeout confirmed these public-client, server-only secret, deploy-only, reserved-future, and blocked boundaries hold across the shipped guardrails: the secret scan passed over 886 tracked text files, browser config exposes only documented public-client values, and no secret, account id, zone id, or tunnel token appears in bundles, diagnostics, logs, or docs examples. Activating any reserved-future variable remains gated on a scoped session (and, for production-hosted use, Phase 08). Phase 08 Session 01 keeps these environment boundaries release-gated in `.spec_system/archive/phases/phase_08/release_requirements_risk_baseline.md`. Presence of Cloudflare, Supabase, Umami, VAPID, tunnel, Worker URL, provider, analytics, or public replay variables remains insufficient to claim hosted identity, hosted storage, analytics capture, public replay hosting, push delivery, remote access, production-hosted validation, certification, or trusted erasure. Later sessions must either record sanitized environment-specific evidence or keep no-claim wording. Phase 08 Session 07 keeps legacy hosted-service and sensitive environment evidence sanitized. Historical service-discovery, token, OAuth, probe, prompt, path, and provider-staging evidence may inform posture conclusions, but stable docs may record only variable names, categories, statuses, booleans, counts, docs paths, and concise no-claim rationale. Do not copy raw env values, account ids, zone ids, service-role values, tunnel tokens, provider payloads, command output, sensitive local paths, generated draft payloads, or quarantined media excerpts into release evidence. Phase 08 Session 08 keeps the same environment boundaries during release-candidate closeout. Local browser and no-network smoke evidence does not require Cloudflare deploy credentials and does not prove deployed hosted readiness. The local closeout environment did not have Cloudflare API token/account/zone values, so Worker or Pages remediation could not be performed. Live hosted smoke issue codes for public demo, Worker, and optional app shell remain no-claim release blockers until rerun from an authorized release environment. ## Hosted Config Diagnostics `GET /diagnostics/hosted-config` returns the source-backed hosted config posture for local operators. The response is status-only: variable name, category, exposure, present or absent posture, enabled or disabled posture, valid or malformed URL posture, reserved or blocked labels, aggregate counts, and docs paths. It does not include raw env values, account ids, zone ids, tunnel tokens, provider keys, webhook URLs, bearer values, local paths, replay data, exports, archives, logs, backups, request bodies, or prompt content. The shared vocabulary lives in `packages/protocol/src/hostedConfig.ts`. `apps/server/src/lib/hostedConfig.ts` consumes it for local diagnostics, and `apps/web/src/lib/hostedConfig.ts` consumes it for browser-visible Vite config. Only documented public-client values are accepted by the browser helper. Blank, absent, malformed, reserved, blocked, credentialed, query-string, fragment, or non-http URL values fall back to local-only behavior. ## Hosted Identity Environment Boundary Hosted identity has no required environment variable today. The shared contract in `packages/protocol/src/hostedIdentity.ts`, server route `GET /diagnostics/hosted-identity`, and browser helper `apps/web/src/lib/hostedIdentity.ts` report planned or unavailable posture only. Phase 08 Session 04 adds a release gate field that remains `no_claim` unless a future scoped session ships active hosted auth evidence. The gate explicitly keeps hosted identity, SSO, organization membership, account UI, analytics consent runtime, public collaboration safety, production audit proof, and trusted erasure unavailable. Setting `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_ANON_KEY`, `SUPABASE_SECRET_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, OAuth provider placeholders, Cloudflare Worker URLs, or `FACTIONOS_AUTH_TOKEN` does not create hosted account identity. Those values also do not prove consent, revocation, account export, account deletion, organization membership, production auditability, analytics consent, or trusted erasure. Future hosted identity activation must introduce explicit source ownership, server-mediated authorization where sensitive data is involved, provider validation, lifecycle controls, audit events, tests, docs, and local-only fallback before any new variable is documented as active identity config. ## Hosted Persistence Environment Boundary Hosted persistence and public replay hosting have no required environment variable today. The shared contract in `packages/protocol/src/hostedPersistence.ts`, server route `GET /diagnostics/hosted-persistence`, and browser helper `apps/web/src/lib/hostedPersistence.ts` report planned or unavailable posture only. Setting `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_ANON_KEY`, `SUPABASE_SECRET_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, Cloudflare Worker URLs, public replay-shaped placeholders, or `FACTIONOS_AUTH_TOKEN` does not create hosted persistence or public replay hosting. Those values also do not prove storage authorization, RLS, migrations, bucket policy, retention, export, deletion, expiration, takedown, no-index posture, abuse controls, production-hosted validation, or trusted erasure. Future hosted persistence activation must introduce explicit source ownership, server-mediated authorization by default for sensitive data, schema artifacts or bucket policy where applicable, payload eligibility tests, consent, retention, export, deletion, audit, abuse controls, docs, and local-only fallback before any variable is documented as active storage or public replay config. ## Hosted Analytics Environment Boundary Hosted analytics has no required environment variable for core local development. The shared contract in `packages/protocol/src/hostedAnalytics.ts` and browser helper in `apps/web/src/lib/hostedAnalytics.ts` report guardrail posture and provide an optional Umami `/api/send` runtime sender. They do not inject scripts, import analytics SDKs, create dashboards, or store account-backed consent. Setting `FACTIONOS_ANALYTICS_PROVIDER=umami`, `FACTIONOS_ANALYTICS_ENABLED=true`, `UMAMI_HOST_URL`, `UMAMI_WEBSITE_ID`, or `UMAMI_API_KEY` does not activate browser analytics by itself. Browser runtime send requires the `VITE_` public-client equivalents for provider, enabled flag, host URL, website id, and consent. Analytics remains off when config is absent, blank, malformed, disabled, missing a website id, lacking consent, or opted out. Opt-out wins over config and consent. The browser helper does not expose raw website id values in readiness output. `VITE_UMAMI_API_KEY` is blocked from hosted browser config metadata and must not be used for `/api/send`. New analytics events or providers must add explicit source ownership, consent UI or operator consent handling, opt-out persistence, payload minimization tests, documentation, and local-only fallback before any new variable is documented as an active analytics runtime requirement. For local self-hosted verification, create the Umami website in the local Umami dashboard, copy only the website id into private browser config, keep the app bound to loopback, and use `docs/runbooks/local-umami-analytics.md` for the smoke and database checks. The local website id is not a reusable project default and must not be committed as shared config. Relaunch starts the local Umami Compose app when available, but it does not create websites, write private browser config, or make analytics required for core local development. ## Hosted Operations Environment Boundary Hosted push, remote access, Cloudflare Tunnel, and hosted diagnostic agents have no required environment variable today. The shared contract in `packages/protocol/src/hostedOperations.ts`, server route `GET /diagnostics/hosted-operations`, CLI status/doctor output, and browser helper `apps/web/src/lib/hostedOperations.ts` report guardrail posture only. Setting `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`, `CLOUDFLARE_TUNNEL_TOKEN`, Cloudflare account ids, zone ids, API tokens, Worker URLs, or custom domains does not activate Web Push, push subscription storage, push delivery, remote access, tunnels, remote executors, hosted diagnostic agents, production-hosted validation, or trusted erasure. Future activation must introduce explicit source ownership, user/operator consent or opt-in, local auth or hosted authorization, token expiration and revocation, Origin/CORS controls, rate limits, audit, abuse controls, redaction, payload minimization tests, docs, and local-only fallback before any variable is documented as active push or remote-access runtime config. ## Data And Privacy Differences | Surface | Data boundary | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Local mock | Synthetic events only. | | Local real hooks | Prompts, paths, command previews, tool metadata, summaries, and local identifiers can enter local server memory, archives, browser replay, and exports. | | Adapters | Selected event summaries are sent to external chat or webhook systems. Discord and Telegram receive formatter output only. Generic webhook defaults to compact formatter output; `FACTIONOS_WEBHOOK_PAYLOAD_SHAPE=full` is an explicit raw-event opt-in for reviewed internal sinks. Formatter output redacts common local paths, command previews, webhook URLs, bot tokens, and auth-header values. | | War Room Worker | Optional external transfer through Cloudflare Workers and Durable Objects. The web client can use a configured Worker for room lifecycle, health diagnostics, approval, presence, reconnect, bounded catch-up, and allowlisted redacted federation. Local-only cockpit use remains available when the Worker URL is blank, invalid, unreachable, timed out, rate-limited, or disabled. | | Future hosted auth | Must define local-only fallback, account lifecycle controls, consent, revocation, data minimization, authorization, audit, and tests before becoming active runtime features. | | Hosted analytics | Config is optional and insufficient without consent and payload controls. Current source can evaluate readiness, scrub payloads, and send approved minimized Umami events only when ready. Local workflows do not require Umami. | | Hosted operation guardrails | VAPID and Cloudflare/Tunnel placeholders are optional and insufficient. Current source reports posture only; push delivery, remote access, tunnels, remote executors, and hosted diagnostic agents remain unavailable. | Phase 05 closeout validates local app browser behavior for the optional Worker URL path. It does not require Cloudflare credentials and does not turn Cloudflare, hosted auth, hosted storage, analytics, push, or tunnel variables into core local development requirements. Phase 06 Session 01 preserves that environment boundary in `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md`. Later collaboration, authority, isolation, and mobile work must keep local mock and local real-hook environments functional without Worker URL, Cloudflare credentials, hosted auth, hosted storage, analytics, public replay hosting, Docker, remote runners, or provider credentials. Future executor, hosted service, analytics, push, remote access, tunnel, or public replay variables remain reserved until the owning phase wires source, tests, consent, redaction, and fallback behavior. Phase 06 closeout confirms the current subset still runs through local mock and local real-hook boundaries without requiring a Worker URL or Cloudflare credentials. Browser evidence may use mocked or same-origin Worker routes for War Room states, but that does not make Worker, hosted auth, hosted storage, analytics, public replay, Docker, remote runner, production-hosted app, or provider variables core environment requirements. --- # 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://faction-os.gitbook.io/faction-os-docs/docs/environments.md?ask=&goal= ``` `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.