Licence configuration
StoatFlow verifies its licence offline, at start: the licence is a small signed string, and the engine checks its signature with a public key it carries. There is no licence server and no egress needed to run — StoatFlow runs in air-gapped estates as it does anywhere else (a trial reports its usage once a day unless you turn that off; no other licence sends anything). Each running instance registers itself in a small topic in your own Kafka cluster, so every instance knows how many services run under the licence, and a start that would exceed it is refused. You give each deployment two or three things: your licence, an environment label, and — unless it runs in production — its environment class.
Get a licence
- Free trial: start one at stoatflow.io/trial, self-serve; the licence and your Maven repository credentials arrive by email. A trial covers up to 10 production services for 30 days; every other environment class is free.
- Commercial licence: contact sales@stoatflow.io.
Your licence arrives in your onboarding email: a single line that starts with sfl1..
The licence
The runtime looks for an explicit key first, then a file — and within each, an environment variable beats a system property (which is what an application.yaml value becomes):
- An explicit licence —
STOATFLOW_LICENCE_KEY(environment variable), else thestoatflow.licence.keysystem property (whichapplication.yaml'sstoatflow.licence.keyfeeds). - A licence file —
STOATFLOW_LICENCE_FILE(environment variable), else thestoatflow.licence.filesystem property (fed byapplication.yaml'sstoatflow.licence.file), else the default~/.stoatflow/licence.key.
So an explicit licence always wins over a file, regardless of where each came from.
application.yaml values are applied below environment variables and -D system properties — so an env var always wins over YAML. This lets you commit a YAML default and override it per environment without touching the file.# Highest precedence. Good for containers, CI, and one-off local runs.
export STOATFLOW_LICENCE_KEY="sfl1....your licence from the onboarding email..."
# Set once, every local app picks it up — no env var needed.
# Must be owner-only (chmod 600) on Linux/macOS, or startup is refused.
mkdir -p ~/.stoatflow
printf '%s' 'sfl1....your licence...' > ~/.stoatflow/licence.key
chmod 600 ~/.stoatflow/licence.key
# Runtime module only. Interpolate from an env var so the licence
# never lands in source control.
stoatflow:
licence:
key: ${STOATFLOW_LICENCE_KEY}
The licence is readable: its payload is plain JSON (licensee, tier, allowances, expiry) under a signature, so changing any of it makes the signature fail. Every start logs who it is licensed to — the licensee's name, the tier and the expiry.
What each deployment declares
Environment label
The environment is a label for the environment a deployment runs in — prd-eu, prd-us, stg, dev. With the application.id it forms the deployment's fingerprint, SHA-256(application-id || environment), so the same application in two environments is two deployments. Set it with STOATFLOW_LICENCE_ENVIRONMENT, the stoatflow.licence.environment system property, or stoatflow.licence.environment in application.yaml.
- Production, enterprise and trial licences require an explicit environment in every class they count — the start is refused if it would have to auto-generate one there. In Kubernetes the auto-generated name is the pod name, which changes on every redeploy.
- A class the licence does not list is free and counts nothing, so it needs no label: a CI run on class
otherkeeps the auto-generatedcicd-<run id>— unless your licence listsotheror*, which counts it. - Developer and internal licences default it to
<username>-<hostname>, orcicd-<run id>on GitHub Actions.
Environment class
Every deployment declares the class of its environment — one of four:
| Class | For |
|---|---|
production | production — the default when nothing is set |
staging | pre-production, often production-like |
development | development environments |
other | everything else: test, previews, CI, DR drills |
Set it with STOATFLOW_LICENCE_ENVIRONMENT_CLASS, the stoatflow.licence.environment-class system property, or stoatflow.licence.environment-class in application.yaml. Any other value is refused at start.
Your licence lists an allowance per class it prices. The standard shape prices only production: staging, development and other are then free and unlimited. A developer licence covers every class except production, and refuses a production-class start. Declaring the class truthfully is part of your licence agreement.
Service
A deployment counts as the service named by its application.id, unless you set STOATFLOW_LICENCE_SERVICE (or stoatflow.licence.service): that merges two application ids that are one service in one environment, such as a blue/green pair or an application being renamed. Application ids that carry their environment (orders-prd) need nothing set, because the environment label already separates them.
The merge is bounded: a service counts once for up to two live application ids; a third counts as a second service, and so on. Nothing is refused for merging — the extra application ids are simply counted, and /licence lists the application ids of every service.
How the licence counts
Every running instance registers in the licence registry, a small compacted topic in the Kafka cluster it already uses, and heartbeats every 30 seconds. Every instance reads it, so each one knows what runs under the licence:
- A production service is a distinct (service, environment) pair with at least one live instance in an environment of class
production. A service in two production environments (prd-eu,prd-us) is two production services; its replicas count once. - Other classes are counted the same way and shown, but they are free and unlimited unless your licence lists them.
- HA standbys: whether a hot-standby replica counts is a term of your licence — all free (the default), every standby counted, or the first n per service free.
/licenceshows the standbys running and counted. - Liveness is judged by your brokers' clock: an instance whose last heartbeat is more than 90 seconds old by the brokers' clock no longer counts, so a pod that crashed leaves the count within 90 seconds, and one that stops gracefully leaves it at once.
At start, an instance counts its environment class with itself in it. If that is within the licence, it registers and runs; if not, the start is refused:
StoatFlow licence for ACME Corp allows 25 production services, and 25 are running. Stop a production service,
declare this deployment's environment class if it is not production, or contact sales@stoatflow.io to raise the
licence.
On Kubernetes, that deployment's pods crash-loop on this message; the running fleet is unaffected. A restart, a rolling update or a replacement pod of a service that is already registered is never refused, so the cap never takes down what already runs — even while the class is over its cap. A service is registered while one of its instances runs, and for 7 days after it was last seen: a graceful restart, a Recreate rollout, a StatefulSet roll or a pod that crash-loops for a while all start again. A service not seen for 7 days starts as a new one. HA standbys that your licence counts come back the same way, up to as many as the service ran in those 7 days: a counted standby's restart starts even over the cap, while a standby beyond that is refused like a new service. Two services that start at the same moment for the last slot both run: each logs a warning about the overage, /licence shows it, and nothing stops.
The cap is the licensed count. A licence can carry a published burst for rollout slack (a burst of 10 % lets a 25-service licence run 28); the default is none.
The licence registry topics
StoatFlow creates two topics in each Kafka cluster it runs against, shared by every StoatFlow application on that cluster:
| Topic | Holds | Read |
|---|---|---|
__stoatflow_licence | the live instances, the services seen during the licence term, licences applied to the cluster | at every start, then tailed |
__stoatflow_licence_history | daily and hourly usage history, kept 400 days | by usage reports only, never at start |
ACLs. The application needs DESCRIBE, READ and WRITE on both topics, and CREATE if StoatFlow is to create them; DESCRIBE_CONFIGS lets the start check the timestamp type — without it, StoatFlow reads the type from the records on the topic, and on an empty topic uses the CreateTime fallback below until the first record shows it. The registry's clients authenticate like the application's own: the producer with producer.*, the admin client with admin.*, the consumer with restore.consumer.* (each falling back to consumer.*).
Pre-creating them on a cluster that denies topic creation — exactly these settings, then restart (the error at start prints them too):
kafka-topics.sh --create --topic __stoatflow_licence --partitions 1 --replication-factor 3 \
--config cleanup.policy=compact --config retention.ms=-1 \
--config message.timestamp.type=LogAppendTime --config min.insync.replicas=2 \
--config segment.ms=300000 --config min.compaction.lag.ms=0 \
--config max.compaction.lag.ms=300000 --config min.cleanable.dirty.ratio=0.1
message.timestamp.type=LogAppendTime matters: liveness and expiry follow your brokers' clock, so rolling back a host's clock does not extend a licence. On a topic created with CreateTime, StoatFlow falls back to each host's own clock, waits 90 seconds at a start that finds other instances' records before it counts, logs a warning every hour, and reports stoatflow.licence.registry.broker.clock = 0.
A separate registry per tenant. On a shared cluster, stoatflow.licence.registry.topic names a different registry topic (the history topic follows as <topic>_history), so one team's licence and instances stay apart from another's.
Applying a licence to the cluster. stoatflow-licence-tool apply verifies a licence offline and writes it to the registry topic:
java -jar stoatflow-licence-tool-all.jar apply licence.sfl1 --bootstrap-server kafka:9092 \
--command-config client.properties
Every running instance of the same licence id — and every instance that starts later — uses the applied licence once it is valid (from its validFrom) when its sequence number is higher than its own: renewals, band changes and trial extensions arrive this way, with no redeploy and no restart. A lower sequence number is ignored (no rollback), and the tool refuses one.
Adopting the applied licence (opt-in). With stoatflow.licence.source: registry, an application that configures no licence of its own adopts the one licence applied to the registry topic. Without that setting an application never picks up a licence someone else applied — on a shared cluster, an unlicensed team's application would otherwise consume another team's allowance.
When the registry is unavailable — a missing ACL, an unreachable cluster at start, a topic deleted under a running application:
- Paid licences keep running. The licence is still verified and its expiry enforced, but the service count is not: the status is
UNVERIFIED, readiness stays UP,stoatflow.licence.registry.availablereads 0, a warning is logged every hour, and the instance retries in the background, counting again as soon as the topic is back. - A trial refuses to start without the registry. A trial that loses it while running keeps running until its expiry.
Bound to Kafka clusters. A licence can name the Kafka cluster ids it may run on; an instance on any other cluster refuses to start. /licence shows the cluster id.
Usage history and reports
Each deployment records its usage in the history topic — one of its instances writes it, every instance while the licence registry is unavailable — __stoatflow_licence_history (kept 400 days by your brokers, never read at start): which services ran each UTC day, and the peak count of its environment class in each hour. From it, the usage report — a JSON document you produce and can read every byte of before sending it — states what a licence used on one Kafka cluster over a period:
java -jar stoatflow-licence-tool-all.jar report --bootstrap-server kafka:9092 \
--licence lic_7Q2… --from 2026-10-01 --to 2027-09-30 > usage-2027.json
A running application serves the same report at GET /licence/usage?from=2026-10-01&to=2026-10-31.
- Per environment class: the peak concurrent count, the distinct services, and for the classes your licence prices the 95th-percentile and average daily peak, the days over the licensed count and the standbys running and counted; also per environment, per day and per engine version.
- Application ids and services appear only as hashes, unless you add
--include-app-names(include-app-names=true). Environment labels and classes appear in clear: the class declaration is what the report attests. - How far to trust it:
registry.brokerClock(whether the history topic carries your brokers' clock),unverifiedHours(hours an instance ran without the registry) andhistoryGapHours(hours the history could not be written). - Many clusters:
java -jar stoatflow-licence-tool-all.jar fleet-report report-a.json report-b.json …merges one licence's per-cluster reports of the same period — each class's daily total is the sum of each cluster's daily peak — and lists the clusters.
If the history topic cannot be written, the instance runs as before; the history has a gap, and stoatflow.licence.history.available reads 0 on every instance of the deployment (one instance writes its history and the others report its state). historyGapHours counts the hours an instance ran without writing its history only up to the last hour it wrote: an instance that stops while the history is still unwritable leaves its last hours out, so alert on the gauge.
Usage reporting
Usage reporting sends the usage report to StoatFlow automatically, so nobody has to run the tool by hand.
- Off by default, except for trials.
stoatflow.licence.reporting.enabled(envSTOATFLOW_LICENCE_REPORTING_ENABLED) turns it on or off —trueorfalse; unset (or any other value, which logs a warning), a trial reports and every other licence does not. A licence agreement may ask for reporting: such a licence logs a warning once a day while it is off — and nothing stops. - What is sent: once a day, the previous UTC day's usage report — exactly what
GET /licence/usageshows for that day, application ids and services hashed — together with the licence it is for. A trial also sends oneactivatedevent when it first runs on a cluster (its environment class and the engine version). - When and from where: after 02:00 UTC — by the clock that stamps the usage history, the Kafka brokers' — plus a delay of up to an hour, fixed per instance, from one instance per cluster and licence: of the instances that report, the one with the lowest live fingerprint — so a deployment that turns reporting on sends even when another deployment of the licence has it off. The report covers every deployment of the licence on that cluster. A licence used on two registry topics of one cluster reports once per topic. Nothing is sent while the instance cannot read the Kafka cluster id. Each send logs one INFO line with the report's summary.
- Where:
POST https://licensing.stoatflow.io/v1/usage— allow egress to that host where reporting is on. - If it fails — a firewall, an outage, a history topic it cannot read — the instance logs a warning, counts it in
stoatflow.licence.reporting.sent.total{result="failed"}, and tries again the next day, catching up the days it missed (up to 7); a trial's activation likewise, once a day. It never affects the licence status, readiness or processing. - Air-gapped estates produce the report with
stoatflow-licence-tool reportand upload it at licensing.stoatflow.io, from any machine that can reach it. To send it without the page,POSTit wrapped with its licence:{"kind": "report", "licence": "sfl1…", "report": <the report>}("kind": "fleet-report"for a fleet report) tohttps://licensing.stoatflow.io/v1/usage; a report covers at most 400 days.
/licence shows reporting — whether it is on, whether the licence asks for it, the last day sent and the last result.
Local development
Use your developer licence and declare the class — the simplest setup is the licence file plus one variable:
mkdir -p ~/.stoatflow
printf '%s' 'sfl1....your developer licence...' > ~/.stoatflow/licence.key
chmod 600 ~/.stoatflow/licence.key
export STOATFLOW_LICENCE_ENVIRONMENT_CLASS=development
CI/CD
A CI run verifies its licence like any other start, and nothing reaches a licence server. Declare the class other and store the licence as an encrypted secret — any of your licences covers it (an unlisted class is free on a production licence, and a developer licence covers every non-production class). No environment label is needed while your licence does not list other or * (the standard shape lists only production): a class it does not list counts nothing, so the auto-generated cicd-<run id> is fine. If it lists either, other is counted and needs a stable label — set STOATFLOW_LICENCE_ENVIRONMENT (e.g. ci):
# .github/workflows/your-workflow.yml
jobs:
integration-test:
runs-on: ubuntu-latest
env:
STOATFLOW_LICENCE_KEY: ${{ secrets.STOATFLOW_LICENCE }}
STOATFLOW_LICENCE_ENVIRONMENT_CLASS: other
# STOATFLOW_LICENCE_ENVIRONMENT: ci # only when your licence lists `other` or `*`
steps:
- uses: actions/checkout@v4
# ... build + run StoatFlow tests ...
Expiry and renewal
- Paid licences (developer, production, enterprise): from 30 days before expiry the log carries a daily warning and the
stoatflow.licence.days.remaininggauge counts down; readiness is unaffected. A running instance is never stopped by expiry. For the 30 days after expiry, a service that ran during the licence term restarts — a pod rescheduled after a node drain, an eviction, an upgrade — with an error in its log, and a new service is refused: the fleet cannot grow on an expired licence. After those 30 days, no instance starts, so an expired fleet goes down at its next reschedule./licenceshowsrestartGraceEndsAtonce the licence has expired;stoatflow.licence.grace.remaining.secondscounts down to that same instant (expiry + 30 days) through the whole term, so an alert on it fires in time whatever the date. (If the registry is unavailable during those 30 days, a restart is allowed with an error, because whether the service ran during the term cannot be checked.) - Trials: from five days before expiry the log names the trial's end date. At expiry the instance logs an error and stops one hour later; a restart after expiry is refused unless an extension was applied. Ask for an extension or a licence before then: an extension applied with
java -jar stoatflow-licence-tool-all.jar apply(the licence tool) cancels the stop, and an instance that restarts later starts on it. A Kafka cluster runs one trial: a trial licence that starts on a cluster after another trial there ended is refused (SERIAL_TRIAL); one that was already running when the other ended is not, and neither is an extension of the same trial. - Renewal: a renewal is a new licence string with the same licence id and a higher sequence number. Apply it with
java -jar stoatflow-licence-tool-all.jar apply: running instances switch to it once it is valid, which also ends a restart grace, and an instance that restarts later starts on it — also once the configured licence has expired, or on a Kafka cluster or environment class only the renewal covers. Or put it where the old one was configured; each instance picks it up when it restarts.
All licence settings
Every setting, with its environment variable, system property, and application.yaml key (under stoatflow.licence). Environment variable wins over system property wins over YAML.
application.yaml (stoatflow.licence.*) | Environment variable | System property | Default | Purpose |
|---|---|---|---|---|
key | STOATFLOW_LICENCE_KEY | stoatflow.licence.key | — | The licence (sfl1.…). |
file | STOATFLOW_LICENCE_FILE | stoatflow.licence.file | ~/.stoatflow/licence.key | Path to an owner-only (chmod 600) file holding the licence; a root-owned mount, such as a Kubernetes Secret with fsGroup, may also be group-readable. |
environment | STOATFLOW_LICENCE_ENVIRONMENT | stoatflow.licence.environment | <username>-<hostname> (auto) | Environment label; required for production, enterprise and trial licences in a class they count. |
environment-class | STOATFLOW_LICENCE_ENVIRONMENT_CLASS | stoatflow.licence.environment-class | production | production, staging, development or other. |
service | STOATFLOW_LICENCE_SERVICE | stoatflow.licence.service | the application.id | The service this deployment counts as. |
verbose-banner | STOATFLOW_LICENCE_VERBOSE_BANNER | stoatflow.licence.verbose-banner | false | Also log the licence's terms (allowances, standbys, cluster binding) at start. |
source | STOATFLOW_LICENCE_SOURCE | stoatflow.licence.source | configured | registry adopts the one licence applied to the registry topic when the application configures none. |
registry.topic | STOATFLOW_LICENCE_REGISTRY_TOPIC | stoatflow.licence.registry.topic | __stoatflow_licence | The registry topic; the history topic is <topic>_history. |
reporting.enabled | STOATFLOW_LICENCE_REPORTING_ENABLED | stoatflow.licence.reporting.enabled | on for a trial, else off | Send the previous day's usage report to StoatFlow once a day. |
Troubleshooting
Every refusal throws a LicenceValidationException from start(), before anything is built, with a code and a message that names the fix.
StoatFlow licence not found. No licence is configured; the message lists every place that was checked. Note the British spelling:STOATFLOW_LICENSE_KEYis not read.MALFORMED— "this is a Keygen licence key". A licence from before offline licensing (key/…). Ask for it to be re-issued as ansfl1licence.INVALID_SIGNATURE. The licence was altered, truncated when copied, or was not issued by StoatFlow. Copy it again from the onboarding email.UNKNOWN_KEY. The licence is signed with a key this StoatFlow version does not have — usually a licence newer than the engine. Upgrade StoatFlow.ENVIRONMENT_REQUIRED. SetSTOATFLOW_LICENCE_ENVIRONMENTto a stable label for the deployment.ENVIRONMENT_CLASS_UNKNOWN. The class must beproduction,staging,developmentorother.CLASS_NOT_LICENSED. Your licence refuses this deployment's class — typically a developer licence in a deployment that did not declare its class, so it counts asproduction. SetSTOATFLOW_LICENCE_ENVIRONMENT_CLASS.SERVICE_LIMIT. The licence's environment class is full. Stop a service of that class, check that deployments outside production declare their class, or contact sales to raise the licence./licenceon any running instance lists what counts.NEW_SERVICE_AFTER_EXPIRY. The licence has expired: services that ran during its term restart for 30 days, a new one does not start. Apply the renewed licence.EXPIRED,TRIAL_EXPIRED. The licence's term is over and so is any grace it has. Apply the renewed licence.REGISTRY_UNAVAILABLE. A trial cannot read the licence registry topic, or a licence was to be adopted from it and it cannot be read. Grant DESCRIBE, READ and WRITE on__stoatflow_licence(and CREATE).SERIAL_TRIAL. This Kafka cluster already ran a different StoatFlow trial, which has ended; the message says when. Ask sales for an extension of that trial, or for a licence.NO_REGISTRY_LICENCE.stoatflow.licence.source: registry, and the registry topic holds no licence, or more than one current licence (an expired one beside a current one is left out): configure the application's licence.INVALID_SETTING. A licence setting has a value it does not take —stoatflow.licence.sourceisconfiguredorregistry.CLUSTER_NOT_LICENSED. The licence is bound to other Kafka clusters; the message names this cluster's id.- Status
UNVERIFIED. The registry is unavailable — the topic cannot be ensured, read or written: the instance runs, but the licence's service count is not checked. Grant the ACLs above; counting resumes on its own once the topic can be read again from its start. licence file has insecure permissions. The file must be owner-only:chmod 600 ~/.stoatflow/licence.key. Only a root-owned file — a Kubernetes Secret mounted withfsGroup— may also be group-readable; no licence file may be writable by its group or readable by others.licence file is not readable. The user StoatFlow runs as cannot read it. For a file it owns,chmod 600; for a Kubernetes Secret mounted as a file, set the pod'ssecurityContext.fsGroupto the image's group anddefaultMode: 0440(see Running on Kubernetes).- Lost your licence? We re-issue rather than retrieve — reply to your onboarding email.
Next steps
- Health checks and the
/licenceendpoint — what the runtime reports about its licence. - The licence tool — apply, check and report on licences.
- Architecture — how the engine runs your topology.
- Questions about your licence? Get in touch.