Shoehorn – Backstage Without the Maintenance Overhead

TL;DR

TL;DR: Shoehorn is a self-hosted intelligent developer platform that replaces Backstage’s value with a fraction of the setup cost — point it at GitHub and your clusters, and you have a catalog, search, docs, and governance in 15 minutes.

Source and Accuracy Notes

⚠️ This section is MANDATORY. All links must be verified from actual source, not guessed.

• Project page: shoehorn.dev
• Source repository: github.com/shoehorn-dev
• License: MIT (verified via GitHub)
• HN launch thread: news.ycombinator.com/item?id=48077324
• Source last checked: 2026-06-29

What Is Shoehorn?

Shoehorn is an open-source developer platform that positions itself as “Backstage without the maintenance overhead.” It launched its public beta on May 8, 2026, and is built and maintained by a Swedish team.

The core pitch: Backstage is powerful, but it requires significant ongoing maintenance — a dedicated portal team just to keep it alive. Shoehorn runs as just another service in your stack. You point it at your GitHub organization, cloud vendors, and Kubernetes clusters, and roughly 15 minutes later you have a service catalog, full-text search, documentation links, and governance tooling.

Key differentiator from Backstage: Shoehorn reads your existing catalog-info.yaml files directly. If your team already uses Backstage’s entity format, the migration path is minimal — your existing catalog files work without modification.

Feature Highlights

• Service catalog — auto-discovers services from GitHub repos and Kubernetes workloads
• Ownership mapping — ties services to teams and individuals automatically
• Impact analysis — shows dependency graphs up to 5 levels deep
• Forge workflows — reusable templates to scaffold new services and provision infrastructure
• Approval gates — enforce sign-off workflows before changes go live
• Backstage-compatible — catalog-info.yaml files work out of the box
• Built-in i18n — supports en, sv, fr, es, de, fi, and nl
• Multi-interface — CLI, Terraform provider, REST API, and Admin UI

Setup

Shoehorn ships as a set of services you deploy to your own infrastructure. There is no hosted SaaS option.

Prerequisites

• Kubernetes cluster (or Docker Compose for local testing)
• GitHub organization with repos you want to catalog
• Helm 3 or Terraform for deployment

Deploy via Helm

# Add the Shoehorn Helm repository
helm repo add shoehorn https://shoehorn-dev.github.io/helm-charts
helm repo update

# Install Shoehorn
helm install shoehorn shoehorn/shoehorn \
  --set鞋 webhook.enabled=true \
  --namespace shoehorn --create-namespace

Connect Your GitHub Organization

The Shoehorn k8s-agent pushes workload data to Shoehorn — no inbound access required to your cluster. For GitHub, you configure a GitHub App or personal access token with read access to your organization and repositories.

# Authenticate the CLI
shoehorn auth login --server http://localhost:8080 --token shp_your_token_here

# Verify your identity
shoehorn whoami

# Browse the discovered catalog
shoehorn get entities
shoehorn search "payment"

Install the Kubernetes Agent

# Deploy the k8s-agent to your cluster
kubectl apply -f https://docs.shoehorn.dev/k8s-agent.yaml

# The agent will push workload data to your Shoehorn instance

Deeper Analysis

How It Works

Shoehorn operates in three stages:

1. Connect — Point Shoehorn at your GitHub org, cloud accounts, and Kubernetes clusters. This takes about 15 minutes of initial configuration.

2. Map — Shoehorn crawls your repos directly. The k8s-agent pushes workload data from your clusters. The output is a live inventory of what runs where, who owns it, what it depends on, and where its documentation lives.

3. Query — Search across the entire catalog. See dependency chains. Know who to page at 2am.

CLI Reference

The Shoehorn CLI (shoehorn) is written in Go and published to Homebrew, Mise, and Scoop.

# Install via Homebrew
brew tap shoehorn-dev/tap
brew install shoehorn

# Search the catalog
shoehorn search "authentication"

# Get entity details with scorecard
shoehorn get entity payment-service --scorecard

# Run a Forge workflow
shoehorn forge execute my-mold --env production

Terraform Provider

Shoehorn ships an official Terraform provider for managing configuration as code.

resource "shoehorn_entity" "my_service" {
  name    = "my-service"
  owner   = "platform-team"
  kind    = "service"
  spec = jsonencode({
    lifecycle     = "production"
    tier          = "2"
    owner_contact  = "[email protected]"
  })
}

Practical Evaluation Checklist

• [ ] Installs via Helm without custom fork
• [ ] Discovers at least one GitHub repo within 15 minutes of setup
• [ ] CLI shoehorn search returns results in under 200ms
• [ ] catalog-info.yaml from a Backstage entity parses correctly
• [ ] k8s-agent pushes workload data without requiring inbound cluster access
• [ ] Terraform provider can manage an entity resource
• [ ] i18n switches correctly between supported locales

Security Notes

• The k8s-agent is deployed inside your cluster and pushes data out — it does not require inbound access from Shoehorn’s servers to your cluster.
• Authentication uses personal access tokens (PAT) or GitHub App credentials. Store these in Kubernetes secrets or your secret manager.
• Shoehorn stores the catalog data on your own infrastructure. No data leaves your environment unless you explicitly configure webhooks or integrations.
• The Terraform provider supports declarative management of catalog entities.

FAQ

Q: Does Shoehorn replace Backstage entirely? A: It depends on your use case. If you primarily use Backstage for its service catalog, search, and ownership features, Shoehorn covers those with far less operational overhead. If you use Backstage’s plugin ecosystem for software templates, API docs, or tech radar, those capabilities are not yet in Shoehorn — though Forge workflows and the SDK aim to fill some of that gap.

Q: How does it compare to other Backstage forks like Red Hat’s downstream? A: Most Backstage forks still carry Backstage’s operational burden. Shoehorn’s architecture is different — it is purpose-built as a single service rather than a meta-framework that requires assembly. It also Backstage-compatible, so you can migrate incrementally.

Q: Does it work with existing Backstage catalog files? A: Yes. Shoehorn reads standard catalog-info.yaml entities without modification. If you have an existing Backstage setup, you can point Shoehorn at the same files.

Q: Is there a hosted or SaaS option? A: Not currently. Shoehorn is strictly self-hosted. The team has indicated this may change in the future.

Q: What is the license? A: MIT License. The core platform and all listed repositories are open source.

Conclusion

Shoehorn targets a specific pain point: developer portals built on Backstage often become second jobs for the teams tasked with maintaining them. By designing Shoehorn as a single deployable service rather than a plug-in framework, the team has significantly lowered the operational bar.

The 15-minute setup claim holds up based on the documented installation flow. The Backstage compatibility via standard catalog-info.yaml files means migration is not an all-or-nothing event. For teams that want the catalog-and-search value of a developer portal without the maintenance commitment, Shoehorn is worth evaluating.

If you have used Shoehorn or are evaluating it alongside Backstage, the GitHub discussions are a good place to ask questions.