checkmarble/marble: a self-hosted decision engine for fraud and AML

Who Marble is for, and the problem it removes

Rule-based fraud and AML tooling usually arrives as a closed product. You configure thresholds in someone else's interface, you cannot see why an alert fired, and exporting the underlying data for your own analysis means asking the vendor. Marble takes the opposite position. The README describes it as "the flexible alternative to Comply Advantage, Actimize or Fiserv for Transaction Monitoring, AML Screening and Case investigation", and the tagline is "the best of Build and Buy: keep full control and build on top." The intended audience is explicit: fintechs, banks and crypto exchanges, with a self-hosted option so that, in the README's words, "your data never has to leave your infrastructure."

The problem it addresses is the gap between a detection rule and a defensible case file. A transaction monitoring rule fires, someone has to screen the counterparty against sanctions and PEP lists, open a case, annotate it, and leave a trail that a regulator or auditor can follow. Marble puts those steps in one system: transaction monitoring, customer and company screening, continuous monitoring, an investigation suite, and searchable audit logs for the detection program, workflows and case actions. The README notes that KYC itself is out of scope and expects you to connect a separate provider.

The architecture visible in the Compose file

The repository splits into a Go backend under api, a frontend under front, an installation directory of deployment guides, and a processes directory. The published docker-compose.yaml pins two images, both tagged v1.9.0: marble-backend from europe-west1-docker.pkg.dev/marble-infra/marble/marble-backend and marble-frontend from the same registry. So a default deployment is a backend container, a frontend container, and the surrounding services the environment block implies.

That environment block is the honest description of the data flow. The backend reads PG_HOSTNAME, PG_PORT, PG_USER, PG_PASSWORD and PG_SSL_MODE for its Postgres connection, and REDIS_HOST for Redis. Object storage appears three times: INGESTION_BUCKET_URL for incoming data, CASE_MANAGER_BUCKET_URL for case files, and ANALYTICS_BUCKET_URL for reporting. Sanctions and PEP screening goes through OPENSANCTIONS_API_HOST, OPENSANCTIONS_AUTH_METHOD and OPENSANCTIONS_API_KEY, which is how the README's claim of lists "updated multiple times a day" is actually delivered: Marble calls an external list service rather than shipping lists in the image. Authentication uses AUTHENTICATION_JWT_SIGNING_KEY, and Firebase variables appear alongside it. There is also an offloading job with its own interval, batch size, write rate and retention cut-off, which suggests the team expects tables to grow and wants a way to move old rows out.

The practical consequence is that Marble is not a single binary you drop on a laptop. It is a small distributed system, and the Compose file is the map of it.

Installing Marble with Docker Compose

The README lists the prerequisites as Docker and Docker Compose, Git, 4GB RAM minimum and 10GB disk space. The quick start assumes you are in the repository root. The commands below are copied from the README's basic installation block, with the clone URL left as the placeholder the README itself uses.

# 1. Clone the repository
git clone <repository-url>
cd marble

# 2. Copy example environment file
cp .env.dev.example .env.dev

# 3. Start Marble
docker compose -f docker-compose-dev.yaml --env-file .env.dev.example up

Note the mismatch worth knowing about before you run it: step two copies .env.dev.example to .env.dev, while step three passes .env.dev.example to the --env-file flag. The commands as printed work, but they do not use the file you just created. If you edit .env.dev and expect your edits to apply, point the flag at .env.dev instead.

Once the stack is up, the .env.example file gives the ports: HOST_API_PORT=8080 and HOST_APP_PORT=3000, with MARBLE_APP_URL set to http://localhost:3000 and MARBLE_API_URL set to http://api:8080, using the API container name as hostname inside the Compose network. So the first thing you open is http://localhost:3000.

The example file is also blunt about the signing key. AUTHENTICATION_JWT_SIGNING_KEY must be changed for production, and if it is left empty, "a key will be regenerated on every app restart, which may cause unexpected logouts." The suggested generation command is:

openssl genrsa -out /path/to/private/key.pem 4096

The same file recommends AUTHENTICATION_JWT_SIGNING_KEY_FILE over the inline variable, because multi-line PEM values are awkward in environment variables. The README points to the installation directory and to docs.checkmarble.com for the full deployment guide, which is where you should look for anything beyond the developer stack.

What the open source build does not tell you

The most consequential omission is the licence. The repository reports NOASSERTION, meaning GitHub could not match the LICENSE file to a known licence, and the README refers to "a free open source self-hosted option and a licensed option with Enterprise features." That is a two-tier model, but the README does not say which features sit behind the licensed tier. The Compose file passes LICENSE_KEY to the backend, so the mechanism exists, and features such as SSO with Open ID Connect, IP whitelisting and SOC 2 Type II certification are grouped under the enterprise governance heading. Whether transaction monitoring or screening is gated is not stated. Anyone evaluating Marble for a regulated production deployment has to read the LICENSE file and the enterprise documentation directly rather than infer from the repository.

The second limitation is the dependency on external list data. Screening quality is only as good as OPENSANCTIONS_API_HOST and the key you supply. A self-hosted deployment keeps your customer and transaction data on your own infrastructure, but the screening calls still leave it unless you host that service yourself. The README's privacy claim is about your data, not about every outbound request.

Third, the quick start is a developer stack, not a production topology. The .env.example warns that variables set there are not all automatically passed to containers, and that new variables must be referenced in the Compose file for the relevant container. Backups, Postgres tuning, TLS termination and the offloading job's retention window are all left to the operator.

Marble compared with buying a monitoring suite

The real alternative here is not another open source project. It is a commercial transaction monitoring and screening suite, which is exactly the comparison the README invites. The difference is where the logic lives. In a bought suite, detection rules, thresholds and case workflows are configured inside the vendor's application, and the underlying data model is the vendor's. In Marble, the README describes transaction monitoring as "based on a custom data model that mirrors your data warehouse", which means the schema follows yours rather than the other way round, and the detection program is something you can inspect and change.

That cuts both ways. A bought suite arrives with onboarding, tuning advice, list curation and a support contract. Marble arrives with a Slack community, weekly updates, and a documentation site. The README states that direct support is for licensed users, so the free self-hosted path is community support. If your team has no one who can operate Postgres, Redis, object storage and a container platform, the operational cost of the open source route can exceed the licence fee of the commercial one. Conversely, if your compliance team has been asking why an alert fired and the vendor cannot answer, the transparency argument in the README's customer quote is the whole point.

Maintenance, releases and upgrade cost

The release cadence is visible in the repository: v1.7.0 on 2026-08-10, v1.8.0 on 2026-08-24 and v1.9.0 on 2026-09-07. The last push to the default branch was on 2026-09-07, and the repository is not archived. That is a fortnightly rhythm across the three releases shown, with release notes naming specific work such as case SLAs and large file ingestion in v1.8.0, and an improved case manager and risk assessment details in v1.7.0. The README also claims weekly updates.

Upgrading means moving the two pinned image tags in docker-compose.yaml, and the version tags in the file are literal, so an upgrade is a deliberate edit rather than a floating tag. The variables in .env.example carry no version numbers, which limits the configuration churn you would expect between releases, but the example file's own warning applies: if a new release adds a variable, you must add it to the Compose file for the container that needs it, not just to your environment file. Run the database migrations that ship with the backend before switching the frontend tag, and keep the JWT signing key stable across restarts unless you want users logged out.

A first real use: from transaction data to a case

The README does not walk through a first rule, so the honest sequence is the one implied by the product structure. Bring your transaction and customer data into Marble through the ingestion path, which is backed by INGESTION_BUCKET_URL, and model it so the fields match your warehouse. Then define detection rules against that model, real time or post trade. Rules produce alerts, alerts become cases in the case manager, and the audit trail records the actions taken. Screening runs in parallel, against the lists configured through the OpenSanctions connection, either in real time or on a schedule, and continuous monitoring rechecks existing customers as lists change.

For a first evaluation, the README's own advice is to go through the interactive demo and read the documentation at docs.checkmarble.com before touching the deployment, and to use the public API reference if you plan to push decisions into another system. That is the right order. Standing up the Compose stack is quick; deciding which of your existing rules to port, and how your data model should look, is the part that determines whether the deployment is useful. The README's customer quote makes the same point from the other direction: the value is that you can see what is going on and troubleshoot the detection program yourself.

Editorial conclusion

Marble fits teams that already have transaction data in a warehouse or core banking system and want detection logic they can read, edit and audit, plus a case manager where analysts work the resulting alerts. It does not fit teams looking for a KYC provider: the README states plainly that Marble does not provide KYC services. Before adopting it, read the LICENSE file yourself, since the repository reports NOASSERTION rather than a named licence, and confirm which features require LICENSE_KEY in docker-compose.yaml and which ship in the open source build.

Frequently asked questions

Official sources

1. checkmarble/marble on GitHub
2. Issues
3. Project website
4. README
5. Releases