> 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/onboarding.md). # Onboarding ## Prerequisites * Node.js 26.2.0 or newer for the workspace. * npm 11.16.0 with workspace support. * Git. * Claude Code, only if you want real local CLI sessions to stream into FactionOS. * Codex CLI, only if you want real local Codex sessions to stream into FactionOS. * Cloudflare account and `wrangler login`, only for deploying `apps/warroom`. * Cloudflare Pages access, only for deploying the static `public-website` workspace. ## Setup ```bash git clone https://github.com/moshehbenavraham/factionos.git cd factionos npm install cp .env.local.example .env.local ``` The `.env.local` file is optional for the default mock workflow. Keep it free of real credentials unless you are enabling an optional integration. ## Start The Local App One command starts both the local server and web client: ```bash npm run dev ``` Open `http://localhost:5193`. The server defaults to mock mode, so the web app should show synthetic activity without any CLI hook installation. If you need to run the processes separately: ```bash npm --workspace apps/server run dev npm --workspace apps/web run dev ``` ## Wire Real Local Sessions Claude Code remains the default hook setup: ```bash npm --workspace apps/cli link factionos init factionos start --daemon factionos open ``` Open a new terminal and run Claude Code. When the local server is reachable, a hero should appear in the cockpit and later prompts, tool activity, permission events, and stop events should update the mission timeline. For Codex CLI: ```bash npm --workspace apps/cli link factionos init --cli codex factionos start --daemon factionos open ``` Open a new terminal, run `codex`, and review the loaded hooks with `/hooks` before relying on the integration. The installer writes user-level Codex hooks under `CODEX_HOME` when that variable is set, otherwise in the Codex user config directory. It preserves user-owned hooks, manages only FactionOS command hooks, and does not change Codex auth, provider, telemetry, model, profile, account settings, project trust, or hook trust decisions. Use `factionos init --cli all` when you want both Claude Code and Codex CLI hook maps installed. FactionOS does not create project-local trusted `.codex/` state, bypass `/hooks`, or ship a Codex plugin in this phase. Useful checks: ```bash factionos status --cli all factionos doctor --cli all ``` To remove FactionOS-managed hook entries: ```bash factionos uninstall --cli claude factionos uninstall --cli codex ``` Codex troubleshooting entry points: * If Codex does not show FactionOS hooks, rerun `factionos doctor --cli codex` and check whether the hooks feature is disabled or `hooks.json` is missing. * If hooks are installed but not running, restart Codex and review changed hooks with `/hooks`. * If the cockpit is empty, confirm `factionos start --daemon` is running and `curl http://localhost:2468/health` returns local server health. ## Required Secrets Core local development requires no secrets. | Variable | Required when | Notes | | ---------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_API_KEY` | Real LLM provider calls | Without it, LLM engines use deterministic fallback responses. | | `DISCORD_WEBHOOK_URL` | Discord adapter | User-supplied webhook secret. | | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | Telegram adapter | User-supplied bot credentials. | | `FACTIONOS_WEBHOOK_URL` | Generic webhook adapter | Optional outbound endpoint. | | Cloudflare login or token values | War Room deploy | Not needed for local core development. | | Supabase project values | Future hosted work | Reserved in `.env.local.example`; not required by current core runtime. Keep secret/service-role values server-only and out of `VITE_` variables. | | Umami values | Optional hosted analytics | Not required by core local runtime. Browser analytics sends only when public `VITE_` config and consent are ready. | ## Verify Setup ```bash curl http://localhost:2468/health npm run format:check npm run lint npm run typecheck --workspaces --if-present npm test ``` For a browser-only demo, open `public-demo/index.html` directly. For the static website workspace, use the package-local Astro commands: ```bash npm --workspace @factionos/public-website run dev npm --workspace @factionos/public-website run build ``` --- # 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/onboarding.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.