Falcone

A multitenant Backend-as-a-Service (BaaS) platform.

Databases, storage, auth, events, realtime and serverless functions — isolated per tenant, governed by plans and quotas, behind one API.

English ·
Español ·
Français ·
Deutsch ·
中文 ·
Русский

[!WARNING]
Falcone is not production-ready. It is in early, active development.
Public APIs, data schemas, and runtime behavior may change at any time, without notice or a
migration path. There are no stability, security, or support guarantees at this stage, and
the project has not undergone a security audit.
Do not run Falcone for production workloads or entrust it with sensitive data. Use it for
evaluation, experimentation, and development only.

The principle behind Falcone

Most products need the same backend plumbing: a database, file storage, user
authentication, background jobs, an event bus, realtime updates. Building and
operating that plumbing once per application — and again for every customer —
is where teams lose time and where security incidents are born.

Falcone exists to solve that once. It is a multitenant BaaS: a single
platform that serves many isolated tenants, each with their own data, identities
and resources, exposed through one consistent API.

Two ideas hold the whole system together:

1. Tenant isolation is the contract, not a feature.
   Every read and every write is scoped by tenant_id (and, one level down, by
   workspace_id). Identity is resolved at the edge from a token, propagated as
   an explicit context through the gateway, services, the data layer and
   background jobs, and enforced at the database with row-level security and
   per-tenant schemas. Cross-tenant leakage is treated as the cardinal bug.

2. Capabilities are granted by plan, enforced everywhere.
   What a tenant can do — SQL, realtime, webhooks, functions, Kafka, storage — is
   the intersection of its commercial plan, the deployment profile and the
   environment. The gateway gates routes on those capability keys, quotas cap
   consumption per tenant/workspace, and every denial is audited.

The result is a platform where a customer gets a full backend in minutes, and the
operator keeps a single, governable, observable surface — instead of a fleet of
hand-rolled backends.

How it fits together

                        ┌──────────────────────────────────────────┐
   Bearer JWT  ──▶  API Gateway (APISIX)   /v1   idempotency, CORS, │
                    resolve tenant ▸ inject identity, correlation-id │
                        └───────────────┬──────────────────────────┘
                                        ▼
                        ┌──────────────────────────────────────────┐
                        │ control-plane  — 250+ REST endpoints      │
                        │ tenants · workspaces · auth/IAM · pg ·    │
                        │ documents · storage · events · functions ·│
                        │ metrics · plans · quotas · backup ·       │
                        │ flows (/v1/flows) · MCP (/v1/mcp) [Prev.] │
                        └───────────────┬──────────────────────────┘
            ┌───────────────────────────┼─────────────────────────────┐
            ▼                           ▼                             ▼
   provisioning-orchestrator   realtime-gateway / webhook-engine   cdc-bridges
   (sagas, appliers)           scheduling-engine / backup-status   (pg & documents → Kafka)
                               workflow-worker (Flows interpreter)
            │                           │                             │
            ▼                           ▼                             ▼
   ┌────────────────────────────────────────────────────────────────────────┐
   │ PostgreSQL (RLS) · FerretDB+DocumentDB · Kafka · SeaweedFS ·             │
   │ Vault (secrets) · Keycloak (realm-per-tenant IAM + MCP OAuth 2.1) ·      │
   │ Temporal (Flows engine) · Knative (functions + per-tenant MCP runtime)   │
   └────────────────────────────────────────────────────────────────────────┘

The platform is a pnpm + Turbo monorepo of Node.js (ES module) services and a
React + Vite web console, deployed with Helm on Kubernetes and fronted by an
APISIX gateway.

Built for AI: a BaAIS

Falcone begins where any backend platform does — multitenant data, auth, storage, events and
functions behind one API — and aims it at how software is increasingly built and operated:
by, and for, AI agents.

We call this category a BaAIS — a Backend-as-an-AI-Service, a play on "BaaS" for an
AI-native world. (The expansion is intentionally loose; what matters is the direction, not the
acronym.) Concretely, "built for AI" means a tenant's backend is designed to be natively
consumable by agents, not only by application code:

• MCP server hosting (Preview) — a tenant exposes its backend (data, storage, functions) as a
  Model Context Protocol server, so any MCP-capable agent can
  discover and call it under that tenant's own isolation, auth and quotas. The management API is
  served live under /v1/mcp; Instant MCP and the official server work end-to-end.
• Agentic workflows (Preview) — the Temporal-based Flows engine lets tenants define
  durable, multi-step workflows from a JSON-Schema DSL, with a first-party activity catalog whose
  credentials are tenant-scoped — the reliable substrate an agent needs to act across services.

Everything an agent touches stays inside the same contract as the rest of the platform: scoped by
tenant and workspace, gated by plan capabilities, and audited.

Roadmap

Falcone is pre-1.0 and moving quickly; this is near-term direction, not a commitment.

Shipped (Preview). Both flagship AI-native capabilities have landed and are documented; they
remain Preview under the not-production-ready posture above:

• MCP server hosting — the management API is served live under /v1/mcp; Instant MCP and
  the official server work end-to-end (create → curate → publish → call → observe), with
  per-tenant isolation, OAuth, quotas, registry/versioning and audit. Server state is in-memory
  (single-replica) today. (epic #386)
• Flows — durable workflow engine (Temporal) — tenant-defined workflows via a JSON-Schema DSL
  and interpreter worker, a first-party activity catalog with tenant-scoped credentials, triggers
  and a visual designer. (epic #355)

In progress / planned.

• MCP next increments — a durable (Postgres-backed) multi-replica server registry; custom
  (bring-your-own-image) hosting on the live create path; wiring workflows-as-MCP-tools; and a
  direct per-server MCP-protocol connection (the control-plane mediates tool calls today).
• Object storage — MinIO → SeaweedFS (complete). SeaweedFS (Apache-2.0) is the object
  store (ADR-13), deployed by the umbrella chart and enabled by
  default; the former MinIO storage component has been removed. See the
  SeaweedFS Storage Runbook.
• Document store — MongoDB → FerretDB + DocumentDB (complete). FerretDB v2 (Apache-2.0,
  MongoDB-wire-compatible) over a DocumentDB / PostgreSQL engine (MIT) is the document store
  (ADR-14),
  deployed by the umbrella chart; the former MongoDB server component has been removed. The MongoDB
  driver, wire protocol and Mongo-style data API are unchanged. See the
  FerretDB Document-Store Runbook.
• Toward a first stable release — planned. Security review, API/schema stability guarantees,
  and migration tooling (see the notice at the top).

Capabilities

QuickStart with Docker Compose

The repository ships a Compose stack that brings up the real backing services
Falcone talks to — PostgreSQL, Keycloak, Redpanda (Kafka), FerretDB + DocumentDB
(MongoDB-wire document store), SeaweedFS (S3) and Vault — plus an APISIX gateway and an action runner.
This is the fastest way to get a working environment on your machine.

Prerequisites

• Docker with the Compose plugin (docker compose)
• Node.js 20+ and pnpm (via corepack enable) — only needed to run the suites

1. Clone and install

git clone https://github.com/gntik-ai/falcone.git
cd falcone
corepack enable
pnpm install

2. Bring up the stack with Docker Compose

The helper script wires up health checks, migrations, the FerretDB + DocumentDB document store, the
SeaweedFS bucket and the Vault audit device for you:

cd tests/env
./up.sh

…or drive Compose directly if you only want the containers:

docker compose -f tests/env/docker-compose.yml up -d --build
docker compose -f tests/env/docker-compose.yml ps

3. Services and ports

4. Exercise it

# Run the unit / contract / e2e suites against the live stack
pnpm test

# or the public-interface black-box contract suite
bash tests/blackbox/run.sh

5. Tear it down

cd tests/env
./down.sh
# or: docker compose -f tests/env/docker-compose.yml down -v

For a full production-grade deployment (functions runtime, the control-plane and
the web console), use the Helm charts under helm/ and charts/ on a Kubernetes
cluster — see the manifests in deploy/.

Repository layout

apps/            control-plane (REST API surface) · web-console (React UI) ·
                 cli (falcone CLI: mcp init/dev/deploy) · mcp-server-sdk (tenant-scoped MCP tool SDK)
services/        gateway-config, realtime-gateway, webhook-engine, cdc-bridges,
                 scheduling-engine, provisioning-orchestrator, backup-status,
                 workflow-worker (Flows DSL interpreter), audit, adapters,
                 internal-contracts, …
charts/ helm/    Kubernetes / Helm deployment (incl. temporal, workflowWorker, mcp components)
deploy/          APISIX routes, kind/OpenShift bootstrap
tests/           blackbox (contract) · e2e (Playwright, incl. mcp specs) · env (Compose stack)
openspec/        spec-driven change workflow

Third-party software and licenses

Falcone itself is MIT-licensed (see LICENSE). It builds on the third-party
software below. Components marked ⚠ are copyleft or source-available (not OSI open source) —
see the compatibility note that follows.

Platform & infrastructure (deployed as services / images)

Principal application frameworks & libraries (npm)

[!IMPORTANT]
License compatibility — review needed. Falcone's own code is MIT, which is compatible
with consuming all the permissive components above (MIT, Apache-2.0, ISC, BSD, PostgreSQL).
The ⚠ components are not OSI open source and deserve review:

• Redpanda (BSL-1.1 + RCL) and Vault (BUSL-1.1) are copyleft or source-available.
  The former MongoDB (SSPL-1.0) and MinIO (AGPL-3.0) dependencies have been removed
  — replaced by FerretDB (Apache-2.0, ADR-14) and
  SeaweedFS (Apache-2.0, ADR-13) respectively, retiring
  their SSPL/AGPL exposure.
• Running them as separate backing services Falcone talks to over the network does not, by
  itself, impose their license on Falcone's MIT code (no linking / derivative work). But their
  "offer-as-a-service" / "competitive service" clauses are directly relevant to a multitenant BaaS
  that re-exposes their functionality to tenants — a Kafka/events API. In particular, the
  Redpanda/Vault BSL grants exclude competing managed offerings. Review these terms before any
  hosted or commercial offering; both are swappable at the deployment layer if their terms don't
  fit your use.
• Object store: MinIO → SeaweedFS (Apache-2.0). Per
  ADR-13, SeaweedFS is the object store, chosen specifically
  to retire the MinIO AGPL §13 "offer-as-a-service" exposure for a BaaS that re-exposes S3 to
  tenants. The former MinIO dependency has been removed.
• Document store: MongoDB → FerretDB + DocumentDB (Apache-2.0 + MIT). Per
  ADR-14, FerretDB v2 over a DocumentDB / PostgreSQL engine
  is the document store, retiring the MongoDB SSPL §13 exposure. FerretDB keeps the MongoDB
  driver and wire protocol unchanged; the former MongoDB server dependency has been removed.

Not exhaustive. This table lists the principal third-party components, not the full
transitive dependency tree (minor utilities — undici, clsx, lucide-react, uuid,
cron-parser, js-yaml, etc. — are omitted). For a complete picture, generate an SBOM / license
report — e.g. license-checker or pnpm licenses list for the npm workspaces — and, if Python or
Go components are added later, pip-licenses and go-licenses respectively. Review the output
before distribution.

License

See LICENSE.