PolyHub

hub.polycrate.io is the central platform of the Polycrate ecosystem: block marketplace and showroom, CLI download platform and update check server for polycrate update. Describes its features and its use as a DataSource in the Polycrate API.

PolyHub

What is PolyHub?

hub.polycrate.io is the central platform for the Polycrate ecosystem with three core functions:

1. Block marketplace & showroom – browse, discover and inspect Polycrate blocks
2. CLI download platform – provides the Polycrate CLI for all platforms
3. Update check server – automatic version check for polycrate update

Architecture

graph TB
    subgraph "Container Registry (Harbor)"
        Proj1[Project: ayedo/k8s]
        Proj2[Project: ayedo/linux]
        Proj3[Project: library]
    end

    subgraph "PolyHub (Showroom)"
        API[API Server]
        Web[Web Interface]
        CLI_DL[CLI Downloads]
    end

    Proj1 -->|Webhooks| API
    Proj2 -->|Webhooks| API
    Proj3 -->|Scheduled Sync| API
    API --> Web
    API --> CLI_DL

    User[Developer] --> Web
    User --> CLI_DL
    Polycrate[Polycrate CLI] --> API
    Polycrate -->|Pull/Push| Proj1

Hub as a showroom for the registry

Interaction Hub ↔ registry:

How the Hub imports blocks:

1. Registry link: a Hub is connected to exactly one container registry
2. Project import: the Hub can import several repositories (in Harbor: "projects")
3. Webhooks: on push events in the registry the Hub is notified automatically
4. Scheduled sync: in addition, the Hub synchronizes with the registry regularly
5. Block interpretation: the Hub reads the block structure and presents: - Available versions (tags) - block.poly – configuration schema and actions - README.md – documentation - CHANGELOG.poly – change history

Block referencing:

registry.my-org.com / ayedo / k8s / postgres : 1.2.0
└── Registry URL ──┘ └─ Project ─┘ └ Block ┘ └ Tag ┘

If a block name contains no registry URL, Polycrate assumes that the block is local in the blocks/ directory.

Accessing the Hub

Web interface

Visit hub.polycrate.io:

• Block browser – browse all available blocks
• Search – full-text search across blocks, descriptions and tags
• Block details – show versions, README, CHANGELOG and block.poly
• CLI downloads – download the Polycrate CLI for all platforms

CLI with interactive TUI

The polycrate hub list command offers an interactive TUI for browsing:

# Interactive TUI (default)
polycrate hub list

# With pre-filter
polycrate hub list --filter postgres

# Filter by block type
polycrate hub list --kind k8sapp

# Table output without TUI
polycrate hub list --no-tui

TUI navigation:

Action menu after selection:

• view-versions – show all available versions
• view-block – show the block.poly of the latest version
• view-readme – show the README
• copy-name – print the block name for workspace.poly

Inspecting block details

# Block details (block.poly)
polycrate hub inspect infra/postgres

# Show README
polycrate hub inspect infra/postgres --readme

# Show changelog
polycrate hub inspect infra/postgres --changelog

# Specific version
polycrate hub inspect infra/postgres:1.2.0

CLI downloads and updates

The Hub serves as the central download platform for the Polycrate CLI:

# Update to the latest version
polycrate update

# Update to a specific version
polycrate update 0.51.3

# Show available versions
polycrate version --check

The CLI automatically checks for available updates at startup and shows a notification.

→ Installation & updates

Using blocks

Referencing in workspace.poly

name: my-workspace

blocks:
  # Full registry path (REQUIRED for remote blocks)
  - name: my-postgres
    from: registry.my-org.com/infra/postgres:1.2.0
    config:
      namespace: production
      replicas: 3

Using auto-pull

# The block is pulled automatically from the registry if not present locally
polycrate run my-postgres install --blocks-auto-pull

Pulling manually

# Pull the block from the registry
polycrate blocks pull registry.my-org.com/infra/postgres:1.2.0

Block documentation

Every block in the Hub has standardized documentation:

README.md

Contains:

• Block description and features
• Prerequisites
• Installation and usage
• Configuration options
• Examples
• Troubleshooting

CHANGELOG.poly

Versioned change history in YAML format:

- version: "1.2.0"
  date: "2025-01-30"
  type: feat
  message: "Automated backup support"
  description: |
    - Added automated backup support
    - Improved high-availability configuration
    - Fixed connection pooling issues

- version: "1.1.0"
  date: "2025-01-15"
  type: feat
  message: "Monitoring integration"

block.poly

Complete block configuration with:

• All available actions
• Config schema (as example/defaults)
• Dependencies and inheritance

Self-hosting

The PolyHub can be self-hosted for:

• Private blocks – internal blocks for your team
• Air-gapped environments – offline use
• Custom branding – your own look & feel

Architecture

A self-hosted setup consists of two components:

┌─────────────────────────────────────────────────────────┐
│                    Your infrastructure                  │
├─────────────────────────┬───────────────────────────────┤
│   OCI Registry          │   PolyHub (licensed)          │
│   registry.my-org.com   │   hub.my-org.com              │
│                         │                               │
│   • Stores blocks       │   • Showroom for the registry │
│   • OCI artifacts       │   • Web interface             │
│   • Versioning          │   • CLI downloads             │
│   • Access control      │   • Block documentation       │
└─────────────────────────┴───────────────────────────────┘

Prerequisites

• Valid PolyHub license from ayedo
• OCI-compatible registry (Harbor recommended)
• Kubernetes cluster for the Hub deployment
• Webhook configuration between registry and Hub

Deployment

After receiving the license you get access to the polyhub block:

# workspace.poly
blocks:
  - name: polyhub
    from: cargo.ayedo.cloud/ayedo/k8s/polyhub
    config:
      domain: hub.my-org.com
      registry_url: registry.my-org.com
      license_key: "{{ secrets.polyhub_license }}"

→ Registry – details on OCI registries, Harbor setup and air-gapped configuration

Best practices

1. Always use the full registry path

# ✅ Good: full registry path with version
from: registry.my-org.com/infra/postgres:1.2.0

# ❌ Bad: without registry (interpreted as local)
from: postgres:1.2.0

# ❌ Bad: latest (can break unexpectedly)
from: registry.my-org.com/infra/postgres:latest

2. Read the documentation

# Read README and changelog in the Hub before use
polycrate hub inspect infra/postgres --readme
polycrate hub inspect infra/postgres --changelog

3. Test in staging first

Use separate workspaces for staging and production:

~/.polycrate/workspaces/
├── acme-staging-1/    # test new block versions
└── acme-production-1/ # proven versions

4. Check for updates regularly

# Show available versions of a block in the Hub
polycrate hub inspect infra/postgres --versions

# Check the changelog of the new version
polycrate hub inspect infra/postgres:1.3.0 --changelog

PolyHub as a DataSource in the Polycrate API

Since Polycrate API 0.15.0 a PolyHub can be created as a DataSource of kind polycrate-hub in the Polycrate API. This imports template blocks from the Hub into the Polycrate API automatically and proactively – without manual maintenance.

What does the DataSource do?

Setup

Administration → DataSources → New

After saving, Polycrate triggers an initial sync. The status (last sync, number of imported blocks, errors) is visible in the DataSource detail view.

MCP integration for AI assistants

The Hub is accessible to AI assistants via the Polycrate MCP server:

→ MCP Server (CLI) · MCP — Platform API

Relation to other concepts

• Registry: PolyHub synchronizes with OCI registries – technical details on pull/push, authentication and proxying
• Dependencies: use Hub blocks as dependencies
• Inheritance: inherit Hub blocks as base blocks
• Blocks: PolyHub makes blocks discoverable