License configuration

Configure your StoatFlow license key for local development and CI/CD — environment variables, system properties, key files, and application.yaml.

StoatFlow checks that a license key is present at startup (a missing key still fails fast), then runs the activating validation ~5 minutes after start on a background thread — and keeps the license current on a periodic heartbeat. Until that first validation the license reports PENDING; the app serves traffic normally, and on a validation failure it shuts down gracefully. You give it two things: your license key and — for production and trial deployments — an environment label. This page covers every way to provide them, for local development and CI/CD, and how your license counts instances.

Get a license key

  • Free trial: request one at stoatflow.io/contact. A trial license covers its granted number of instances for 30 days and can run in staging or production.
  • Commercial license: contact sales@stoatflow.io.

Your key arrives in your onboarding email.

The license key

Your key is the signed string from your onboarding email — it starts with key/. The runtime resolves it by looking for an explicit key first, then a key file — and within each, an environment variable beats a system property (which is what an application.yaml value becomes):

  1. An explicit key — STOATFLOW_LICENSE_KEY (environment variable), else the stoatflow.license.key system property (which application.yaml's stoatflow.license.key feeds).
  2. A key file — STOATFLOW_LICENSE_FILE (environment variable), else the stoatflow.license.file system property (fed by application.yaml's stoatflow.license.file), else the default ~/.stoatflow/license.key.

So an explicit key always wins over a key 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.

Pick whichever fits — by source:

# Highest precedence. Good for containers, CI, and one-off local runs.
export STOATFLOW_LICENSE_KEY="key/...your key from the onboarding email..."

The environment label

The environment is a label for the deployment an instance belongs to — e.g. prod, prod-eu-west, staging, dev. StoatFlow derives the instance's fingerprint from it:

fingerprint = SHA-256(application-id || environment)

So the same application-id + the same environment is one instance; distinct environments are distinct instances. Set it with STOATFLOW_LICENSE_ENVIRONMENT, the stoatflow.license.environment system property, or stoatflow.license.environment in application.yaml.

  • Local development (Developer tier): if you don't set it, the environment defaults to <your-username>-<hostname> — one instance per developer machine, no configuration needed.
  • Production and Trial: both tiers require an explicit environment — the engine refuses to run if it has to auto-generate one (the check fires at the deferred validation, ~5 minutes after start). In Kubernetes the auto-generated hostname is the pod name, so every redeploy would count as a new instance. Set it per deployment (prod, prod-eu-west, staging, …).

Local development

The simplest local setup is the key file — write it once and every StoatFlow app you run locally is licensed, with no env vars and an auto-derived per-machine environment:

mkdir -p ~/.stoatflow
printf '%s' 'key/...your developer key...' > ~/.stoatflow/license.key
chmod 600 ~/.stoatflow/license.key

Prefer per-run configuration? Export the key (and optionally the environment) in your shell:

export STOATFLOW_LICENSE_KEY="key/...your developer key..."
# Optional — defaults to <username>-<hostname> if unset:
export STOATFLOW_LICENSE_ENVIRONMENT="dev-$(whoami)"

CI/CD

Use your CI/CD-tier key (it carries a higher machine cap suited to short-lived build agents). Store it as an encrypted secret — never in the repo.

On GitHub Actions, StoatFlow auto-detects the run and sets the environment to cicd-<run id> for you, so each run is its own short-lived instance — you only need to provide the key:

# .github/workflows/your-workflow.yml
jobs:
  integration-test:
    runs-on: ubuntu-latest
    env:
      STOATFLOW_LICENSE_KEY: ${{ secrets.STOATFLOW_CI_LICENSE }}
      # Optional — auto-derived as cicd-${GITHUB_RUN_ID} on GitHub Actions:
      # STOATFLOW_LICENSE_ENVIRONMENT: cicd-${{ github.run_id }}
    steps:
      - uses: actions/checkout@v4
      # ... build + run StoatFlow tests ...

On other CI systems (GitLab CI, Jenkins, …) there's no auto-detection — set the environment explicitly to something unique-per-run so concurrent builds don't share one instance:

export STOATFLOW_LICENSE_KEY="$STOATFLOW_CI_LICENSE"
export STOATFLOW_LICENSE_ENVIRONMENT="cicd-${CI_PIPELINE_ID:-$(date +%s)}"

Deferred validation & CI/testcontainers

The activating license validation — the call that registers a machine against your license — runs ~5 minutes after start(), not at startup. Startup only checks the key is present (offline, no network). The consequence for tests:

  • A test instance (testcontainers, integration tests, CI jobs) that starts and stops within ~5 minutes makes zero license-server API calls and consumes zero machine activations — the usual start-app-per-test-class pattern is free, no matter how often CI runs.
  • During that window the license status reports PENDING: readiness is UP, the app processes normally, and the stoatflow.license.valid gauge reads 0 until validation succeeds (see Metrics).
  • An instance that outlives the window validates and consumes one activation for its fingerprint. Long-running soak/perf tests therefore each count as an instance — the CI/CD tier's higher machine cap covers this; instances from ended runs free their slot automatically (below).

Instance limit

Your license covers a number of concurrent instances:

  • An instance is one application.id + environment. Replicas of it and an HA active/standby pair share that fingerprint, so they count once.
  • A running instance stays counted through a periodic heartbeat. An instance that stops frees its slot automatically within about its license's heartbeat window (an hour for Trial and Developer, a few hours for Production) — no deactivation step.
  • Renaming an environment registers a new instance; the old one counts until its slot is freed.
  • /license reports machinesUsed — the instances registered against your license, which can briefly include instances that have just stopped — and machinesAllowed, the instances your license covers.

When every instance your license covers is in use, a new instance is refused at its activating validation (~5 minutes after start) and shuts down gracefully, with a message saying so. An instance that is already running is never stopped because of the limit: if it loses its registration (for example after a long network outage) and cannot register again because the license is full, it keeps processing, reports INVALID with reason: instance_limit on /license and readiness, retries on every heartbeat, and recovers on its own once a slot frees. To raise the limit, contact sales@stoatflow.io.

Expiry and renewal

  • Trial: 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. An extended trial keeps running to its new date with the same key — nothing to redeploy.
  • Renewal: a renewed license keeps working with the same key; the engine picks up the new expiry at its next online validation. A paid license that expires keeps running until its next restart; the restart is then refused.

All license settings

Every setting, with its environment variable, system property, and application.yaml key (under stoatflow.license). Environment variable wins over system property wins over YAML.

application.yaml (stoatflow.license.*)Environment variableSystem propertyDefaultPurpose
keySTOATFLOW_LICENSE_KEYstoatflow.license.key—The signed license key (key/…).
fileSTOATFLOW_LICENSE_FILEstoatflow.license.file~/.stoatflow/license.keyPath to a file containing the key.
environmentSTOATFLOW_LICENSE_ENVIRONMENTstoatflow.license.environment<username>-<hostname> (auto)Instance label; required for Production and Trial.
cache-dirSTOATFLOW_LICENSE_CACHE_DIRstoatflow.license.cache-dir~/.stoatflow/license-cache/Where the offline-grace cache is stored.
verbose-bannerSTOATFLOW_LICENSE_VERBOSE_BANNERstoatflow.license.verbose-bannerfalseLog a detailed license banner at startup.
Heartbeat cadence and offline-grace are set by your license tier, not by configuration. They govern how quickly a license change takes effect and how long the engine tolerates a Keygen outage — so they're tuned per tier rather than left to each deployment. If your environment needs a longer offline-grace window (intermittent connectivity, restricted egress), talk to us and we'll set it on your license.

Troubleshooting

  • Startup fails: license key missing. The presence check hard-fails fast at start(). Check the key is set (precedence above).
  • App shuts down ~5 minutes after start: license invalid / expired / revoked. The deferred validation rejected the key — the log carries [LICENSE] deferred validation failed (code=…). Check the key is current; renew via your onboarding contact.
  • license key file has insecure permissions. The key file must be owner-only — chmod 600 ~/.stoatflow/license.key.
  • Production or Trial refuses to run without an environment. Set STOATFLOW_LICENSE_ENVIRONMENT (or stoatflow.license.environment) explicitly — these tiers won't auto-generate one. The refusal fires at the deferred validation (~5 minutes after start), once the tier is known.
  • StoatFlow instance allowance exhausted. Every instance your license covers is in use. Stopped instances free their slot automatically within about the heartbeat window; check /license (machinesUsed vs machinesAllowed) and look for environments that were renamed or apps nobody stopped — see Instance limit.
  • Readiness DOWN with reason: instance_limit on a running instance. The instance lost its registration and the license is full. It keeps processing and recovers by itself once a slot frees; it would be refused at its next restart.
  • Warning: the license has more registered instances than it allows. Your license's limit was lowered below the instances registered against it. Every instance keeps running and stays ready; contact your StoatFlow administrator.
  • Brief Keygen outage. The runtime keeps serving from its offline cache for the grace window, measured from its last successful online validation, then fails on the next check. Normal restarts within the window are fine.
  • Lost your key or token? We re-issue rather than retrieve — reply to your onboarding email and we'll rotate it.

Next steps