marlo-self-hosted-ai-cmo

Open-source AI CMO. Marlo audits your website, finds what's holding it back in search and AI answers, helps you fix it, and only calls a fix verified when it has evidence.

Hosted app · Self-host · Docs · Pricing (beta) · Changelog

Marlo is one Next.js app. Use the hosted version, or self-host it for free with your own API keys. Self-host has every feature unlocked and no plan limits.

Marlo is inspired by Okara. It is an independent project: not affiliated with or endorsed by Okara, and not derived from Okara's code.

What Marlo does

Marlo runs one loop: discover → understand → act → verify. "Verified" always means evidence: a later audit, a re-check, or a real AI-answer run. A click alone never verifies anything.

Step	What happens
Discover	You add a website. Setup audits the homepage, writes a description, finds competitors, and drafts Context documents (product info, marketing strategy, competitor analysis, content strategy, design guide). Progress is saved per project, and setup resumes when you come back.
Understand	Issues become findings, ranked by impact. The Fix first strip shows the top ones. Each finding has its evidence, why it matters, and a recommendation that matches the issue. The Traffic tab (Search Console, GA4) and GEO tracking add search and AI-answer context.
Act	Mark a finding as in progress, ask the coding agent to open a draft GitHub pull request through the GitHub App, or publish a reviewed change to WordPress or Webflow. You approve every external write. Nothing posts or merges by itself.
Verify	Re-check runs the real check again, either when you click it or automatically on hosted. A finding that a newer audit no longer reports is flagged No longer detected and stays open until a re-check proves it. A GEO gap closes only when a later real run names you.

Dashboard	Traffic (Search Console and GA4)
Setup progress, saved per project	Integrations
Mobile	Pricing (beta)

Status

Marlo is in beta. This table says what to rely on today.

Hosted or self-host

You can also run the hosted build on your own Supabase project. See docs/self-hosting.md.

Quick start

Self-host

Requires Node.js 24.12 or newer (engines in package.json) and git.

git clone https://github.com/Kumar2421/marlo-self-hosted-ai-cmo.git
cd marlo-self-hosted-ai-cmo
npm install
echo "NEXT_PUBLIC_SELF_HOST=true" > .env.local
npm run dev

1. Open http://localhost:3000/dashboard. The root URL redirects to the hosted sign-in page, which needs Supabase.
2. To check the setup, open http://localhost:3000/api/system/storage-diagnostics. You should see "storageMode":"sqlite" and "available":true under sqlite.
3. In Settings → LLM Providers, add at least one model key. The providers with drivers are Anthropic, OpenAI, Google, Mistral and Groq, plus a local Ollama or LM Studio server or any other OpenAI-compatible endpoint. Add optional keys under Settings → API Credentials: Tavily for web search, PageSpeed, Gemini for real GEO answers, Google Cloud, and a GitHub token for fix PRs.
4. Add your website. Setup runs while the tab is open.

No environment variables are required in self-host mode. Optional ones, such as Gmail OAuth or Resend email, are listed in docs/environment.md. For a production-style build, run npm run build and then npm start. For full steps and troubleshooting, see docs/self-hosting.md.

Docker

No Node or npm needed:

git clone https://github.com/Kumar2421/marlo-self-hosted-ai-cmo.git
cd marlo-self-hosted-ai-cmo
docker compose up -d --build

Or skip the build: docker run -d -p 127.0.0.1:3000:3000 -v marlo-data:/app/data ghcr.io/kumar2421/marlo:latest.

Open http://localhost:3000/dashboard and add a model key in Settings → LLM Providers. Your data lives in the marlo-data volume. The port is bound to your machine only; to share it, set MARLO_ACCESS_PASSWORD, put HTTPS in front and change the port mapping. Details: docs/self-hosting.md.

Use Marlo from your AI assistant (MCP)

marlo-mcp lets Claude, Cursor, Windsurf and other MCP clients audit a page from chat. Add it to your client:

{ "mcpServers": { "marlo": { "command": "npx", "args": ["-y", "marlo-mcp"] } } }

Claude Code: claude mcp add marlo -- npx -y marlo-mcp. Then ask: "Audit https://mysite.com and tell me what to fix first."

It is read-only and audits one page. Point it at your own server with MARLO_BASE_URL (and MARLO_ACCESS_PASSWORD if you set one). See packages/marlo-mcp/README.md.

Hosted

Sign up at https://app.marlo.mlforge.in. To run your own hosted deployment (Supabase and Vercel), follow docs/hosted-setup.md and docs/self-hosting.md.

How it works

flowchart LR
  U["Browser: dashboard"] -->|setup steps, Re-check| API["Next.js route handlers"]
  API --> D["lib/domain: audit, findings, GEO, search, codefix"]
  D --> S{"Store pair"}
  S -->|self-host| SQ[("SQLite: data/okara.db")]
  S -->|hosted| PG[("Supabase Postgres + RLS")]
  D -->|guarded fetch| WEB["Your site, search and LLM APIs"]
  D -->|GitHub App| GH["Draft pull request"]
  CRON["Vercel Cron (hosted only)"] --> API

• One app, two modes. lib/features.ts chooses the mode. Self-host uses SQLite. Hosted uses Supabase, and a hosted deployment with missing Supabase config fails closed with HTTP 503.
• Store pairs. Each domain store has a SQLite file and a Supabase file, for example findingStore.ts and findingStoreSupabase.ts. The domain logic above them is shared and mostly pure.
• Finding lifecycle. new → acknowledged → fixing → fixed → verified | failed. Only evidence sets verified or failed: a Re-check, the automatic check, or a later GEO run. You cannot set them by hand.

stateDiagram-v2
  [*] --> new: audit / search / GEO gap
  new --> acknowledged
  acknowledged --> fixing
  fixing --> fixed: you mark it, or the fix PR merges
  fixed --> verified: Re-check passes (evidence)
  fixed --> failed: Re-check still detects it
  failed --> fixing
  verified --> fixing: regression
  note right of new: No longer detected is a flag, not a status.<br/>The finding waits for a Re-check.

For data flow, cron jobs, the GitHub App loop and setup state, see docs/architecture.md.

Security

• Auth. Supabase Auth. Server routes verify the user with auth.getUser() and do not trust a client-side session.
• Isolation. Row-level security on user tables. Server-trusted tables (profiles, settings, connections) are read-only to users. Project routes check that the signed-in user owns the project.
• Outbound requests. URLs that users can influence go through one guarded fetcher. It pins DNS, blocks private addresses, re-checks every redirect hop, and caps time and body size.
• OAuth. Google, Gmail and GitHub connect flows use a single-use, expiring state value. On hosted, only the user who started a flow can complete it. Email unsubscribe links use signed, expiring HMAC tokens.
• Keys. The operator's provider keys are never sent to a base URL that a user supplied (#170).
• External writes. Fix PRs and CMS publishes need a signed, expiring approval. PRs are drafts, and nothing auto-merges or auto-posts.
• Cron routes require a CRON_SECRET bearer token, compared in constant time.
• The Content-Security-Policy header is still report-only.

Read docs/security.md for details. To report a vulnerability, follow SECURITY.md and use GitHub private vulnerability reporting, not a public issue.

Plans and pricing

Hosted plans are Free, Lite and Pro, per website, and they are in beta. There is no payment gateway yet, so the paid plans have a waitlist at /pricing. The suggested beta prices are Lite $29/month ($24/month billed annually) and Pro $79/month ($66/month billed annually). Plan enforcement is off, so the plan limits are not active and hosted features are unlocked today. Self-host is always unlocked.

The full feature and limit matrix, generated from lib/domain/plans/planMatrix.ts, is in docs/plans-and-pricing.md.

Roadmap and known limits

Coming next, in order: finish the core loop (findings, re-check, GEO gaps), then audit depth, then hardening. Known limits today:

• Setup runs in your browser. Progress is saved and resumes when you return, but setup does not continue while the tab is closed.
• Shallow crawl. The audit covers 1 page and samples up to 8. A full crawl of hundreds of pages is not built.
• Scheduled jobs have limited coverage. Each cron is one time-boxed run per day (GEO: per week), so a large fleet of sites is covered slowly.
• Payments are not live. Plan limits are defined but not enforced.
• Limited GEO engines. Marlo measures Gemini grounded answers only, and labels the simulated stand-in as simulated.
• No automatic posting to X, LinkedIn or Reddit.
• Lead email checks use SMTP, which most cloud hosts block, so lead emails often show as unverified on hosted.
• E2E suite. The Playwright suite (layout, accessibility, vitals, visual) runs by hand, not in CI, and some accessibility and visual specs fail today.
• CSP is report-only.

Documentation

Contributing

Issues and pull requests are welcome. The rule for features matches the code: use real data or say plainly that it is not available. Never show a plausible-looking fake. If you add a feature, show its empty, loading and error states too.

npm test          # unit tests (node:test, tests/*.test.mts)
npm run lint      # ESLint
npm run build     # production build
npm run e2e       # Playwright (run `npx playwright install chromium` once first)

• Keep PRs small. Each PR should solve one problem end to end. Avoid broad refactors and new abstractions without a consumer.
• CI (.github/workflows/ci.yml) lints the files you changed, runs npm test (and fails if no tests ran), and runs a production build. Full-repo lint is informational only.
• Target main. The pr-base-guard job fails a PR whose base is another branch, unless the PR body says intentional-base.
• See docs/acceptance-gates.md for the definition of done.

License

Marlo is licensed under the GNU Affero General Public License v3.0. If you run a modified version as a network service, you must make its source available to the people who use it.