Quick start

This walks through scaffolding a brand-new Minamo site and running it locally. It’s written for a developer setting a site up for the first time — once it’s running, day-to-day editing happens in the admin, covered in the marketing manager track.

Requirements

  • Node.js 22.16 or later
  • The git binary on your PATH
  • A directory you’re happy to turn into a real git repository
Note

There is no database and no other external service to provision. Content, drafts, and every publish are real git operations against the site’s own repository — that’s the whole persistence layer.

Scaffold a site

The create-site command generates the four-folder structure described in Core concepts, complete with a starter theme:

Terminal
npx -p @minamocms/framework create-site my-site
cd my-site

This produces a real git repository with an initial commit, a working starter site to build from — a theme/ with a layout, nine sections, eight blocks and site settings, starter pages and menus in content/ — and a vhost/ pointing at a pinned version of the CMS. It also prints a real access token to your terminal — copy it now, it is never shown again.

Install and run

Terminal
cd vhost
npm install
npm start

By default the site listens on port 3000. Visit http://localhost:3000 and you should see the starter theme’s home page rendering the starter content.

While building the theme, use npm run dev instead: it restarts the site whenever a file in theme/ changes. npm run stop stops the site from any terminal, and npm run check renders every page and reports anything broken. See Working on a site locally.

Building with an AI assistant?

Every new site includes an AGENTS.md file: a complete brief on building a theme and its content, for coding assistants such as Claude Code or Codex. Point yours at it before asking it to build pages.

Tip

Run npm run tunnel (or node server.js --tunnel directly) instead to also expose the site through a public HTTPS URL, printed to stdout on boot. This is how you point a hosted admin at a site you’re developing locally, without deploying anywhere yet. Don’t leave a tunnel running unattended — anyone with the URL and a valid token can reach it for as long as the process runs.

Connect the admin

The site itself has no login screen of its own — it’s an API. To edit it through the admin:

  1. In the admin, register the site by its URL and the token create-site printed above (scoped to content, theme, and media by default — see the v1 API for what each scope allows).
  2. The admin calls GET /v1/capabilities to confirm it can reach the site and to learn its agent version and content schema version.

Lost that token, or want a second one with narrower scopes for a different client? mint-token generates a fresh one for a site that already exists, without touching any tokens already in use:

Terminal
npx -p @minamocms/framework mint-token my-site --scopes content,theme

From here, everything else — browsing pages, editing sections, publishing — happens in the admin. See Getting started with the admin.

Next steps

Build out the theme

Add your own sections, blocks, and layouts.

 Put it live

Choose a host and deploy once — then pull and push.