Frequently Asked Questions

Shoehorn is an internal developer platform that surfaces who owns what across your stack. Point it at your GitHub org and clusters, and it builds the catalog, search, docs, workflows, governance, and Kubernetes view for you, without turning your team into platform developers.

An entity is a single catalog entry. It can come from two places: a manifest in Git or cloud storage, either Shoehorn-native (.shoehorn/*.yaml) or Backstage-compatible (catalog-info.yaml), where one manifest with kind: Component, type: service equals one entity. Or a Kubernetes workload discovered by the cluster agent.

Shoehorn supports the nine Backstage-compatible kinds for manifests: Component, API, Resource, System, Domain, Group, User, Location, and Template.

What counts as an entity from Kubernetes

Only workloads: Deployment, StatefulSet, and DaemonSet. Services, ConfigMaps, Secrets, Ingresses, ReplicaSets, and Pods are not persisted as catalog entities.

Workloads are deduplicated across clusters by namespace + kind + name. The same Deployment running in prod, staging, and dev is one entity with three runtime instances, not three separate entities. Cluster is operational data, not part of the entity identity.

What counts separately

Repositories, Teams, and Kubernetes clusters are tracked as separate license resources with their own limits, so they don't burn your entity quota. Argo CD and FluxCD applications surface through annotations on existing entities, not as new ones.

In short: entity quota = unique manifest entries + unique workloads across all clusters. A workload deployed to three clusters costs one. Cluster quota is independent.

Backstage is a framework you assemble. You pick the plugins, write the integrations, and stand up a team to keep it running. Shoehorn ships the same surface area (catalog, search, docs, ownership, workflows, governance, Kubernetes view) already wired together, so the team operating it can be one or two people instead of a portal squad.

Yes. You don't need to migrate on day one. Just shoehorn us in.

Shoehorn is fully compatible with Backstage catalog files, so your existing setup keeps working as-is while you evaluate:

• ✓ catalog-info.yaml files are auto-discovered and indexed, with no changes needed
• ✓ Run Backstage and Shoehorn in parallel during evaluation
• ✓ When you're ready, the CLI includes convert tooling to migrate your catalog over cleanly

Compatibility comes first. Start using Shoehorn today, and migrate on your own schedule.

Self-hosted, runs on your own infrastructure. Deploy with the Helm chart directly or via the Terraform Helm provider and you're up in minutes. Multi-arch containers (amd64 and arm64) mean it works wherever you run things.

Everything we ship today is in the Beta. We aren't gating features behind tiers while the product is still finding its shape. If packaging changes later, we'll communicate it clearly before it affects anyone running on Beta pricing.

Shoehorn currently supports Zitadel and Okta out of the box. Support for other OIDC providers like Microsoft Entra ID (Azure AD) and Google Workspace is coming soon. Need a different provider? Get in touch. We prioritise additions based on customer demand.

Shoehorn currently includes built-in translations for English, Swedish, French, Spanish, German, Finnish, and Dutch. These translations are currently AI-generated, and we're improving them over time with feedback from teams using Shoehorn.

If you want to help improve a language or contribute a new one, the translation files are open here: shoehorn-dev/i18n-translations.

Shoehorn includes a read-only MCP server for AI assistants that need safe access to catalog and platform context. For anything operational, scriptable, or CI/CD-driven, the fully-featured CLI is still the best integration point: get, put, pipe, automate. The REST API is also available for custom integrations.

Shoehorn uses hardened base images, and every new release ships dependency patches alongside the code. The default install path stays current without your team having to maintain a hardened build of its own.

Not today, but we're planning to open source parts of the project later this year. We'll announce which components, and under what license, when it ships.

Currently, GitHub. Repo discovery, catalog ingestion, docs indexing, and workflows are all built around it today. If you need another source control provider, get in touch. We're open to adding more.