We built Shoehorn out of frustration. Some internal developer portals act like frameworks: you install one, then spend a quarter sifting through unmaintained community plugins, writing TypeScript and React, just to make it presentable. Most people running these portals are platform engineers, not frontend developers. So the portal becomes a product they’re stuck maintaining, instead of a tool their developers can just use.<\/p>\n\n\n\n
Shoehorn starts from the opposite assumption: you should be able to use it, not develop it. Whether you reach the catalog from the CLI, Terraform, the web UI, or an MCP-connected IDE agent, it’s the same product end to end. You install it, it discovers your stuff, and it works.<\/p>\n\n\n\n
One view of your whole stack: every workload across every cluster, the cloud resources behind them, ownership, and scorecards. No flipping between cluster dashboards, cloud consoles, and team wikis to answer one question.<\/p>\n\n\n\n
The sovereignty story is downstream of that. Because Shoehorn is genuinely self-hostable in one Terraform apply, you can run it on infrastructure you control, in a jurisdiction you choose. That’s why it’s a natural fit for UpCloud customers. But sovereignty isn’t the pitch. Simplicity is. Sovereignty is what you get for free when the product is small enough that one person can run it.<\/p>\n\n\n\n
The rest of this post is what that looks like in practice.<\/p>\n\n\n\n
What is Shoehorn<\/h2>\n\n\n\n
Shoehorn is an Intelligent Developer Platform: service catalog, scaffolding engine, scorecards, fuzzy search, multi-tenant by design. Same category as Backstage, Port, Cortex.<\/p>\n\n\n\n
The differentiator is operational. We built it for the 95% of teams that don’t have a dedicated platform team to maintain a portal. Opinionated defaults instead of a plugin ecosystem. Auto-discovery from Kubernetes, GitHub, and your IdP instead of hand-written manifests. One install, sensible defaults, working catalog inside an afternoon. One person can run it. That’s the whole product thesis.<\/p>\n\n\n\n
Architecturally, it’s a small set of Go microservices (api<\/code>, eventbus<\/code>, worker<\/code>, crawler<\/code>, forge<\/code>) backed by Postgres 18, Meilisearch, Valkey, and Redpanda. Authentication is OIDC: Zitadel, Okta, or any compliant provider. Multi-tenant isolation is enforced at the database layer using Postgres row-level security, not application-layer filtering, so a forgotten WHERE<\/code> clause can’t leak data across tenants.<\/p>\n\n\n\n
It ships as a Helm chart, and that’s enough if you want to drive it yourself. But for partners and customers who’d rather not assemble the pieces by hand, we ship something more direct.<\/p>\n\n\n\n<\/figure>\n\n\n\n
What it adds on top of a Kubernetes cluster<\/h2>\n\n\n\n
Platform engineers ask us this regularly: What does Shoehorn add over kubectl and ArgoCD?<\/p>\n\n\n\n
Shoehorn doesn’t replace either of them. It sits at a different layer.<\/p>\n\n\n\n
\n
kubectl<\/code><\/strong> answers “what’s the state of this resource<\/em>, in this cluster<\/em>, right now<\/em>?” It’s a per-cluster CRUD tool. Brilliant for operations. Useless for “which team owns the payment service?” or “which services are below tier-2 reliability?”, because those questions aren’t about resources, they’re about your organisation<\/em>.<\/li>\n\n\n\n
ArgoCD \/ Flux<\/strong> answer “is the cluster in sync with the git-declared desired state?” GitOps is the right way to deploy. But ArgoCD doesn’t know what a service<\/em> is in business terms, what its dependencies are, who’s on call, or whether it has a runbook. It’s a synchronisation engine, not a catalog.<\/li>\n\n\n\n
Shoehorn<\/strong> answers questions spanning clusters, repositories, teams, and time. Where does this service run? Who owns it? Which version is in prod? What’s its scorecard? Where’s the runbook? It’s a catalog plus a workflow layer plus a governance layer, built for people<\/em> rather than resources.<\/li>\n<\/ul>\n\n\n\n
In day-to-day terms, here’s how the three pieces work together for a typical Shoehorn-on-Kubernetes setup:<\/p>\n\n\n\n<\/figure>\n\n\n\n
The K8s agent: zero-config service discovery<\/h3>\n\n\n\n
A small (~50m CPU, <150 MB memory) push-based agent runs in each of your clusters. It watches the Kubernetes API, samples metrics-server<\/code> for CPU\/memory aggregates, and watches GitOps CRDs (ArgoCD Applications<\/code>, Flux Kustomizations<\/code> and HelmReleases<\/code>). Every 30 seconds it pushes a batched, read-only summary to the Shoehorn API.<\/p>\n\n\n\n
What this gives you, with literally zero config beyond installing the agent:<\/p>\n\n\n\n
\n
Every workload in every cluster shows up in the catalog automatically. New services appear within minutes. Removed services disappear.<\/li>\n\n\n\n
Team ownership is inferred from namespace labels (e.g. team: payments-team<\/code>), so there’s no separate manifest to maintain.<\/li>\n\n\n\n
GitOps state is tied to catalog entities, so “is this service in sync?” is a property of the entity, not a separate ArgoCD-tab dance.<\/li>\n\n\n\n
Because it’s push-based, the platform never holds kubeconfig credentials for your clusters. Cluster credentials never leave the cluster. (This is a real benefit for SOC 2 \/ HIPAA \/ generally paranoid environments.)<\/li>\n\n\n\n
Multi-cluster works out of the box. One agent per cluster, all reporting into the same catalog. The same service running across three clusters appears as a single entity, with visibility into all clusters it’s running in. No duplicate entries to deduplicate by hand.<\/li>\n<\/ul>\n\n\n\n
For richer metadata than labels can carry, add a single annotation pointing at an entity file:<\/p>\n\n\n\n
annotations:\n # Relative path, resolved against the repo URL Shoehorn already knows from ArgoCD\/Flux\/crawler\n shoehorn.dev\/entityFile: \".shoehorn\/catalog.yaml\"\n\n # Full URL, when the file lives in a different repo\n shoehorn.dev\/entityFile: \"https:\/\/github.com\/acme\/shared-configs\/blob\/main\/.shoehorn\/checkout.yaml\"\n\n # Multi-service file with a fragment selector\n shoehorn.dev\/entityFile: \".shoehorn\/platform.yaml#checkout-api\"<\/code><\/pre>\n\n\n\n
The file gives you full enrichment: relations, links, runbooks, and interfaces. Start with zero-config and add an entity file only when the extra detail is worth it.<\/p>\n\n\n\n
The CLI: the catalog from the terminal<\/h3>\n\n\n\n
shoehorn<\/code> is a single Go binary, available via Homebrew, Scoop, mise, or a direct download. It does what gh<\/code> does for GitHub: gives the developers who live in their terminal the same product the UI offers, without context-switching.<\/p>\n\n\n\n
A flavour of what you can do without leaving your shell:<\/p>\n\n\n\n
# Browse the catalog\nshoehorn get entities --owner payments-team\nshoehorn search \"payment\"\nshoehorn get entity payment-service --scorecard\n\n# Run a Forge workflow (scaffolding) from the terminal\nshoehorn forge molds\nshoehorn forge run new-go-service --inputs name=billing-api,team=payments-team\n\n# Declarative ops: apply\/diff\/delete catalog entities like kubectl\nshoehorn apply -f service.yaml\nshoehorn diff -f service.yaml\nshoehorn validate mold .\/my-mold<\/code><\/pre>\n\n\n\n<\/figure>\n\n\n\n
The CLI is the same API surface the UI uses, so anything you can do interactively, you can script. CI\/CD pipelines and developer onboarding scripts use it the same way they use kubectl<\/code>.<\/p>\n\n\n\n
Terraform: the install and the day-2 lifecycle<\/h3>\n\n\n\n
Terraform isn’t just for the initial install. The Shoehorn Terraform provider (separate repo: terraform-provider-shoehorn<\/code>) lets you declare catalog entities, teams, ownership, scorecards, and Forge molds the same way you declare any other infrastructure. So your developer platform, the thing that describes your organisation<\/em>, can be version-controlled, peer-reviewed, and rolled back like any other Terraform state.<\/p>\n\n\n\n
Combined with the install module, a partner or platform engineer can describe an entire Shoehorn deployment as code: the platform itself, the org structure, the scorecards, the discovery agent. One terraform apply<\/code> from a fresh kubeconfig to a running, populated, scored, and owned developer platform.<\/p>\n\n\n\n
The TL;DR<\/h3>\n\n\n\n
kubectl<\/code> is the tool for resources. ArgoCD is the tool for sync. Shoehorn is the tool for the things that span clusters, repos, and teams. The three sit at different layers and work fine together.<\/p>\n\n\n\n
MCP support: your developer platform, addressable from an IDE agent<\/h2>\n\n\n\n
Shoehorn includes a built-in Model Context Protocol<\/strong> server. Every instance exposes an MCP endpoint at \/mcp<\/code>, with a public capability document at \/.well-known\/mcp<\/code> for registries and IDE agents to auto-discover.<\/p>\n\n\n\n
Three things matter about this for self-hosted teams:<\/p>\n\n\n\n
\n
The agent talks to your<\/em> Shoehorn.<\/strong> When a developer asks Claude, Cursor, or any MCP-capable IDE, “find me the payment service’s runbook” or “which services on the payments team are below tier-2 reliability?”, that query goes straight to your Shoehorn instance. The catalog data, the team mappings, the scorecards: none of it leaves your infrastructure to answer the question. The AI provider sees the question and the answer, but the index<\/em> lives entirely in your cluster.<\/li>\n\n\n\n
Read-only by design.<\/strong> The v0 MCP surface is annotated readOnlyHint: true<\/code> for every tool. Agents can search the catalog, fetch entity details, look up teams, query scorecards, and read docs. They cannot create, modify, or delete anything. We’ll add write tools deliberately, behind explicit scopes, when it’s clear they’re worth the surface area.<\/li>\n\n\n\n
Bounded by personal access tokens.<\/strong> Each developer generates their own PAT scoped to mcp:read<\/code> from \/profile\/mcp<\/code>, with chosen expiry (30\/90\/365 days or never). The token is bcrypt-hashed at rest; the raw value is shown once. PATs scope to a tenant, so an agent acting on behalf of one tenant’s developer can never see another tenant’s data.<\/li>\n<\/ul>\n\n\n\n
The tool surface today covers catalog entities, teams, scorecards, repositories, workloads, security findings, dependencies, docs, and a few diagnostic tools (zombies, whoami). Enough to make an IDE agent genuinely useful for navigating an internal developer platform; not enough to let it create entities, run Forge molds, or change ownership.<\/p>\n\n\n\n
The transport is stateless Streamable HTTP, protocol revision 2025-11-25<\/code>. The agent on the other side is whichever one you already use. Create PAT token from \/profile\/<\/p>\n\n\n\n<\/figure>\n\n\n\n
![\"-\"](\"https:\/\/upcloud.com\/media\/1-shoehorn-catalog-1024x541.png\")
<\/figure>\n\n\n\n![\"-\"](\"https:\/\/upcloud.com\/media\/2-shoehorn-operations-1024x421.png\")
<\/figure>\n\n\n\n![\"-\"](\"https:\/\/upcloud.com\/media\/4-shoehorn-entities-1024x200.png\")
<\/figure>\n\n\n\n![\"-\"](\"https:\/\/upcloud.com\/media\/3-shoehorn-ide-configuration-1024x817.png\")
<\/figure>\n\n\n\n