Skip to content
Cinatra Docs

Hosting Guide

This guide is for operators — the people who install Cinatra, configure it, deploy it, and keep it running. It covers prerequisites, environment variables, services, upgrades, and operational troubleshooting.

If you are an end user, see the User Guide. If you administer the /administration/* area, see the Admin Guide. If you work on the code, see the Developer Guide. For the MCP server (external and internal), see the MCP Guide.

Get a working instance

Section titled “Get a working instance”
  • Installation — prerequisites, services, first-time setup, the database, Redis, the WayFlow sidecar
  • Quickstart — start the dev server, register the first admin, run your first agent

Run it well

Section titled “Run it well”
  • Configuration — every environment variable: database, Redis, Better Auth, MCP server, public base URL, Sentry, LLM provider keys
  • Troubleshooting — common failure modes, how to read the logs, when to restart what

What “hosting” means here

Section titled “What “hosting” means here”

Hosting in this guide means the deployment dimension — what processes run, where state lives, how secrets are injected, how the OAuth surface binds to a canonical origin, how upgrades flow.

It does not mean the production runbook for any particular hosting target. Production deployment specifics (Kubernetes manifests, Terraform, CI/CD pipelines, observability stacks) live separately from this open-source repository and depend on your environment.

The Cinatra environment

Section titled “The Cinatra environment”

Beyond the Next.js application itself, Cinatra runs alongside a small set of supporting services. All of them ship in the bundled docker-compose.yml for development; production deployments wire equivalent services from whatever environment you operate.

  • PostgreSQL — the canonical store. Drizzle ORM owns the schema. The default schema name is cinatra (override with SUPABASE_SCHEMA). Better Auth tables live in the public schema.
  • Redis — BullMQ queues, Redis Streams for the AG-UI event log, plus session caches. Default URL is redis://127.0.0.1:6379 (override with REDIS_URL).
  • WayFlow Python sidecar — hosts the OAS Flow runtime that executes agent runs. The Next.js app calls it over A2A. The sidecar is replaceable by any OAS-compliant runtime; see Architecture for the integration contract.
  • Verdaccio — the npm-compatible private registry that backs the extensions marketplace. Cinatra publishes installed agent and skill packages to it and reads other instances’ packages from it. The public marketplace at registry.cinatra.ai runs the same software.
  • Nango — the OAuth gateway that brokers connector credentials (Gmail, Apollo, LinkedIn, and the rest). Nango runs as its own server + dedicated Postgres database; Cinatra calls it via NANGO_SECRET_KEY + NANGO_SERVER_URL.
  • Neo4j + Graphiti — the knowledge-graph derived index for the objects layer. Neo4j stores the graph; the knowledge-graph-mcp (Graphiti) front-end projects objects into it via MCP. The Graphiti projection is asynchronous and lives outside the synchronous primitive path; see Objects layer for how the projector consumes the outbox.

The bundled docker-compose.yml also ships WordPress and Drupal containers, but those are not part of Cinatra’s hosting requirements — they are integration-test target instances used by the Cinatra WordPress and Drupal connectors. A real deployment connects to your own existing CMS instances (or omits them entirely).

The first user is admin

Section titled “The first user is admin”

On a fresh database, the first user to register through the auth surface becomes the platform admin (via Better Auth’s admin plugin). After that, admin grants are issued through /administration/permissions. There is no env var that promotes a user to admin retroactively.

Where production deployment material lives

Section titled “Where production deployment material lives”

Anything operational that’s specific to running Cinatra in production at your organisation — Kubernetes manifests, Terraform modules, your secret-manager wiring, your CI pipeline, your incident runbook — belongs in your own deployment repository, not in the open-source Cinatra repo. This Hosting Guide covers what you need to know about Cinatra to wire it into whatever deployment you operate.

Where to go next

Section titled “Where to go next”