DocsPlatformCore
Core
RootCX Core is a single Rust binary. It runs your internal tools, enforces enterprise governance, supervises backend processes, serves frontends, and exposes the REST API. One Core instance handles one tool or several hundred.
When you create a project on RootCX Cloud, a dedicated Core instance is provisioned for you. When you self-host, you run the same binary on your own infrastructure. Same API surface, same governance.
What the Core does
Every request, every tool call, every data mutation flows through the Core:
| Subsystem | What it handles | Reference |
|---|---|---|
| Authentication | JWT sessions, Argon2id hashing, refresh tokens, OIDC SSO, magic links, password disable | Authentication |
| Governance | Global roles, namespaced permission keys, wildcard matching, inheritance. Enforced in PostgreSQL via Row-Level Security on every query, not in app code. | Governance |
| Audit Log | Immutable, trigger-based. Full before/after JSONB snapshots on every INSERT, UPDATE, DELETE. | Audit Log |
| Secret Vault | AES-256-GCM encrypted key-value store. Secrets injected as env vars into backends. Never returned via API. | Secret Vault |
| Data API | Auto-generated CRUD endpoints from the manifest. Schema Sync Engine handles migrations automatically. | Data API |
| Backend Processes | Isolated Bun workers, supervised with crash recovery (exponential backoff). RPC proxying via JSON-line IPC. | Backend Development |
| Job Queue | Durable background processing backed by pgmq (PostgreSQL). 120s visibility timeout, automatic retry. | Job Queue |
| Scheduled Jobs | Recurring cron schedules powered by pg_cron. Sub-minute intervals, overlap detection. | Scheduled Jobs |
| Webhooks | Inbound HTTP callbacks. 64-character token URLs, stable across deploys. | Webhooks |
| File Storage | Global buckets (platform) + per-app uploads. PostgreSQL-backed (BYTEA). 64 MB max (platform), 50 MB max (app upload). | Storage |
| Channels | Connect messaging platforms (Telegram) to AI agents. Account linking, session routing. | Channels |
| AI Agents | Session memory, supervision policies, approval flows, cross-agent delegation, entity triggers. | Build an AI Agent |
| Integrations | External API connectors. OAuth flows, credential delegation, action catalog. | Build an Integration |
| MCP | Auto-generated MCP tools for every app's entities. Same RBAC enforced. | |
| Real-time Logs | stdout/stderr from backends, broadcast via SSE. | Real-time Logs |
| OIDC Relying Party | Integrate with external identity providers (Okta, Azure AD, Google Workspace, Auth0) for SSO. | Authentication |
| Database Introspection | Browse schemas, tables, columns. Execute read-only SQL queries. | |
| LLM Models | Multi-provider configuration (Anthropic, OpenAI, Bedrock). Default model management. |
Architecture
┌────────────────────────────────────────────────────────────────┐
│ RootCX Core (Rust binary, port 9100) │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ HTTP API (axum) │ │
│ │ Auth · RBAC · CRUD · RPC · Deploy · Agents · Webhooks │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┐ ┌───────┴───────┐ ┌────────────────────┐ │
│ │ Scheduler │ │ Worker Manager│ │ Extension Registry │ │
│ │ (pgmq + cron) │ │ (IPC + Bun) │ │ (audit, oidc, ...) │ │
│ └───────────────┘ └───────────────┘ └────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴──────────────────────────────┐ │
│ │ PostgreSQL 16+ (pgmq extension) │ │
│ │ App schemas · System tables · Job queue · Audit log │ │
│ └──────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
│ (Spawns)
┌────────┴───────────────────────────────────────────────────────┐
│ Backend Workers (Isolated Bun Processes) │
│ ┌──────┐ ┌───────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Apps │ │ AI Agents │ │ Integrations │ │ MCP Servers │ │
│ └──────┘ └───────────┘ └──────────────┘ └──────────────────┘ │
└────────────────────────────────────────────────────────────────┘Extensions
The Core is composed of built-in extensions, each providing routes and lifecycle hooks:
| Extension | Responsibility |
|---|---|
| Audit | PostgreSQL triggers for immutable audit trail |
| Hooks | Entity triggers (auto-enqueue jobs/invoke agents on data changes) |
| Logs | SSE streaming of worker stdout/stderr |
| Auth | JWT sessions, registration, login, token refresh, password disable |
| RBAC | Roles, permissions, assignments, inheritance, wildcard matching |
| Sharing | Share tokens for public access to specific app views |
| OIDC | Relying Party (external SSO) + Identity Provider |
| Magic Link | Passwordless email authentication |
| Agents | Session management, supervision, approvals, fleet stream |
| Integrations | Catalog, deploy, OAuth, credentials, action execution |
| MCP | Model Context Protocol server management |
| Channels | Messaging platform connectors (Telegram) |
| Storage | Per-app file storage with nonce-based upload |
| Platform Storage | Global bucket-based file storage with RBAC |
PostgreSQL
The Core requires an external PostgreSQL 16+ instance with the pgmq and pg_cron extensions. Connection configured via DATABASE_URL. The recommended Docker image (ghcr.io/rootcx/postgresql:16-pgmq-cron) includes both extensions pre-installed.
System tables (rootcx_system schema)
| Table | Purpose |
|---|---|
apps |
Installed applications (manifest, type, status, webhook_token, icon) |
users |
Registered users (email, password_hash, is_system, display_name) |
sessions |
Server-side JWT sessions (user_id, refresh_token_hash, expires_at) |
rbac_roles |
Role definitions (name, description, inherits, permissions) |
rbac_assignments |
User-to-role mappings |
rbac_permissions |
Available permission keys (key, description, source_app) |
audit_log |
Immutable audit entries (schema, table, record_id, operation, old/new) |
secrets |
AES-256-GCM encrypted key-value store (app_id scope, key, nonce, ciphertext) |
cron_schedules |
Scheduled jobs (app_id, name, schedule, timezone, payload, overlap_policy) |
webhooks |
Webhook definitions (app_id, name, method, token) |
agents |
Agent configurations (app_id, name, description, config JSONB) |
agent_sessions |
Agent conversation sessions (messages, total_tokens, turn_count) |
agent_messages |
Individual messages within sessions (role, content, is_summary) |
agent_tool_calls |
Tool call records within sessions (tool_name, input, output, duration) |
entity_hooks |
Entity trigger definitions (app_id, entity, operation, action_type) |
integration_connections |
Per-user integration credentials (integration_id, user_id, kind, label) |
app_integrations |
App-to-integration bindings (app_id, integration_id, connection_id) |
oidc_providers |
OIDC identity provider configurations |
oidc_state |
Pending OIDC authorization state (nonce, redirect) |
llm_models |
LLM model configurations (provider, model, is_default) |
mcp_servers |
Registered MCP server configurations |
files |
File metadata for app-level storage (app_id, name, content_type, size) |
storage_buckets |
Bucket definitions for platform storage |
storage_objects |
Object metadata for platform storage |
channels |
Messaging channel configurations |
channel_identities |
User-to-messaging-platform identity links |
channel_sessions |
Agent conversation sessions via channels |
magic_link_tokens |
Passwordless authentication tokens (token_hash, user_id, expires_at) |
public_shares |
Share tokens for public app access |
Each app also gets its own PostgreSQL schema (named after appId) containing its entity tables.
Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection URL (e.g., postgres://user:pass@host:5432/db). |
|
ROOTCX_BIND |
No | not set | Set to any value to listen on 0.0.0.0 instead of 127.0.0.1. Required for remote access. |
ROOTCX_JWT_SECRET |
No | Auto-generated | String (min 32 characters) for HS256 JWT signing. Auto-generated in config/jwt.key if not set. |
ROOTCX_MASTER_KEY |
No | Auto-generated | Hex-encoded 32-byte key for AES-256-GCM encryption. Auto-generated in config/master.key if not set. |
ROOTCX_PUBLIC_URL |
No | not set | Public URL for OIDC callbacks and magic links (e.g., https://core.example.com). Falls back to ROOTCX_URL. |
ROOTCX_URL |
No | not set | Core instance URL (fallback for ROOTCX_PUBLIC_URL). |
ROOTCX_OIDC_ISSUER |
No | not set | OIDC identity provider URL. Seeds a provider with id "rootcx" on first boot. |
ROOTCX_OIDC_CLIENT_ID |
No | not set | Client ID for OIDC provider. Required if ROOTCX_OIDC_ISSUER is set. |
ROOTCX_OIDC_CLIENT_SECRET |
No | not set | Client Secret for OIDC provider. Required if ROOTCX_OIDC_ISSUER is set. Encrypted in vault. |
ROOTCX_DISABLE_PASSWORD_LOGIN |
No | not set | Set to true or 1 to force SSO-only. A first-user bypass allows initial registration. |
RUST_LOG |
No | info |
Log filter. Values: trace, debug, info, warn, error. |
For production, always provide explicit values for
ROOTCX_JWT_SECRET and ROOTCX_MASTER_KEY. Auto-generated secrets are lost if the container is recreated without persistent storage.Health checks
# Basic liveness
curl http://localhost:9100/health
# {"status":"ok"}
# Full status (memory, CPU, disk, database reachability)
curl http://localhost:9100/health?full=true
# {"status":"ok","memory":{...},"cpu":{...},"disk":{...},"database":{"reachable":true}}
# Authenticated runtime status (requires Bearer token)
curl http://localhost:9100/api/v1/status -H "Authorization: Bearer $TOKEN"Network
| Property | Value |
|---|---|
| Default port | 9100 |
| Default bind | 127.0.0.1 (set ROOTCX_BIND for 0.0.0.0) |
| Protocol | HTTP/1.1 |
| Format | JSON (UTF-8) |
| Max request body | 50 MB (deploy and upload endpoints) |
| CORS | Allows localhost:*, tauri://, *.rootcx.com origins |
Worker supervision
The Core spawns and supervises one Bun process per deployed application (apps, agents, integrations). Communication is via JSON-line IPC over stdin/stdout.
| Property | Value |
|---|---|
| Runtime | Bun |
| IPC protocol | JSON-lines (stdin/stdout), protocol version 2 |
| Crash recovery | Exponential backoff: 0s, 0s, 2s, 4s, 8s, 16s... |
| Crash loop detection | 5 crashes within 60 seconds marks worker as crashed |
| Worker states | starting, running, stopping, stopped, crashed |
| RPC timeout | 30 seconds |
| Job visibility timeout | 120 seconds (unacknowledged jobs re-queued) |
Platforms
The Core is distributed as a Docker image:
| Platform | Architecture | Image |
|---|---|---|
| Linux | x86_64 | ghcr.io/rootcx/core:latest |
| Linux | ARM64 | ghcr.io/rootcx/core:latest |
On RootCX Cloud, the Core is managed for you. For self-hosting, use Docker. See the Self-Hosting guide.
Self-hosting
Run the Core on your own infrastructure with Docker:
docker compose up -d
curl http://localhost:9100/healthSee the Self-Hosting guide for the full Docker Compose configuration, managed database setup, and production hardening.