vibecms

The CMS your agents publish into: Markdown posts, versions, and media over scoped MCP or the REST /api/v1 API - you own every post. Every mutation creates activity, and meaningful post changes create versions.

Features

• Clean hosted blog dashboard
• Public blog pages
• Markdown post editor
• R2 media uploads
• D1 database
• Activity history
• Post version history
• Scoped, reveal-once agent tokens with vc_live_ prefixes
• MCP endpoint for trusted agents
• Polar billing for hosted vibecms Cloud
• SELF_HOSTED=true mode without Polar

Connect an MCP client

vibecms exposes standards-based MCP over Streamable HTTP. Hosted vibecms uses https://app.vibecms.dev; self-hosters use their own API host.

Sign-in is required before MCP discovery or tool use: initialize, tools/list, server/discover, and legacy notifications/initialized all require authentication. OAuth clients such as Claude web, desktop and Code offer Connect or Sign in up front. Requests without a bearer receive HTTP 401 with an OAuth resource-metadata challenge; existing API-key users continue sending their bearer key as before. OAuth metadata, trusted CIMD/public-client registration, the static server card and HTTP agent skill files remain public.

Connect Claude Code with the URL, then open /mcp to sign in and approve access:

claude mcp add --transport http vibecms https://app.vibecms.dev/mcp

For a client using an agent key instead, open Connect in the dashboard, create a scoped token, and copy it once. Send it as a bearer credential:

{  "mcpServers": {    "vibecms": {      "type": "http",      "url": "https://app.vibecms.dev/mcp",      "headers": {        "Authorization": "Bearer vc_..."      }    }  }}

Install the client-independent safety, writing and SEO skills (every skill in skills/):

npx skills add https://vibecms.dev --skill '*'

Run npx skills update to stay current. Alternatively, use npx vibecms-cli skills get to save every skill to .agents/skills (pass skill names to select a subset, --dir <path> to choose the folder, or --force to overwrite existing files), or let a connected agent call the skills.list and skills.get MCP tools.

Claude Code users on the hosted service can install every skill and the MCP server as one plugin. The plugin connects using the server URL; open /mcp to sign in and approve access through OAuth:

claude plugin marketplace add moinulmoin/vibecmsclaude plugin install vibecms@vibecms

Directory listing copy and submission notes live in docs/directory-listings.md.

Verify that the credential can read your site with a protected tool call (tools/list now also requires authentication, but only lists tools allowed by its scopes):

curl https://app.vibecms.dev/mcp \  -H "Content-Type: application/json" \  -H "Authorization: Bearer vc_..." \  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sites.get","arguments":{}}}'

A valid token returns the current site in structuredContent; an invalid or missing token returns 401. The approval-first publishing flow is:

sites.get -> posts.format_guide -> draft -> posts.preview  -> latest saved version -> explicit approval  -> posts.publish(postId, expectedVersionNumber) -> returned URL

Fix error and warn SEO findings before asking for publication approval. posts.preview includes deterministic seo findings. For a saved post, use posts.seo_check({postId, focusKeyword?}) or GET /api/v1/posts/{postId}/seo?focusKeyword=deployment. The 31 rules are plain code and run on every plan: 26 for search engines (metadata, headings, links, content, duplicates, indexing, focus keyword) and 5 for AI answers (a short opening paragraph before the first heading, numbers with a source link, sections short enough to quote, steps as lists). vibecms runs no AI model on your posts; your agent answers the judgment questions in the vibecms-seo skill with its own model.

The REST /api/v1 API mirrors the MCP tools with full read/write parity. Post lists return summaries without full Markdown, so fetch a single post body through REST or MCP posts.get:

curl "https://app.vibecms.dev/api/v1/posts?limit=20&offset=0" \  -H "Authorization: Bearer vc_..."

Hosted vibecms Cloud counts MCP and REST against the same workspace API quota. Rate-limit failures are machine-readable: REST returns 429 with RATE_LIMIT, and MCP returns a JSON-RPC rate-limit error.

License

vibecms is licensed under AGPL-3.0-or-later. See LICENSE.

The vibecms name and marks are covered by the trademark guidelines in TRADEMARKS.md.

Scripts

pnpm installpnpm typecheckpnpm lintpnpm testpnpm buildpnpm public:auditpnpm db:migrate:localpnpm db:seed:localpnpm dev

Database migration SQL lives in packages/db/drizzle/ and is shared by both Workers. Local API development, Astro rendering, migrations, and seed commands share the root .wrangler/state directory so both Workers see the same D1 and R2 data.

See plans/README.md for the decision-record index.

Self-host mode

vibecms now has a real self-host switch:

SELF_HOSTED=true

In self-host mode, Polar is optional, billing gates are disabled, and hosted workspace API quotas are not enforced by default. After signup and blog setup, the owner lands on /dashboard; publishing, media uploads, scoped agent access, activity history, and post versions run on the self-hoster's Cloudflare D1/R2 resources.

The repository deploys the same three-Worker topology in hosted and self-hosted modes:

• apps/api/wrangler.jsonc, apps/public/wrangler.jsonc, and apps/og/wrangler.jsonc configure hosted development/production.
• Root wrangler.jsonc configures the self-hosted Hono API + dashboard Worker.
• Root wrangler.public.jsonc configures the self-hosted Astro public-blog Worker.
• Root wrangler.og.jsonc configures the optional self-hosted OG Worker.
• pnpm deploy builds all configured Workers, applies D1 migrations, then deploys API → OG → public (OG first so public's service bindings resolve).

During deploy, configure the root Wrangler files (wrangler.jsonc, wrangler.public.jsonc, and wrangler.og.jsonc unless you omit OG per docs/self-hosting.md). Public blogs are host-only (tenant identity is the host), so the API/dashboard and public blog use separate Worker hosts:

APP_URL=https://vibecms.<your-subdomain>.workers.devBETTER_AUTH_URL=https://vibecms.<your-subdomain>.workers.devPUBLIC_BLOG_DOMAIN=vibecms-public.<your-subdomain>.workers.devSELF_HOSTED=true

The public blog serves at /, /<post-slug>, and /tag/<tag> on PUBLIC_BLOG_DOMAIN; removed /blog/<site-slug>/* path mode is not supported.

The only required self-host secrets are listed in .dev.vars.example:

BETTER_AUTH_SECRET=<generate with openssl rand -hex 32>TOKEN_PEPPER=<generate with openssl rand -hex 32>

Minimal local/self-host env shape (local URLs are not public hosted URLs):

APP_URL=https://vibecms.example.workers.devBETTER_AUTH_URL=https://vibecms.example.workers.devPUBLIC_BLOG_DOMAIN=vibecms-public.example.workers.devSELF_HOSTED=trueBETTER_AUTH_SECRET=<generate with openssl rand -hex 32>TOKEN_PEPPER=<generate with openssl rand -hex 32>

See docs/self-hosting.md for the Cloudflare self-host flow and deploy-button notes.

Launch notes

• Configure shared Cloudflare D1/R2 IDs in apps/api/wrangler.jsonc and apps/public/wrangler.jsonc before production deploy.
• Set API Worker secrets with Wrangler: BETTER_AUTH_SECRET, TOKEN_PEPPER, POLAR_ACCESS_TOKEN, and POLAR_WEBHOOK_SECRET; AUTOSEOPILOT_INTERNAL_SECRET is optional and only enables the managed AutoSEOPilot routes.
• Set product, URL, and host variables in both Worker configs.
• Promote a reviewed commit with gh workflow run deploy-production.yml --ref main -f release_sha=<full sha> -f smoke_mode=authenticated, which runs pnpm deploy:prod: preflights and builds production artifacts, captures backup metadata, migrates D1, deploys OG → public → API, then smokes. Astro sessions are disabled (no SESSION KV).

For self-hosted production, set SELF_HOSTED=true and only BETTER_AUTH_SECRET plus TOKEN_PEPPER are required as secrets; Polar access token/product/webhook secrets are hosted-SaaS only.

Dev deployment

Current Cloudflare development resources are wired in apps/api/wrangler.jsonc and apps/public/wrangler.jsonc:

• API + dashboard Worker: vibecms-api-dev at https://app.basedui.dev
• Public Astro Worker: vibecms-public-dev at https://basedui.dev and *.basedui.dev
• Shared D1 database: vibecms_dev
• Shared R2 bucket: vibecms-assets

Run the full dev deploy/test flow:

pnpm installpnpm typecheckpnpm lintpnpm db:seed:devpnpm deploy:dev

pnpm deploy:dev syncs the development token pepper, applies remote D1 migrations, builds the dashboard assets, deploys the Hono API Worker, deploys the OG Worker, then builds and deploys the Astro public Worker.

For Polar billing, create a sandbox product in Polar and update the dev vars. The committed dev vars already carry sandbox product and launch-discount ids; if you use your own Polar sandbox products, set all four — POLAR_MONTHLY_PRODUCT_ID, POLAR_YEARLY_PRODUCT_ID, POLAR_LAUNCH_DISCOUNT_MONTHLY_ID, and POLAR_LAUNCH_DISCOUNT_YEARLY_ID — in apps/api/wrangler.jsonc under env.development.vars. Checkout selects the configured discounts automatically, so create matching forever-duration discounts that produce $9/month and $75/year, or remove the two discount vars to test list-price checkout:

pnpm --filter @vc/api exec wrangler secret put POLAR_ACCESS_TOKENpnpm --filter @vc/api exec wrangler secret put POLAR_WEBHOOK_SECRETpnpm deploy:dev

Recommended sandbox product setup:

• Recurring subscription product.
• Price: $15/month list, or $150/year if you create a yearly product/price in Polar (launch offer: $9/month, $75/year via discounts).
• Set the monthly product as POLAR_MONTHLY_PRODUCT_ID. If yearly is a separate Polar product, set it as POLAR_YEARLY_PRODUCT_ID. Set both launch discount ids too, or checkout sends the committed sandbox discounts.
• In hosted mode the free boundary is 5 published posts, 5 drafts at a time, and 10 images — no card required — and free blogs show a small "Published with vibecms" link; a subscription unlocks unlimited posts, 10 GB media, analytics, and custom domains, and removes the link. In self-host mode, SELF_HOSTED=true bypasses billing gates entirely and never shows the link.
• Launch entitlement: 1 hosted blog, unlimited posts, 10 GB media, scoped agent access with no monthly request cap (per-minute and per-day guardrails only), activity and version history, and reader + AI discovery analytics.
• Upload policy enforced by the app: JPEG/PNG/WebP/GIF only, 10MB max image size, no video hosting, no generic file hosting.

Recommended minimum Polar organization access token scopes:

• checkouts:write for creating checkout sessions.
• customer_sessions:write for creating customer portal sessions.

You do not need product, order, refund, file, meter, webhook, or subscription write scopes for the current app runtime. Webhooks are verified with POLAR_WEBHOOK_SECRET, not the API token.

In Polar, set the webhook endpoint to:

https://app.vibecms.dev/api/polar/webhook

Subscribe to these webhook events:

• Required: subscription.created, subscription.updated, subscription.active, subscription.past_due, subscription.canceled, subscription.revoked.
• Required for checkout/customer reconciliation fallback: checkout.updated.
• Optional but useful for analytics later: order.paid.

The app currently updates billing state from subscription.* payloads and from successful checkout.updated payloads. Keep the webhook delivery format as raw JSON and copy the endpoint signing secret into POLAR_WEBHOOK_SECRET.