License

Shoehorn ships with a free tier built in. No license key needed to run it. Higher editions raise the active-agent limit and unlock paid support. All features are available on every edition. There’s no feature gating.

Free is one active agent (one cluster). No node cap.

Editions

Edition	Key required	Active agents (clusters)	Pricing
Free	No	1	Free
Beta	Yes	3	6 months free, then a 30-day read-only window before auto-disconnect
Standard	Yes	3 (extra clusters via license upgrade)	TBA

Entities, users, integrations, repositories, addons, and nodes are unlimited on every edition. Only active K8s agents (= clusters) are counted.

Beta period and grace window

A Beta license runs free for 6 months from issue. After that:

1. 30-day read-only window. The admin UI shows a banner. Mutating API calls return 423 BETA_ENDED_READ_ONLY. Catalog reads, dashboards, and agent traffic keep working, so existing data stays observable. License activation also keeps working, so a customer can switch to Standard without restoring write access first.
2. Auto-disconnect. When the 30 days expire, a daily background job keeps one cluster (smallest node count, oldest first) and revokes the agent tokens on the rest. Data stays in place. The disconnected agents can’t authenticate until they’re reactivated under a paid license.

Beta licenses issued before 2026-11-10 won’t expire before that date even if their natural 6-month end is earlier. This protects legacy Beta customers from a sudden read-only flip when per-cluster pricing took over.

Standard cluster overage

Standard includes 3 clusters in the base subscription. When an agent registers a cluster past that count, the registration parks as pending instead of failing.

Shoehorn is self-hosted with offline-signed licenses. Capacity goes up only when we issue a new license that covers more clusters. There’s no in-product approve button and no automatic billing. Admins see pending rows in Admin > Settings > License and pick one of two actions:

• Request upgrade. Opens an email to sales@shoehorn.dev with the cluster name and ID. We send back a new signed license that raises the cluster count. After you activate it, the agent’s next register attempt succeeds.
• Dismiss. Removes the row from the list. The agent will keep trying to register, so dismiss is just bookkeeping. To actually stop the loop, remove the agent from the cluster.

The list is also reachable from the API:

# List pending registrations
curl https://shoehorn.example.com/api/v1/license/pending-clusters \
  -H "Authorization: Bearer <admin-token>"

# Dismiss a pending row (does not grant capacity)
curl -X DELETE https://shoehorn.example.com/api/v1/license/pending-clusters/<cluster_id> \
  -H "Authorization: Bearer <admin-token>"

License key format

Keys are issued as SHP-<EDITION>-<PAYLOAD>.<SIGNATURE> where edition is one of:

• BE for Beta
• ST for Standard

The prefix is cosmetic. The actual tier comes from the signed payload.

View license status

In the UI

Admin > Settings > License shows the active edition, licensee, expiration, active-agent usage, pending registrations, and any warnings. Beta tenants past their end date also see the read-only countdown.

Via API

curl https://shoehorn.example.com/api/v1/license \
  -H "Authorization: Bearer <admin-token>"

curl https://shoehorn.example.com/api/v1/license/usage \
  -H "Authorization: Bearer <admin-token>"

The license-status response includes beta_ends_at, beta_grace_ends_at, and is_read_only. They’re set only when relevant; is_read_only is false for non-Beta editions.

Activate a license

curl -X POST https://shoehorn.example.com/api/v1/license/activate \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"license_key":"SHP-ST-..."}'

Successful activation updates the edition, limits, and expiration for the current tenant. If the tenant was in a Beta read-only window, activation lifts the write block on the next status read.

Deactivate a license

curl -X POST https://shoehorn.example.com/api/v1/license/deactivate \
  -H "Authorization: Bearer <admin-token>"

The tenant falls back to Free limits (1 active agent).

Expiration

Shoehorn warns when a license expires within 30 days. After expiry the license is marked invalid in the status response and the admin UI. Limits keep resolving from the stored edition until the license is changed or removed.

Beta licenses don’t expire the same way. The read-only window plus auto-disconnect handle that transition (see Beta period and grace window).

Operational notes

• License checks are tenant-aware.
• Usage counts come from the live database, not cached estimates.
• API keys and automation clients see the same tenant limits as interactive users.
• The auto-disconnect job runs once a day on the worker service. With multiple worker replicas, only one runs it per cycle via a distributed lock.
• If license data is unreadable, Shoehorn falls back to Free limits.

See also

• API Overview: authentication and conventions
• Teams
• K8s Agent