DocsIntroductionHow it Works

How it Works

RootCX has one foundational component: Core. It's the Rust daemon that runs everything. Every app you create, every AI agent you deploy, every integration you connect runs on a single Core instance that provides the entire backend infrastructure.

You build with whatever tool you prefer: the CLI, Claude Code, RootCX Studio, Cursor, or any code editor. The Core doesn't care how the code was written. It cares that you have a manifest.json, an optional frontend, and an optional backend.

RootCX Architecture

The Core

RootCX Core manages the database, enforces authentication and RBAC, runs your backend processes, serves your frontends, and exposes the REST API. One Core instance runs your entire fleet of apps, whether that's one tool or several hundred.

When you create a project on RootCX Cloud, a dedicated Core instance is provisioned for you. If you self-host, you run the Core on your own infrastructure with Docker.

Build, Deploy, Run

1. Build

A project is composed of:

  • A manifest (manifest.json) that declares entities, fields, and permissions.
  • A frontend -- a React app using the @rootcx/sdk to interact with the Core's Data API.
  • An optional backend -- TypeScript handlers for RPC calls and scheduled jobs, executed by the Core in an isolated Bun process.

Build these with the CLI (rootcx new my_crm), describe them to Claude Code, use the AI Forge in RootCX Studio, or write them by hand.

2. Deploy

Run rootcx deploy from the CLI (or press Run in Studio). The CLI executes a pipeline:

  1. Install dependencies -- runs bun install if a package.json is present.
  2. Build frontend -- runs bun run build if a src/ directory exists.
  3. Install manifest -- sends manifest.json to the Core, which applies entity/field changes to PostgreSQL (creates tables, columns, indexes).
  4. Deploy backend -- uploads and starts the backend worker under the process supervisor.
  5. Publish frontend -- uploads static assets to the Core, which serves them at /apps/{appId}/.

This pipeline is idempotent. Change anything, deploy again, and Core applies the diff.

3. Run

Once deployed, the Core handles everything at runtime:

  • Authentication -- JWT-based sessions (Argon2id password hashing, HS256 tokens) with OIDC Single Sign-On support.
  • RBAC -- global role assignments with inheritance and namespaced permission keys, enforced before any query runs.
  • Data API -- auto-generated CRUD endpoints for every entity declared in the manifest.
  • Backend processes -- supervised Bun workers communicating with the Core via JSON-line IPC.
  • Job Queue -- durable background job scheduling backed by pgmq.
  • Secret Vault -- AES-256-GCM encrypted key-value store, injected as environment variables into backends.
  • Audit Log -- PostgreSQL triggers capture every INSERT, UPDATE, and DELETE. Immutable.
  • Real-time Logs -- stdout/stderr from all backends, streamed via SSE.
  • Channels -- connect messaging platforms (Telegram, Slack) to AI agents for conversational interfaces.
Fleet 3D view with Agent chat

The Fleet model

Every application, AI agent, and integration you deploy runs on the same Core. They share the same database, the same authentication system, and the same permission model. This is what makes them a fleet -- not isolated silos, but interconnected services that can reference each other's data and capabilities.

An AI agent can query data from any application in the fleet. An integration can push external data into entities used by multiple apps. Everything stays consistent because it all flows through the same Core.

Further reading

PreviousGetting StartedNextApplication