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, Verdaccio, Graphiti, WayFlow, WordPress test instance, Drupal test instance) in Docker. Docker should have at least 6 GB of RAM allocated.

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 up -d — Postgres, Redis, Verdaccio, Nango, Graphiti, WayFlow, and the optional test CMS containers.
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 tables.
Builds the OpenAI shell image so agents that use the shell tool can run.

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 LLM provider key. See Quickstart for the full walkthrough.

Other commands

Command	Purpose
`make dev`	Start infrastructure and the app
`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

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 queue, AG-UI/A2UI 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 its configured port — local agent-package registry
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.

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, edit docker-compose.yml or the matching env var in .env.local.
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
How the platform is put together: Architecture