Ecosystem and Tools

Shoehorn is more than the portal itself. There are companion tools for CLI access, infrastructure-as-code, addon development, and Kubernetes integration. All are open source under the shoehorn-dev GitHub organization.

Repositories

Tool	Repository	What it does
Shoehorn Platform	shoehorn-dev/shoehorn	The portal itself — API, frontend, microservices
Helm Charts	shoehorn-dev/helm-charts	Official Helm charts for deploying Shoehorn, the K8s agent, and the network observer
K8s Agent	shoehorn-dev/shoehorn-k8s-agent	Kubernetes cluster agent — discovers workloads, collects metrics, pushes to Shoehorn
CLI	shoehorn-dev/shoehorn-cli	Command-line interface for browsing catalog, running Forge workflows, managing auth
Terraform Provider	shoehorn-dev/terraform-provider-shoehorn	Manage Shoehorn resources as code (entities, teams, feature flags, API keys)
Addon SDK	shoehorn-dev/sdk	TypeScript SDK for building Shoehorn addons
Official Addons	shoehorn-dev/addons	Official addon collection (e.g., jira-sync)

Helm Charts

Deploy Shoehorn and the K8s agent to Kubernetes.

Registry: oci://ghcr.io/shoehorn-dev/helm-charts/

Install the platform:

helm install shoehorn oci://ghcr.io/shoehorn-dev/helm-charts/shoehorn \
  --values values.yaml

Install the K8s agent in each cluster:

helm install shoehorn-agent oci://ghcr.io/shoehorn-dev/helm-charts/shoehorn-k8s-agent \
  --set shoehorn.apiURL=https://shoehorn.example.com \
  --set shoehorn.apiToken=sha_your_token_here \
  --set shoehorn.cluster.id=prod-us-east-1 \
  --set shoehorn.cluster.name="Production US East 1"

See the shoehorn-dev/helm-charts repository for values references and full configuration. See K8s Agent for what the agent does and operational considerations.

CLI

Browse the catalog, run Forge workflows, and manage authentication from the terminal.

Install with Homebrew:

brew tap shoehorn-dev/tap
brew install shoehorn

Install with Go:

go install github.com/shoehorn-dev/shoehorn-cli/cmd/shoehorn@latest

Install with Mise:

Add to your mise.toml:

[tools]
"github:shoehorn-dev/shoehorn-cli" = "latest"

Or download from GitHub Releases.

Authenticate and browse:

shoehorn auth login
shoehorn catalog list
shoehorn teams list
shoehorn forge run scaffold-go-service --name my-app --owner my-org

# Governance actions
shoehorn governance actions list [--status X] [--priority X]
shoehorn governance actions get <id>
shoehorn governance actions create --entity-id X --title X --priority X --source-type X
shoehorn governance actions update <id> --status X
shoehorn governance actions delete <id>
shoehorn governance dashboard

# GitOps resources
shoehorn get gitops [--cluster-id X] [--tool argocd|fluxcd]
shoehorn get gitops <id>

See CLI Getting Started for full usage.

Terraform Provider

Manage Shoehorn resources as infrastructure-as-code.

Terraform Registry: shoehorn-dev/shoehorn

terraform {
  required_providers {
    shoehorn = {
      source  = "shoehorn-dev/shoehorn"
      version = "~> 0.1"
    }
  }
}

provider "shoehorn" {
  host    = "https://shoehorn.example.com"
  api_key = var.shoehorn_api_key
}

resource "shoehorn_entity" "payment_api" {
  name        = "payment-api"
  type        = "service"
  description = "Handles payment processing"
  owner       = "payments-team"
  lifecycle   = "production"
  tags        = ["critical", "pci"]
}

resource "shoehorn_team" "payments" {
  name        = "payments-team"
  description = "Payments and billing team"
}

resource "shoehorn_k8s_agent" "prod_cluster" {
  cluster_id   = "prod-us-east-1"
  cluster_name = "prod-us-east-1"
}

Available resources:

shoehorn_entity — catalog entities
shoehorn_team — teams with members
shoehorn_feature_flag — feature flags
shoehorn_api_key — API keys
shoehorn_user_role — user RBAC assignments
shoehorn_integration — third-party integrations
shoehorn_k8s_agent — Kubernetes cluster agents
shoehorn_governance_action — governance action items
shoehorn_forge_mold — Forge workflow templates
shoehorn_forge_approval_policy — Forge approval policies
shoehorn_marketplace_installation — marketplace addon installations

Available data sources:

shoehorn_governance_actions — governance actions (filtered)
shoehorn_forge_molds — Forge mold templates
shoehorn_marketplace_items — marketplace catalog
shoehorn_gitops_resources — GitOps resources from K8s agents

Note: shoehorn_tenant_settings was updated with hidden_pages and forge settings.

See Terraform Provider for provider configuration, supported resources, and API key scope guidance.

Addon SDK (alpha)

Build custom addons that extend Shoehorn with widgets, API routes, and webhook handlers.

Github: shoehorn-sdk

Scaffold a new addon:

npx @shoehorn-dev/addon-sdk init my-addon
cd my-addon
npm install
npm run build

Publish to your Shoehorn instance:

shoehorn addon publish --dir .

Addons have three tiers:

declarative — configuration-only, no code
scripted — JavaScript/TypeScript with SDK helpers
full — complete control over rendering and routing

SDK capabilities

The SDK provides typed access to platform services via the ctx global in the QuickJS sandbox:

Capability	Description
`ctx.log`, `ctx.config`, `ctx.secrets`	Logging, configuration, encrypted secrets
`ctx.http`	Synchronous HTTP client (URL allowlisted)
`ctx.entities`	Catalog entity CRUD
`ctx.cache`	Valkey/Redis ephemeral cache
`ctx.events`	Redpanda/Kafka event pub/sub
`ctx.db`	PostgreSQL read-only queries
`ctx.search`	Meilisearch full-text search
`ctx.kv`	Persistent key-value store
`ctx.notifications`	Platform notification sender

Frontend addons get a CSS design system (sh-* classes) matching the host app, plus XSS-safe HTML builders and a Svelte 5 component bridge.

The jira-sync addon is a production-ready example of a scripted addon.

See Marketplace and Addons for the full permissions reference.

Required API key scopes for publishing: marketplace:admin, admin:write.