Install Headcode through your coding agent, the skills CLI, or by hand. Then point it at your collections and start shipping.
Use this path for a new local project on http://localhost:3000. Draft content is served on http://draft.localhost:3000.
bash rm -f app/page.tsx app/layout.tsx pnpm dlx shadcn@latest add headcodecms/headcodecms/headcode pnpm install pnpm convex dev
Create a WorkOS environment with email-code and social sign-in. Sign-up can stay open: new users can read, and you activate editors with the user metadata
{ "headcode_role": "editor" }{"headcode_role": {{ user.metadata.headcode_role || 'viewer' }}}http://localhost:3000/callbackhttp://localhost:3000/http://localhost:3000/admin/loginbash pnpm convex env set WORKOS_CLIENT_ID "client_..." pnpm convex env set WORKOS_AUTHKIT_DOMAIN "your-app.authkit.app" pnpm convex env set ALLOWED_MCP_TOKENS "$(openssl rand -hex 32)"
Add the matching values to .env.local:
env WORKOS_CLIENT_ID=client_... WORKOS_AUTHKIT_DOMAIN=your-app.authkit.app WORKOS_COOKIE_PASSWORD=at-least-32-characters NEXT_PUBLIC_WORKOS_REDIRECT_URI=http://localhost:3000/callback ALLOWED_MCP_TOKENS=the-same-token
Start the app with pnpm dev, then open http://localhost:3000 and http://localhost:3000/admin.
env NEXT_PUBLIC_HEADCODE_VERSION=auto NEXT_PUBLIC_HEADCODE_DRAFT_HOSTS=draft.example.com NEXT_PUBLIC_SITE_URL=https://www.example.com
MCP clients sign in with OAuth through AuthKit. Enable Client ID Metadata Documents and Dynamic Client Registration in WorkOS and add each /mcp URL as a resource indicator. Clients without OAuth can send a bearer token from ALLOWED_MCP_TOKENS (set in both Convex and the Next.js environment). Use separate MCP client names for draft and live hosts, for example headcode-draft and headcode-live.
Drop the install prompt into Claude Code, Cursor, or any MCP-aware agent. The agent reads your package manager, runs the install, and wires up the workspace.
Install Headcode in this repo and wire up an empty workspace called "acme-marketing".
Skills extend Headcode with first-party recipes - image pipelines, redirects, sitemap generation. Install them with one command and the agent picks them up.
claude skill add @headcode/sitemap
Install Headcode from the shadcn registry, then connect Convex and WorkOS. This is the same path coding agents should use.
rm -f app/page.tsx app/layout.tsx && pnpm dlx shadcn@latest add headcodecms/headcodecms/headcode && pnpm install
A typed schema lives in your repo. The runtime exposes that schema as a typed API, an admin UI, and an MCP server. Every consumer reads the same model.
Writes land on a draft branch by default. Reviewers see the diff plus the rendered preview, then publish or reject. The same flow applies whether the author is human or agent.
Published content is cached at the edge. Publishing triggers tag-scoped revalidation so changes propagate in under a second without a full deploy.
config.ts is the entrypoint. Declare collections, globals, the preview URL, and any agent capabilities. Everything else is derived from this file.
import { defineConfig } from 'headcode'
export default defineConfig({
workspace: 'acme-marketing',
globals: ['header', 'footer', 'homepage'],
})A short checklist to confirm everything is wired correctly before you invite the rest of the team.
pnpm dlx headcode doctor
The blog has deeper write-ups on the architecture decisions and the migration guides we hand to teams moving from a legacy CMS. The admin is where you spend your time once Headcode is running.
Stuck? Open the contact page.