Skip to main content

Licensing

This page describes how a Foundation4 license is bound to an installation, how operators read the system ID, apply and renew a license, and what the license limits. The page also describes how Foundation4 behaves when the license is invalid, expired or exceeded. Operators and administrators who install or run Foundation4 use this page.

The commands on this page read the production values file foundation4ai.values.yaml, created in Install on Kubernetes. An evaluation installation uses evaluation.values.yaml instead.

License binding​

Every Foundation4 installation requires a license, including an evaluation installation. The Foundation4 provider issues each license for one system ID. The system ID identifies one database schema on one PostgreSQL cluster.

For licenses of version 3, the current license version, Foundation4 computes the system ID from the PostgreSQL system identifier, the database name and the schema in database.schema. PostgreSQL assigns the system identifier when a database cluster is created with initdb, and physical copies of the cluster keep the identifier. The system ID is a string of 64 hexadecimal characters and does not depend on the Foundation4 tables, so the system ID exists before the database migration.

Foundation4 reads the system identifier with the PostgreSQL function pg_control_system(). Stock PostgreSQL lets every database user run the function; a managed database service that revokes this permission grants the permission to the Foundation4 user, as Database describes. Without the permission, the system ID cannot be computed.

Licenses of versions 1 and 2 keep the earlier system ID, computed from PostgreSQL catalog object identifiers (OIDs) of the schema in database.schema, the owner of that schema and the api_keys table.

EventSystem ID of version 3License
Pod restart, Helm upgrade, Foundation4 upgrade, application release reinstalled against the same databaseUnchangedRemains valid
PostgreSQL restart or minor version upgradeUnchangedRemains valid
Failover to a physical replica, physical restore with pg_basebackup, storage snapshot of the clusterUnchanged, because the copy keeps the system identifierRemains valid
Bundled PostgreSQL pod deleted or rescheduled (evaluation profile)Unchanged, because the volume claim keeps the databaseRemains valid
Logical restore with pg_dump and pg_restore into a database of the same name on the same clusterUnchanged; new for licenses of versions 1 and 2Remains valid for version 3
New database, including a new installationNewNew license required
Logical restore into another cluster or under another database nameNewNew license required
Major PostgreSQL version upgrade, which creates a new clusterNewNew license required
Move to a new managed database instanceNewNew license required
Database or database.schema renamedNewNew license required
Volume claim of the bundled PostgreSQL deleted (evaluation profile)New, because the database is recreated emptyNew license required
Schema assigned to a new owner, or api_keys table recreatedUnchanged; new for licenses of versions 1 and 2Remains valid for version 3

The following rules keep the system ID stable:

  • Database and schema names. The database name and database.schema do not change after the license is installed. The installation Jobs, the command-line tools, the API server and the workers compute the system ID from the same database.schema.
  • Schema ownership. For licenses of versions 1 and 2, the owner of the schema does not change after the license is installed.
  • Planned changes. Before a change that creates a new system ID, such as a major PostgreSQL version upgrade, the operator requests a license for the new system ID, so that the license is ready at the switch-over.

Database describes the database requirements, and Backup, restore and upgrades describes restores and major PostgreSQL version upgrades.

System ID retrieval​

The system ID is available from three sources:

  • License check Job log. The Job foundation4ai-api-server-license-check prints the system ID in the first line of the log, at every installation and upgrade of the application release. Helm deletes the Job after a successful check, so the log remains after a failed check, until the next install or upgrade. This source is the only one available during the first installation.
  • Command in a running pod. foundation4ai license system-id prints the system ID of the database and schema that the pod is configured for.
  • Startup warning. When the license does not match, the API server and the workers log a warning with the system ID before exiting.

Read the system ID from the log of a failed license check Job:

kubectl logs -n foundation4ai job/foundation4ai-api-server-license-check

Expected result: the first line holds the system ID, the second line holds the license status, and the last line repeats the status as an error.

SystemID: <system ID>
Checking for a valid license... Invalid
Error: "License check failed: Invalid"

When the database user cannot run pg_control_system(), the first line reads SystemID: unavailable (<reason>).

Read the system ID from a running API server pod:

kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \
./foundation4ai license system-id

Expected result: one line with 64 hexadecimal characters. A database user without access to pg_control_system() produces Error: "Failed generating system id: the database user cannot read pg_control_system()" instead.

Find the startup warning in the log of an API server that exited:

kubectl logs -n foundation4ai deploy/foundation4ai-api-server -c server --previous | \
grep "Failed to validate license for system id"

Expected result: a WARN line that ends with Failed to validate license for system id: <system ID>.

License contents​

foundation4ai license details prints the contents of a license after checking the license against the system ID of the database:

kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \
./foundation4ai license details '<license>'

Expected result for a license that matches the database, with each value in angle brackets replaced by the license contents:

License: <license holder> (expires on <date> <time> UTC)
System ID: <system ID>
Version: <license version>
Limits:
Pipelines: <limit>
Documents: <limit>

The output has the following parts:

  • Holder and expiry. The first line names the license holder and the expiry date and time in UTC, or (perpetual) for a license without an expiry date.
  • Optional lines. Description: and Environment: lines appear when the license carries these fields.
  • Version. The license version. Licenses bound to the PostgreSQL system identifier have version 3.
  • Limits. One line for each limited object type: Pipelines, Documents, Fragments, Text Splitters, Embedding Models, Agents, LLMs, Api Keys and Taxonomies. An object type without a line, or with the limit 0, has no limit, and none means that no object type is limited.
  • Errors. When the license cannot be used, the command prints Error: "<result>" instead of the details and exits with status 1. The result is Invalid for a license that is malformed, of an unsupported version or issued for another system ID, Expired, Missing for an empty value, or The system id for this license version could not be computed.

Command-line interface describes the license subcommands.

License installation​

The first installation obtains the system ID, then installs the license. The steps are part of Install on Kubernetes and of steps 4 to 6 of Install for evaluation:

  1. The secrets file holds a placeholder, such as pending, or an empty value in FOUNDATION4AI_APP_LICENSE.
  2. The first application install migrates the database, then stops at the license check, which prints the system ID and fails.
  3. The operator sends the system ID to the Foundation4 provider and receives the license.
  4. The operator sets the license in foundation4ai.secrets.env, applies the Secret and runs the application install again.

The license check Job fails at once after a failed check, so Helm reports a failed pre-install hook without waiting for the Helm timeout. The failed Job and the log remain until the next install or upgrade of the application release, which replaces the Job.

License renewal​

A renewed license replaces the license of a running installation, for example before the expiry date or when the limits change. The renewed license is checked first, because a license that fails the check stops the upgrade and every restarted pod.

  1. Check the renewed license against the database:

    kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \
    ./foundation4ai license details '<renewed license>'

    Expected result: the license details, starting with License:, and the expected expiry date and limits. Error: "Invalid" or Error: "Expired" means that the license cannot be used; the procedure stops here.

  2. Replace the value of FOUNDATION4AI_APP_LICENSE in foundation4ai.secrets.env and apply the Secret:

    kubectl kustomize . | kubectl apply -n foundation4ai -f -

    Expected result: secret/foundation4ai-secrets configured.

  3. Upgrade the application release, which runs the license check and restarts the API server and the workers with the renewed license, then check the license that the API server reads:

    helm upgrade foundation4ai ./charts/foundation4ai \
    -n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10m
    kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \
    ./foundation4ai license check

    Expected result: Helm reports STATUS: deployed, and the check prints Checking for a valid license... OK.

When the application release is rendered without access to the cluster, the API server and the workers are restarted by hand after step 3, as Secrets and keys describes.

Foundation4 reports no warning before a license expires. The operator records the expiry date of each license and renews the license before that date. GET /license, with an admin API key such as the master key, returns the expiry date, the limit of each object type and the number of objects in use:

curl -s "$FOUNDATION4_URL/license" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"

Expected result: HTTP 200 with the license details. The following response is shortened to two of the nine entries of items:

{
"name": "Example Organization",
"description": null,
"environment": "production",
"version": 3,
"created": "2026-11-01T00:00:00+00:00",
"expires": "2027-11-01T00:00:00+00:00",
"valid": true,
"status": null,
"items": [
{"object_type": "pipelines", "limit": 10, "used": 4, "estimated": false},
{"object_type": "documents", "limit": 1000000, "used": 182340, "estimated": true}
]
}

expires is null for a perpetual license, and limit is null for an object type without a limit. valid and status report the license as the API server enforces the license. GET /license describes every field.

License enforcement at startup​

The API server and each worker read the license at startup. The license check Job checks the license at every installation and upgrade of the application release. The database migration Job and the master key Job do not read the license. A license that is missing, malformed, issued for another system ID, of an unsupported version or expired stops the process:

ProcessOutput
License check JobSystemID: <system ID>, then Checking for a valid license... followed by Missing, Invalid, Expired or The system id for this license version could not be computed, then Error: "License check failed: <result>". The Job fails, and the install or upgrade stops.
API serverError: "Failed to initialize server: License check failed: Invalid license"
WorkerError: "License check failed: Invalid license"

An expired license replaces Invalid license with Expired license, and a system ID that cannot be computed with Error computing system id. The API server and the workers also log the warning Failed to validate license for system id: <system ID>.

A license expiry does not stop a running API server. The workers stop after the expiry, as License enforcement at runtime describes. A pod that restarts after the expiry, after a node failure or during a rolling update, does not start again until a valid license is installed.

HTTP 401 on POST /login is a credential error, never a license error. A license error appears either at startup or as HTTP 403.

License enforcement at runtime​

The API server checks the license before every operation that creates or changes data:

  • Checked operations. Creating and updating pipelines, text splitters, embedding models, agents, LLMs, API keys and taxonomies; creating and expiring documents; changing classifications, indexes, taxonomy entries and API key permissions; direct LLM queries; agent execution and the agent retrieval dry run.
  • Unchecked operations. Reads, searches and deletes.
  • Workers. Each worker checks the expiry date before each batch. After the expiry, the worker logs The license is no longer valid: the worker stops; queued documents wait for a renewed license and stops with Error: "License check failed: Expired license". Documents that are not yet processed remain pending.

A refused operation returns HTTP 403 with one of the following messages. Errors describes each message.

MessageCondition
Invalid license: ExpiredThe license has expired
Invalid license: Exceeded("<type>")For pipelines, text splitters, embedding models, agents, LLMs, API keys and taxonomies: a cached count exceeds the limit for the named type, and every checked operation fails, whatever the object type. For Documents and Fragments: the count has reached the limit, and requests that add documents fail.
License limits exceeded for <type>Creating one more object of the type would exceed the limit

The API server counts objects in the following ways:

Object typesCountRefresh
Pipelines, text splitters, embedding models, agents, LLMs, API keys, taxonomiesExact countAt API server startup and every 10 minutes; each create also counts exactly
Documents, fragmentsLive row counts from the PostgreSQL statistics, without ANALYZEAt API server startup and every 10 seconds

Deleting objects lowers the counts at the next refresh. Restarting the API server refreshes every count at once. Documents accepted before a count reaches the limit are processed in full, so the counts can pass the limit by the documents added within one refresh. The workers keep no counts and check only the expiry date.

The queue keeps each processing job for 24 hours after the document is submitted. When a renewed license is deployed within that time, the restarted workers process the queued documents. Documents whose jobs were removed from the queue remain pending, and the client application submits these documents again, as Ingest documents reliably describes.

Troubleshooting​

Installation or upgrade stopped at the license check​

  • Symptoms. helm install or helm upgrade of the application release fails with a failed pre-install or pre-upgrade hook, and the Job foundation4ai-api-server-license-check shows Failed.
  • Diagnosis. kubectl logs -n foundation4ai job/foundation4ai-api-server-license-check shows Checking for a valid license... followed by Missing, Invalid, Expired or The system id for this license version could not be computed.
  • Cause. The license in foundation4ai-secrets is empty or still the placeholder, does not match the system ID or has expired, or the database user cannot run pg_control_system().
  • Resolution. Obtain a license for the system ID in the log, set the license in foundation4ai.secrets.env, apply the Secret, and install or upgrade the application release again. For an unavailable system ID, grant the permission as Database describes.
  • Actions to avoid. Deleting the failed Job before the system ID is recorded. The log of the Job is the only source of the system ID during the first installation.

API server or workers exiting with a license error​

  • Symptoms. The server or worker containers restart repeatedly, and the logs report License check failed.
  • Diagnosis. kubectl logs -n foundation4ai deploy/foundation4ai-api-server -c server --previous shows whether the message ends with Invalid license or Expired license, and shows the warning with the system ID. kubectl logs -n foundation4ai deploy/foundation4ai-api-server-worker -c worker --previous shows the same message for a worker.
  • Cause. The license is not valid for the database. The database was replaced or restored with a new system ID, or the license expired, which stops the workers and every restarted pod.
  • Resolution. Obtain a license for the system ID in the warning and follow License renewal from step 2.
  • Actions to avoid. Recreating the database or reinstalling the core release to clear the error. A new database has a new system ID and needs a new license as well.

License rejected for a license issued for the installation​

  • Symptoms. license details or the license check prints Invalid for a license that the Foundation4 provider issued for this installation.
  • Diagnosis. kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- ./foundation4ai license system-id shows the current system ID. The system ID sent to the provider is compared with the current value.
  • Cause. The system ID changed after the license request: the database was moved to another cluster, restored under another name, or database.schema changed. For licenses of versions 1 and 2, a recreated database or a new schema owner also changes the system ID. A license copied with missing or extra characters also reads as invalid.
  • Resolution. Copy the license again without line breaks. When the system ID differs, request a license for the current system ID.
  • Actions to avoid. Changing database.schema to match a system ID. The schema setting selects the tables that Foundation4 reads, and a changed schema produces another system ID.

Writes refused with HTTP 403 while the license is current​

  • Symptoms. Create and update requests return HTTP 403 with Invalid license: Exceeded("<type>"), although the license has not expired.
  • Diagnosis. GET /license, as shown in License renewal, returns the limit and the number of objects in use for each object type. status names the exceeded limit.
  • Cause. For a configuration object type, such as pipelines or API keys, the cached count exceeds the license limit, and every checked operation fails. For documents and fragments, the count has reached the limit, and only requests that add documents fail.
  • Resolution. Delete objects of the named type and restart the API server to refresh the counts, or install a license with higher limits.
  • Actions to avoid. Creating objects of other types to test the license. Every checked operation fails while the count of a configuration object type exceeds the limit.

Documents pending after a license renewal​

  • Symptoms. Documents submitted before or during the expiry remain pending after the renewal.
  • Diagnosis. The client application finds the documents concerned, as described in Pending documents. kubectl get pods -n foundation4ai shows whether the worker pods run since the renewal.
  • Cause. Workers stop after the expiry, and the queue removes each job 24 hours after the document was submitted. Documents whose jobs were removed are no longer processed.
  • Resolution. The client application submits the documents again, as described in Ingest documents reliably.
  • Actions to avoid. Restarting the workers to process removed jobs. Jobs removed from the queue are not processed again after a restart.