Installation

This guide gets a working Cinatra development instance running on your machine: app, database, queue, agent runtime, and local supporting services.

For the first-time configuration steps after the app is running, see Quickstart.

Prerequisites

You need:

Node.js 24 or newer — https://nodejs.org/
pnpm — https://pnpm.io/installation
Docker with the Compose plugin — https://docs.docker.com/get-docker/
Make — already on macOS and Linux; on Windows use WSL

Cinatra runs the app on your host machine and the supporting services (PostgreSQL, Redis, Nango (the OAuth gateway brokering connector credentials), Verdaccio (an npm-compatible registry), Graphiti (a knowledge-graph indexer), WayFlow (Cinatra’s OAS Flow agent runtime), WordPress test instance, Drupal test instance) in Docker. Docker should have at least 6 GB of RAM allocated.

Install with the CLI (recommended)

The fastest path from a fresh machine to a running instance is the published cinatra CLI (npm @cinatra-ai/cinatra). One command does the whole from-zero bootstrap:

npx @cinatra-ai/cinatra install

install is the single, idempotent command for both bootstrapping from zero and reconciling an existing checkout. It runs your prerequisite checks first (Node.js 24+, git, pnpm via Corepack, Docker with the Compose plugin, free ports), then clones Cinatra, creates your .env.local, brings up the Docker services and waits for them, installs Node dependencies, and runs first-time setup inside the freshly cloned checkout — the same work the manual flow below does, in one step. It writes the checkout into a cinatra/ directory under your current working directory by default. Re-running install on an existing checkout skips the clone and just re-runs the reconcile phase — there is no separate setup command to remember.

Useful options:

--mode dev|prod — install mode (default dev); see Dev vs prod below.
--dry-run — show what install would do without changing anything.
--resume — finish an install that was interrupted partway through.

After it completes, cd cinatra and run the rest of the commands from inside that checkout. Two read-only health commands are handy from the start:

npx @cinatra-ai/cinatra status   # show setup state (auth tables, user count, MCP config)
npx @cinatra-ai/cinatra doctor   # diagnose your local setup

To install the CLI globally instead of invoking it through npx, run npm install -g @cinatra-ai/cinatra; the command is then just cinatra.

The rest of this page documents the manual flow — clone the repo yourself and drive setup with the make targets. Use it if you want to manage the checkout yourself or contribute to the platform; the CLI runs these same steps for you.

Dev vs prod

cinatra install takes a --mode dev|prod (default dev if not given). The mode does not by itself change what gets checked out — that is --ref (default main); pin --ref v1.2.3 explicitly if you want a specific release. What the mode changes is the setup path that runs inside the checkout:

--mode dev — the flow this guide walks through: a host-native Next.js dev server against Dockerized Postgres/Redis/Nango/etc.
--mode prod — before touching the database, acquires the production required-extension set with cinatra extensions acquire-prod (downloads tarballs pinned to commit SHAs from the committed lock file, with tree-hash and package.json verification) rather than cloning extension source repos, then runs setup in production mode. cinatra extensions verify-prod is a read-only check that the on-disk extension set, the baked seed, the lock file, what the running instance’s loader registered, and what WayFlow can see all agree.

cinatra update --instance later moves an existing checkout forward by its own recorded type — no --mode flag to pass: a dev checkout fast-forwards to the latest main, a prod checkout moves to the latest v* release tag — then reconciles it.

Clone the repo

git clone https://github.com/cinatra-ai/cinatra.git
cd cinatra

Cinatra is open source under Apache 2.0; any clone of the canonical repository works.

First-time setup

One command:

make setup

That target runs scripts/setup.sh, which does the following in order:

Copies .env.example to .env.local if you do not already have one, and fills in safe defaults for local development.
Starts the supporting services with docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d — Postgres, Redis, Verdaccio, Nango, Graphiti, WayFlow, and the optional test CMS containers. The base compose is safe-by-default (it does not publish the Postgres/Redis/Neo4j ports); docker-compose.dev.yml re-publishes them on 127.0.0.1 so the host-run app can reach them. If you start services manually, include both -f files — a bare docker compose up -d will not expose the DB ports.
Installs Node dependencies with pnpm install.
Runs the app’s setup script (pnpm setup:dev) which creates the configured Postgres schema, applies migrations, and prepares the Better Auth (the auth server library Cinatra uses) tables.
Builds the OpenAI shell image so agents that use the shell tool can run.
Validates the services — runs scripts/check-services.mjs and reports any supporting service that is not reachable. Re-run it any time with make check.

The script is idempotent — running it on an already-set-up environment skips work that is already done.

Start the app

make dev

That brings up the Docker services (if they are not running) and starts the Next.js dev server. Open http://localhost:3000.

The first user to register becomes the initial admin and the owner of the default workspace organization. The setup wizard (at /setup after first sign-in) walks through the remaining one-time configuration: encryption key, instance display name, and the default large language model (LLM) provider key. See Quickstart for the full walkthrough.

Keeping your checkout up to date

After pulling new code, reconcile your dev environment — dependencies and the dev database schema — to match it:

git pull
make refresh

make refresh is dev-only and never touches git: you manage branches, it brings dependencies and the dev database in sync with the code on disk. It applies additive schema changes automatically and then runs the versioned core migration chain (migrations/core/, recorded in the pgmigrations ledger), so transformational changes (renames/backfills) apply automatically too — hand-run release-note migrations are retired. (A fresh schema ledger-records the historical migrations because the bootstrap already creates the current shape; an existing deployment executes only the pending ones.) Restart with make dev afterwards.

Other commands

Command	Purpose
`make dev`	Start infrastructure and the app
`make refresh`	After `git pull`, reconcile dependencies + the dev database schema to the code on disk
`make check`	Validate that every supporting service is reachable
`make down`	Stop infrastructure; keep data
`make logs`	Tail Docker service logs
`make reset`	Soft reset — drop app data, flush Redis, rebuild schemas
`make reset-full`	Hard reset — wipes volumes and `node_modules`, regenerates `.env.local`, reinstalls everything
`make clean`	Remove Docker volumes only (data wipe, no rebuild)
`pnpm typecheck`	Fast type check via `tsgo`
`pnpm lint`	ESLint
`pnpm setup:status`	Inspect current setup state
`pnpm backup:create`	Create a backup bundle of the running instance

Extension CLI commands

A few extension-related operations are available from the cinatra CLI:

Command	Purpose
`cinatra agents install [<name>[@<range>]]`	Install an agent extension tree from the local Verdaccio registry. Writes a `cinatra-agents.lock`.
`cinatra extensions submit <tarball.tgz>`	Submit a built extension tarball to the Cinatra Marketplace for review. Requires `MARKETPLACE_INSTANCE_TOKEN` in the shell env.
`cinatra extensions purge <packageName>`	Remove an extension’s installed state from this instance — its database rows and on-disk files. The registry is left untouched (purge never unpublishes a published version; version cleanup is a separate operation).

There is no general cinatra extensions install command. The only install-style CLI command is cinatra agents install, which installs an agent tree from Verdaccio. General extensions — connectors, skills, artifacts, and workflows — are installed through the UI and MCP surface (browse at /configuration/marketplace, manage installed extensions at /configuration/extensions), not the CLI.

What is running after setup

Once make dev is up, the local processes are:

Next.js app on http://localhost:3000 — the UI and all API routes
PostgreSQL on localhost:5434 — Better Auth + Cinatra app data
Redis on the default port — BullMQ (a Redis-backed job queue), Agent-User Interaction Protocol (AG-UI)/agent-to-UI (A2UI) protocol event log, pub/sub
WayFlow on http://localhost:3010 — agent runtime container
Nango on http://localhost:3003 — OAuth gateway for third-party connector auth
Verdaccio on http://localhost:4873 — the local, private npm-compatible registry in the self-host stack. This is where extensions you author and publish from this instance land, and what cinatra agents install pulls from locally. It is distinct from the hosted endpoints the app talks to for the marketplace experience: the storefront marketplace.cinatra.ai powers marketplace browse and detail, and the public registry registry.cinatra.ai backs the package/manifest reads and install download for first-party extensions. The app references those two hosted endpoints by URL; you do not host or operate them — you only run your own local Verdaccio.
Graphiti on http://localhost:8000 — typed object graph indexer
Test CMS instances (WordPress, Drupal) on their compose-defined ports — used by the CMS connectors during development

You do not need all of these for every use case; the Compose file starts them all because they are cheap and the typical development workflow touches several. Trim the compose profile down if you only need a subset.

There is also an opt-in Plane stack for developing against the PM-tool integration. It is not part of the default make dev set — bring it up only when you need it, with its own compose profile:

docker compose --profile plane up -d

That runs Plane Community Edition on loopback at http://localhost:3400 (a heavier stack, so it stays opt-in). After it’s up, complete Plane’s one-time first-user sign-up and create a workspace, then connect it from Cinatra. The full walkthrough — minting a token, base URL, picking a workspace and project — is in PM-tool integration.

Run make check at any time to confirm each of these services is reachable.

Remote services and the MCP public URL

The services above all run on your machine. Cinatra also depends on remote provider services — the LLM providers (OpenAI, Anthropic, Google). Calls to those are normally outbound and work from any machine with internet access.

The one exception is native Model Context Protocol (MCP): the AI chat hands the LLM provider a reference to your /api/mcp endpoint, and the provider’s servers connect back to it — which a localhost URL cannot satisfy. To use the chat on a local install you expose the app through a tunnel and record the resulting public URL in Cinatra.

See MCP public URL & tunnels for why this is needed, how the three service tiers differ, and a step-by-step Tailscale Funnel (a public-internet tunnel) setup.

Troubleshooting installation

If make setup fails partway through, the most common causes are:

Docker is not running. Start Docker Desktop or the daemon, then re-run make setup.
Port conflicts. Postgres on 5434, Redis on its default port, WayFlow on 3010. If any of those are taken, remap the port and the matching env var in .env.local. The Postgres and Redis host bindings are published by docker-compose.dev.yml (the dev-only override), not the base docker-compose.yml — edit them there; WayFlow’s port is in the base docker-compose.yml.
pnpm install fails on missing native deps. On macOS, install Xcode Command Line Tools (xcode-select --install). On Linux, install build-essential and python3.
App boots but /api/auth/get-session 500s. Usually a missing BETTER_AUTH_SECRET or a stale .next cache. Set the secret in .env.local (32 random hex chars) and run rm -rf .next && pnpm dev.

More patterns are in Troubleshooting.

Where to go next

First-time configuration and your first agent run: Quickstart
Full configuration reference: Configuration
Why the AI chat needs a public URL, and how to set up a tunnel: MCP public URL & tunnels
How the platform is put together: Architecture

Docs content licensed under CC-BY-4.0; embedded code snippets under Apache-2.0.