Read me first

If you have just been handed SynthGen and you are wondering what it is, start here. No technical background assumed.

---

1. Who this is for

People who need realistic data to work with, and are not allowed to use the real thing.

Typically that means someone in a hospital trust, a bank, an insurer or a government department, working on:

• testing — a system needs to be tried out with data that behaves like the real data, but the real data cannot leave the live environment;
• building models — a forecasting or scoring model needs records to learn from, and the records in question belong to actual people;
• sharing — a supplier, a partner or a research team has asked for a sample, and nobody is comfortable sending it.

You do not have to be a privacy specialist. Most people who use this are not. That is rather the point: it is built for someone who has been asked to make a privacy decision they were never trained to make and cannot put off.

There is a second reader who never touches the software at all — the auditor or regulator who reads the paperwork months later. A great deal of what SynthGen does is for them.

2. What it does

In one sentence: it makes convincing fake data, works out how risky that fake data is, and refuses to hand it over if the answer is "too risky" or "we could not tell".

Slightly longer:

1. You show it some real data.
2. It studies the shape of that data — the ranges, the proportions, how the columns relate to each other — and points out anything that looks like personal information.
3. It produces brand-new records that behave like the originals but describe nobody.
4. It measures how likely it is that someone could still be picked out of the result, and explains how it arrived at that number.
5. If the risk is above the limit your organisation set, it will not release the data.
6. It writes all of this down in a document you can hand to an auditor.

Step 5 is the unusual one. Most tools stop at step 3.

3. The domain: why this is harder than it sounds

Almost everyone's first assumption is that made-up data must be anonymous. It is not, and this is the single most expensive misunderstanding in the field.

Picture a made-up record: a 61-year-old female cardiologist in a small county town. Nobody's file was copied. But if there is exactly one such person, that record points at her as surely as her name would.

The danger is rarely a name or an account number — those are easy to remove. It is the combination of ordinary details. Age, postcode, job title, admission date: each harmless alone, and together often unique to one individual. Specialists call these quasi-identifiers.

Regulators are clear about this. Under the UK and EU data protection rules, data is only anonymous if a person cannot be picked out by any means reasonably likely to be used. In December 2024 the European Data Protection Board said explicitly that synthetic data is encouraged but is not automatically anonymous. In US healthcare, the equivalent route requires a qualified expert to certify that the risk is very small.

So the real question is never "did I make synthetic data?" It is:

Could I defend having released this, to someone reading my justification a year from now who cannot ask me what I meant?

That question is what SynthGen is built around.

4. Where it fits

It sits beside your real systems, not inside them. You install it on your own infrastructure. Your data does not go to anybody else — there is no cloud service in the middle, and nothing is sent anywhere for processing.

Who uses it. Usually a small number of people: engineers and analysts who generate data day to day, and one or two senior people who set the rules about what may be released and who approve the exceptions.

What it connects to.

• Files — spreadsheets and exported tables you upload.
• Databases — it can read directly from a company database, taking a sample rather than copying everything. Its login details are stored encrypted and cannot be read back out afterwards, by anyone.
• Automated pipelines — your build or data pipeline can drive the whole thing without a person present, using its own credential.

How people work with it. There are no screens to click. You use it by typing commands, or your systems talk to it directly. The two things designed to be read are what appears in the terminal and the compliance documents it produces. That is a deliberate choice, not an omission — this is a tool for people who already work this way.

5. First run

The first thing to do is set the release limit, before anyone generates anything.

The release limit is the maximum risk you are willing to accept in released data. It matters that it is chosen in advance. A limit picked after seeing an inconvenient number is not a limit.

synthgen config set --release-threshold 0.09 --retention-days 30

The very first person to authenticate automatically becomes an Operator — the senior role that can set rules and approve exceptions. That is you, and after that, promotions have to be granted by an existing Operator.

Then check your own footing:

synthgen auth status
synthgen config show

If you want to look around before committing to anything, use the preview package instead — it comes with example data already loaded. See demo-data.md.

6. Setting up

Point it at some data. Either upload a file:

synthgen source register customers
synthgen source upload customers customers.csv

or connect it to a database, where it will discover related tables on its own.

Let it look, then check what it proposes:

synthgen source profile customers

It reports what it found in each column and suggests what to do about it. Three kinds of answer:

• this looks like personal information — with a suggested treatment;
• I do not recognise this — so it will be treated cautiously anyway;
• this is fine as it is — left alone.

That middle answer is worth pausing on. "I do not recognise this" is not the same claim as "this is safe", and the tool never quietly converts one into the other.

Nothing is applied until you say so. These are proposals. Review them, change any you disagree with, and only then generate.

7. Day to day

The routine is four commands.

Generate:

synthgen run start --source customers --rows 50000

Read the verdict — this is the screen the whole product exists for:

synthgen assessment show <run-id>

You get a number: roughly, the chance that a record could be traced to a real person. And, unusually, you get how that number was worked out, in words.

Take the data:

synthgen dataset export <dataset-id> --format csv

When it says no, it tells you why and what would change the answer:

Export refused — risk above the release threshold.

  Estimated re-identification probability   0.1240
  Release threshold                         0.0900

  What would change this:
    - generalise `age` to 5-year bands
    - request fewer rows than the source contains
    - record an Operator override with a written justification

Usually the first suggestion is the right one. Rounding an age to a five-year band or a postcode to its first half often drops the risk sharply while barely affecting how useful the data is.

If you genuinely must release it anyway, an Operator can override — but must write down why, and that explanation then appears on every compliance document for that dataset, permanently. An automated pipeline cannot override at all. That is deliberate: an exception a script could grant would soon be a script that always grants it.

Get the paperwork:

synthgen report generate <run-id> gdpr_recital_26

A readable document you can hand to an auditor, where every figure can be traced back to something actually measured.

8. Ongoing care

Data is deleted on a schedule; the record is not. Generated datasets expire after your retention period and their files are removed. Everything about them — what was done, what was measured, who approved it — is kept indefinitely. For most kinds of run, an expired dataset can be rebuilt from that record, identical to the original.

Rotate the pipeline credentials. Credentials issued to automated systems expire. Issue the replacement before the old one lapses.

Look at the audit trail occasionally.

synthgen audit list

Refusals are recorded as well as successes — often the more interesting half.

Two keys must never be lost. One determines how identifiers are disguised; change it and previously produced data can no longer be matched up. The other protects stored database passwords; lose it and they are gone for good. Back both up when the system is installed, not later.

Revisit the release limit periodically. It encodes your organisation's appetite for risk, and that changes.

---

A short glossary

Term	What it means here
Synthetic data	Made-up records that behave statistically like real ones
Quasi-identifier	An ordinary detail — age, postcode, job title — that identifies nobody alone but can identify someone in combination
Re-identification	Working out which real person a record refers to
Assessment	SynthGen's measured verdict on how identifiable a dataset is
Release threshold	The maximum risk your organisation accepts. Set in advance
Treatment	What happens to a column: kept, disguised, blurred, removed, or replaced
Run	One act of generating a dataset, with everything about it recorded
Override	A senior person's decision to release above the limit, with a written reason
Differential privacy	A stronger, mathematical guarantee, available for the most sensitive work
Fidelity	How closely the fake data resembles the real thing
Operator / Analyst	The two roles. Analysts generate and export; Operators also set rules and approve exceptions

The other documents here

Document	Read it when
getting-started.md	You want your first dataset, step by step
privacy-model.md	You want to understand the risk number and its limits
demo-data.md	You want example data to explore before using your own
production-initialisation.md	You are setting up a live system for the first time
api.md	You are connecting another system to it
testing.md	You want to know how it was tested, and what the tests do not tell you

There is also a collateral/ folder with longer background reading, including white papers on why synthetic data is not automatically anonymous and how the risk is measured.

Who can do what

	Analyst	Operator
Generate, assess, export	yes	yes
Set the release limit and retention	no	yes
Approve an over-limit release	no	yes
Manage people and pipeline credentials	no	yes

An automated pipeline always has Analyst permissions, whoever set it up. It can never approve an exception.

The example data

The preview package arrives with four example datasets already loaded: a patient cohort, an insurance book, a stream of transactions, and a small register of medical specialists.

One of them is deliberately designed to be refused. That is not a fault — it is the most useful thing to see, because it shows the product doing the job it exists for.

To clear the examples and start with your own data, see demo-data.md.

Common questions

Is the data it produces anonymous? Not automatically, and SynthGen will not tell you it is. It measures the risk and helps you argue about it. The assessment supports the claim; the word "synthetic" does not.

Can I trust the risk number? It is a floor, not a ceiling. It assumes someone who knows what is in your dataset. It cannot account for someone who also holds a different dataset about the same people. Real risk is therefore at least the number shown.

Is a compliance report a certificate? No. It is evidence that helps a qualified person make and record a decision. Nothing this software produces certifies anything.

Why did it refuse when I was in a hurry? Because that is exactly when the check matters. The limit is adjustable — by an Operator, deliberately, in advance. What cannot be switched off is refusing when the assessment is incomplete.

Why is there nothing to click? There is no web interface by design. It is used from a command line or by other systems, and the things meant to be read are the terminal output and the compliance documents.

Can I get an old dataset back after it expired? Usually yes — it can be rebuilt from its record, identical to the original. The exception is data generated with the strongest privacy guarantee, which by its nature cannot be reproduced. privacy-model.md explains why.

Does my data go anywhere? No. It runs on your own infrastructure. There is one optional feature that can send a description of your columns — their names and types, never any values — to a language model to help draft a specification. It is switched off unless you turn it on.

Where to get help

This project is part of the worlds-biggest-software-project initiative. For questions, ideas, or to find people who can adapt it to your organisation, visit wbsp.ai.

It is worth looking around while you are there. Community members have built many versions of this and other applications, and one may be closer to what you need than you would expect.