# Ballerine: self-hosted risk decisioning infrastructure for KYC, KYB and manual review

> Ballerine is an open source monorepo that combines a workflow engine, a case management back office and collection flows for identity and risk decisions. The README states the open source repository is undergoing a major rebuild and is not actively supported at this time.

**ballerine-io/ballerine** — Open-source infrastructure and data orchestration platform for risk decisioning

- Repository: https://github.com/ballerine-io/ballerine
- Website: https://www.ballerine.com
- Stars: 2,440 · Forks: 311
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/ballerine-io-ballerine

## What Ballerine is for: onboarding risk decisions across KYC and KYB

Ballerine targets the point where a payment company, marketplace or fintech has to decide whether to accept a merchant, a seller or a user, and then keep deciding as that relationship changes. The README describes the scope as account opening (KYC, KYB), underwriting and transaction monitoring, with a rules and workflow engine, a plugin system, a manual review back office and frontend flows for collecting documents and information.

The repository is a pnpm monorepo in TypeScript with apps, packages, services, sdks and examples as top-level entries. That layout tells you what kind of adoption this is: you are not installing a single binary, you are running a set of services and frontends that talk to each other. The README frames the value as data ownership through self-hosting, so the intended user is a team with infrastructure capacity and a compliance process it wants to encode rather than rent.

One caveat sits above everything else in the README. A notice states that the open source repository is undergoing a major rebuild and is not actively supported at this time, and it directs people to a Slack workspace, sales@ballerine.com for the SaaS version and oss@ballerine.com for questions about the OSS version. The repository is not archived, and the last push was on 2026-09-17, but the project's own notice is the more useful signal about support expectations than the commit date.

## Workflow engine, back office and collection flows: how the parts connect

The README names four modules that matter for understanding the data flow: a back office for case management and manual decision-making, a workflow engine that orchestrates and automates the different system's parts, KYB collection flows that allow real-time modification of KYC/KYB frontend user journeys, and a plugin system that integrates third-party vendors, APIs and databases. A no-code builder is listed as work in progress.

The workflow engine is the centre. It holds the process definition, so the steps a user goes through are data rather than code baked into a frontend. The collection flow renders those steps, which is why the README can describe journeys that modify in real time based on the user's risk. When a step needs a decision, the engine calls out through the plugin system to a vendor, an API or a database, and when the outcome is not automatic, the case lands in the back office for a human to review.

The demo described in the README ties these together with four moving parts: document collection, a manual review back office, live communication between the parts through the workflow engine, and a JSON file containing risk rules checked during the flow. The README is explicit that the rule engine is still under construction and is not part of that demo, which is worth reading carefully. The rule types and the no-code builder are the parts of the pitch with the least shipped surface behind them.

## Installing Ballerine locally and running the KYC manual review example

The README gives a local setup path with three prerequisites: Node.js (it suggests installing NVM and then node 21), the latest PNPM, and Docker with docker compose. The root package.json narrows the Node range to >=18.0.0 <22.0.0 and requires pnpm >=8.0.0, so the engines field is the constraint to check against your machine before you start.

Clone the repository first. The README uses the HTTPS URL on the default branch.

```bash
git clone https://github.com/ballerine-io/ballerine.git
```

Then install dependencies and initialise the monorepo. The init step runs a script at ./scripts/init.js through the monorepo:init target, which is what wires the workspace together after a fresh clone.

```bash
pnpm install
pnpm monorepo:init
```

With that done, the README offers two example entry points, one for KYB and one for KYC. For the KYC manual review example, run the script by name.

```bash
pnpm kyc-manual-review-example
```

The script itself is worth reading before you run it, because it explains what you should see. It builds @ballerine/common, runs the @ballerine/workflows-service setup target, then starts the workflows service alongside the web UI SDK and backoffice-v2, waiting on http://localhost:3000/api/v1/_health/ready before the frontends come up. It sets VITE_POLLING_INTERVAL=3, VITE_EXAMPLE_TYPE=kyc and VITE_API_KEY=secret through cross-env. The KYB variant, pnpm kyb-manual-review-example, uses VITE_EXAMPLE_TYPE=kyb and starts the kyb-app instead of the web UI SDK. If the health endpoint never answers, the frontends will not start, so that URL is the first thing to check when the example appears to hang.

## The rebuild notice is the limitation that matters most

Most open source projects have a long list of small limitations. Ballerine has one large one, stated by the project itself: the open source repository is undergoing a major rebuild and is not actively supported at this time. That sentence changes how you should read everything else in the README, including the feature list, the demo and the community links.

Practically, it means bug reports may not be triaged, questions may go unanswered, and the interface between modules can move. The release list supports that reading. Recent releases are tagged workflow-service with dev suffixes such as workflow-service@v0.6.732-dev-1bb25933a and workflow-service@v0.6.731-dev-4b8d1a2cc, alongside a hotfix-workflow-service@v0.6.733. A dev-suffixed release stream is a normal pattern for a monorepo that publishes continuously, but it also means the version you pin is the version you are responsible for.

The wrong tool case follows from the same notice. If your organisation needs a vendor to answer a support ticket, or needs a compliance reviewer to point at a maintained product, this repository is not that today, and the README says so before it says anything else. The README also notes that the rule engine is still under construction, so a team whose main requirement is a mature rules engine should treat that module as unproven regardless of the rebuild.

## Ballerine compared with a general workflow engine

The obvious alternative category is a general workflow or orchestration engine such as Temporal, which many teams already run for background jobs. The difference is where the domain lives. A general engine gives you durable execution, retries and timers, and you model the onboarding process yourself: the steps, the document collection UI, the vendor calls and the review queue are all yours to build.

Ballerine ships those pieces as part of the repository. The back office is a case management dashboard for manual decision-making, the collection flow is a frontend journey that can be modified in real time, and the plugin system is the seam for third-party vendors, APIs and databases. You trade control of the execution layer for a starting point that already knows what a review case is.

That trade only pays off if the domain model matches your process. If your risk decisions are mostly automated scoring with a rare manual exception, a general engine plus your own thin review UI may be less to operate than five services and two frontends. If your process is document-heavy, involves several vendors per country, and ends in a human decision, the modules in this repository map to work you would otherwise write from scratch. The README's own framing, self-hosting for data ownership, is the tiebreaker: with a general engine you own the data anyway, but you also own the compliance-shaped parts.

## Maintenance cost, licence status and what to check before committing

Running Ballerine means running a monorepo, not a package. The example scripts start a workflow service, a backoffice frontend and a collection frontend together, and the prerequisites include Docker and docker compose, so the operational surface includes container orchestration, a database behind the workflow service and the Node version window declared in package.json. Upgrades are not a single version bump: the release tags are per-package, and the dev-suffixed workflow-service tags suggest you should read the changelog for the package you depend on rather than the repository as a whole. The repository uses changesets, which is the mechanism behind those per-package versions.

The licence is the item to resolve first. The repository metadata reports the licence as NOASSERTION, which means the automated classifier could not map the LICENSE file to a known identifier. The LICENSE file exists at the repository root, and examples/ has its own LICENSE file, so the two may not be the same. Read both and have your legal review decide what they permit; nothing here should be taken as legal advice.

Before committing engineering time, verify three things in order. Confirm the example runs on your Node version within the >=18.0.0 <22.0.0 range, since the README suggests node 21 while the engines field is wider. Confirm the health endpoint at http://localhost:3000/api/v1/_health/ready responds, because the frontends wait on it. And confirm the LICENSE file matches what your organisation accepts, given the NOASSERTION classification.

## Conclusion

Ballerine suits teams that want to read and modify the orchestration code for onboarding risk decisions, and that can pin to the releases they actually test. Teams that need a supported product with a release cadence should look at the SaaS version the README points to, or at a narrower workflow engine. Before adopting, verify that the example flows run on your Node version, that the workflow service health endpoint answers, and that the licence file matches what your legal review requires.

## FAQ

### Is Ballerine actively maintained?

The repository is not archived, and the last push was on 2026-09-17. The README states that the open source repository is undergoing a major rebuild and is not actively supported at this time, and it points OSS questions to oss@ballerine.com and the Slack workspace.

### What are the prerequisites for installing Ballerine locally?

The README lists Node.js (with NVM and node 21 suggested), the latest PNPM, and Docker with docker compose. The root package.json requires node >=18.0.0 <22.0.0 and pnpm >=8.0.0.

### How do I run the Ballerine KYC manual review example?

After git clone, pnpm install and pnpm monorepo:init, the README gives pnpm kyc-manual-review-example. That script builds @ballerine/common, sets up @ballerine/workflows-service, and starts the workflows service with the web UI SDK and backoffice-v2 once http://localhost:3000/api/v1/_health/ready responds.

### Does Ballerine include a rule engine?

A rule engine is listed as a module, and the demo describes a simple JSON file with risk rules checked during the flow. The README also states that the rule engine is still under construction and is not part of that demo.

### What licence does Ballerine use?

The repository metadata reports the licence as NOASSERTION, meaning the LICENSE file could not be mapped to a known identifier. A LICENSE file sits at the repository root and examples/ has a separate LICENSE file.

## Sources

- [ballerine-io/ballerine on GitHub](https://github.com/ballerine-io/ballerine)
- [Issues](https://github.com/ballerine-io/ballerine/issues)
- [Project website](https://www.ballerine.com)
- [README](https://github.com/ballerine-io/ballerine/blob/dev/README.md)
- [Releases](https://github.com/ballerine-io/ballerine/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ballerine-io-ballerine