Licensing
No feature is licence-gated, on any tier. Every edition runs the same binary with the same features: search, navigation, the API, every MCP tool, auditing, single sign-on through your proxy, branding. Tiers differ in exactly two numbers, how many repositories and how many users, and both come out of the licence file. Changing tier is a new licence file, not a new release.
That is a security property as much as a commercial one. A gated feature is a place where the product behaves differently depending on the licence, and the dangerous version of that is one where a licence lapse changes who can see what. There is no such place in searchcode enterprise.
One thing a licence can say beyond its two numbers: that the instance serves service accounts only, with no web UI and no person signing in. It removes surfaces and never adds one, and it never changes what an admitted service account can see. See A licence for service accounts only.
Verification is offline
The licence is a signed file. It is verified against a public key compiled into the binary, with no network call, at startup. There is no licence server, no check-in, no telemetry and no phone-home, on any tier. An air-gapped install verifies its licence exactly the way a connected one does. See Trust for the full list of what the process does and does not connect to.
Where the licence goes
Either of:
license.fileinsearchcode.yaml, the path to the licence key file;- the
SEARCHCODE_LICENSEenvironment variable, holding the licence text.
When both are set, the file wins. The file is what an operator edits and the environment is what a platform injects, and a stale injected value silently overriding a deliberate edit would be the wrong way round.
In Kubernetes, put the licence in a Secret created out of band and reference it
from the chart's license.existingSecret. Never put it inline in a values file.
See Install with Helm and
Air-gapped install.
A licence is read once, at startup. Replacing the file and reloading the
configuration does not pick up a renewal; restart the process. license.file is
a restart-only setting, and a reload that changes it is refused, which is the
signal that a restart is the step.
No licence at all is a supported, stable way to run. It is the community edition: 3 users and 5 searchable repositories, no expiry, no countdown. Enough to try the product; a licence is what a team runs on.
The two meters
Repositories: warns, never blocks, on a licensed tier
The repository meter counts what is in the estate. A directory source counts
units, not mounts: how a mounted directory becomes one or many searchable
units is unitDetection on the source, and it is a metering input.
With a licence, crossing the licensed count logs a warning, and the count and
limit are on /api/v1/status and in license show. Nothing is blocked. The
repository over the limit is cloned, indexed and searchable exactly like the one
before it, and the difference is reconciled at renewal.
With no licence, the limit holds. The community edition makes the first 5 repositories by name searchable: the same 5 across restarts, whichever finished cloning first. The rest are cloned and listed and not indexed, and every search says how many repositories are outside the limit and that a licence lifts it. Adding a repository whose name sorts earlier moves the last of the 5 out. The community edition has no contract to reconcile at renewal, which is why it is the one tier where this meter blocks.
Users: refuses only a genuinely new person
The user meter counts distinct people seen in the last thirty days. It rolls, so leavers and one-off triallists drop off without anybody pruning a list.
Every credential a person holds — a key for Claude Code, another for Cursor, an OAuth token — rolls up to that one person. One engineer with three agents is one user. A service account declared in configuration has no person behind it, so it counts as its own user.
This is the only meter that can refuse a person, and it refuses narrowly. In order:
- An administrator is never refused, whatever the count. The person who can fix the problem must always be able to sign in.
- Anybody seen in the last twelve months is never refused. "New" means new to this instance in a year, not "outside the thirty-day count". Somebody back from a long holiday is not locked out of a tool they have used for a year.
- If the user store cannot be read, the meter admits, and says so loudly. An unreadable count is a fault in our own bookkeeping, and locking an organisation out of its code search over one is the worse failure. (Authentication against the same store still fails closed. This applies to the count only.)
- Otherwise, a person never seen before is refused when the active count is at the limit.
A refused person is told the instance is at its licensed user limit and that this
is not an access-control decision, so nobody mistakes it for a permissions problem.
The admin page warns as the count approaches the limit and says when new users are
being refused. The refusal is recorded in the audit log as license.user_limit_reached and counted
as searchcode_user_limit_refusals_total.
A licence for service accounts only
A licence can carry access: service-accounts. It is for an instance used only by
an automated integration — an agent platform calling the API and MCP with a
service account — under an agreement that does not include people using it
directly. While that licence is installed:
- There is no web UI. No UI listener is bound, whatever
server.uiListensays; startup printssearchcode ui: off (licence: service accounts only)and warns ifserver.uiListennames an address. - Only service accounts authenticate, on the API and on MCP. A person's API
key, an OAuth token and
auth.mode: open's anonymous access are refused with 401 and recorded in the audit log asauth.access_restricted, naming who was refused. Service accounts are declared inserviceAccountsas usual; useauth.mode: localorproxyandmcp.auth.mode: apikey. Underauth.mode: opennothing can use the instance, and startup says so. - The user limit counts service accounts only. A licence with
users: 1admits the first service account to authenticate and refuses any other. Rotating that account's token keeps its seat; renaming the account makes it a new one, admitted once the old name has been unused for thirty days. - Nothing is deleted. Accounts, personal API keys and OAuth refresh tokens stay
in
subjects.db, refused while the licence is installed, and work again under a licence without the restriction. - It holds past expiry and grace. A lapsed licence pauses indexing as usual; it never turns the UI back on.
Nothing about it stops the instance starting. Each setting it makes inert is
logged once, by name, and listed by searchcode doctor, which also counts the
personal API keys being refused.
If the licence is removed, the instance runs as the community edition, with the UI
and its 3 users. It records that it once ran under the restriction, and
license show, the license.previousAccess field of /api/v1/status and the
startup log all say so. That record restricts nothing.
When the licence is absent, expired or invalid
Nothing here can stop the process. An absent, unreadable, tampered or expired
licence, or one in a format this build does not recognise, puts the instance in
community mode: it keeps serving with the community limits, logs a warning
that says why, and reports the reason on /api/v1/status. The warning is logged at
warn and not error, deliberately: every feature is working, and an error level
would page somebody for a commercial event.
The expiry ladder
A licence with an expiry date moves through four states.
| State | When | What changes |
|---|---|---|
valid |
More than 30 days before expiry | Nothing. |
expiring |
Within 30 days of expiry | Administrators see a notice. Other users see nothing. |
grace |
Past expiry, inside the grace period the licence names | Everything still works. The notice widens to every user. |
past_grace |
Past the grace period | Indexing pauses. Administrators are confined to the licence page in the admin UI. |
Past grace, the list of things that keep working is the important half:
- search, over everything already indexed;
- the HTTP API and every MCP tool;
- the audit log;
- authentication and authorisation, exactly as configured.
The estate goes stale rather than dark. A lapsed licence that widened access, or stopped recording security events, would be an incident at your site, and the ladder is shaped so that neither can happen.
Ingestion reports the pause as license_expired on
searchcode_ingestion_paused, so the shipped alert rules see it.
A licence that covers older versions only
A licence can name the last product version it covers. Running a newer build than
that is treated as past_grace and not as an invalid licence: the licence is
genuine, it just does not cover this build. Indexing pauses and everything else
keeps working, and the remedy is to renew or to run the last version the licence
covers.
Clocks
A licence that is not valid yet is checked with a day of tolerance, because air-gapped machines often have no time synchronisation. If the system clock reads earlier than the binary's own build time, the instance warns that the clock is wrong, since a licence that appears "not yet valid" is then almost certainly the clock.
Checking the licence
On the command line, without a running instance:
searchcode --config /etc/searchcode/searchcode.yaml license show
It prints the licence's source, identity, issue and expiry dates, its state on the ladder, the reason for that state, whether it admits service accounts only, and both meters with their current counts and limits. It works on a broken licence, which is the point: it renders what it could not verify and why.
On a running instance, the same report is the license block of
/api/v1/status and the licence panel of the admin page. All three are computed
in one place, so they cannot disagree.
In Prometheus, searchcode_license_expiry_timestamp_seconds, the two meters
and their limits, and the refusal counter, with alert rules for expiry, refusals
and the repository limit already written. See
Monitoring.
The ladder state is logged at startup and re-evaluated daily, and a meter is logged when it crosses a level, so an operator who reads logs rather than the admin page still finds out.
Related
- searchcode enterprise — what it does for what every edition includes.
- Backup and restore: the licence is one of the secret files your configuration references, and belongs in your secret manager's backup.
- Upgrades for moving to a new release.