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:3074. Draft content is served on http://draft.localhost:3074.
bash npx degit headcodecms/headcodecms/apps/local my-site cd my-site pnpm install
Add the values to .env.local:
env BETTER_AUTH_SECRET=at-least-32-characters ALLOWED_MCP_TOKENS=a-random-token NEXT_PUBLIC_SITE_URL=http://localhost:3074 NEXT_PUBLIC_HEADCODE_VERSION=auto NEXT_PUBLIC_HEADCODE_DRAFT_HOSTS=draft.localhost
Start the app with pnpm dev, run pnpm seed once to create the tables and sample content, then open http://localhost:3074/admin and create an account. The first account becomes the editor; later accounts can read until an editor activates them.
This app runs on your laptop: pnpm build && pnpm start is the production build. All data is in storage/ (database and images). To host it on your own server, build the setup from this app; the README lists what it needs (secret, persistent storage/, one process, HTTPS).
MCP clients sign in with OAuth: Better Auth is the authorization server and supports Client ID Metadata Documents and Dynamic Client Registration. Clients without OAuth can send a bearer token from ALLOWED_MCP_TOKENS. 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
Copy the local app, seed the SQLite database, and run it with Node. This is the same path coding agents should use.
npx degit headcodecms/headcodecms/apps/local my-site && cd my-site && 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.