SyftHub

A registry and discovery platform for AI/ML endpoints with identity provider capabilities.

What is SyftHub?

SyftHub is a platform for discovering, managing, and sharing AI/ML endpoints — think of it as "GitHub for AI endpoints". It enables developers and organizations to:

Discover — Browse and search public ML models and data sources, find trending endpoints by stars
Share — Publish your own endpoints with flexible visibility controls (public, internal, private)
Collaborate — Create organizations to manage endpoints as a team with role-based access
Integrate — Use official Python and TypeScript SDKs for programmatic access
Federate — Built-in Identity Provider (IdP) enables satellite services to verify users via RS256-signed tokens

Core Concepts

Endpoints

Endpoints are the primary resource in SyftHub. Each endpoint represents either:

Type	Description
Model	An ML model endpoint (inference, predictions, embeddings, etc.)
Data Source	A data access endpoint (databases, APIs, datasets, etc.)

Endpoints support:

Visibility: public (anyone), internal (authenticated users), private (owner/members only)
Versioning: Semantic version tracking (e.g., 0.1.0)
README: Markdown documentation with syntax highlighting
Policies: Flexible JSON configuration for access policies
Connections: Multiple connection methods with custom configuration
Stars: Community rating system

Endpoints are accessed via GitHub-style URLs: /{owner}/{endpoint-slug}

Organizations

Organizations enable team collaboration on endpoints:

Role	Permissions
Owner	Full control, can delete organization, manage all members
Admin	Manage endpoints, add/remove members, update settings
Member	Access organization endpoints, basic collaboration

Identity Provider (IdP)

SyftHub acts as an Identity Provider for satellite services:

User authenticates with SyftHub (gets HS256 access token)
User requests a satellite token for a specific service (audience)
Hub issues RS256-signed short-lived token (60 seconds)
Satellite service verifies token using Hub's JWKS endpoint (/.well-known/jwks.json)
No API call to Hub needed for verification — fully distributed

This enables federated authentication across multiple services with a single SyftHub login.

Stars

Users can star endpoints to show appreciation and help surface popular content. The trending page ranks endpoints by star count.

Features

Endpoint Management

Create, update, and delete endpoints with full CRUD support
Auto-generated URL-safe slugs from endpoint names
Markdown README rendering with syntax highlighting
Flexible policy and connection configuration (JSON)
Star/unstar endpoints with trending discovery

Organization Collaboration

Create organizations with unique slugs
Invite members with role-based permissions
Shared endpoint ownership across team members
Protected operations (cannot remove last owner)

Identity Provider

JWKS endpoint for distributed key verification
RS256-signed satellite tokens with audience scoping
Configurable audience allowlist
Server-side token verification endpoint

Authentication & Security

JWT-based authentication (HS256 for hub, RS256 for satellites)
Access + refresh token flow with configurable expiry
Token blacklist for secure logout
Argon2 password hashing
Role-based access control (admin, user, guest)

SDKs

Official Python SDK (syfthub-sdk)
Official TypeScript SDK (@syfthub/sdk)
Full API parity with language-appropriate conventions

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    NGINX (Reverse Proxy)                         │
│                 Port 80/443 (prod) | 8080 (dev)                  │
└─────────────────────┬───────────────────────┬───────────────────┘
                      │                       │
         ┌────────────▼────────────┐  ┌───────▼────────────┐
         │   Frontend (React 19)   │  │  Backend (FastAPI) │
         │   TypeScript + Vite     │  │  Python 3.12       │
         │   Tailwind + shadcn/ui  │  │  SQLAlchemy ORM    │
         └────────────┬────────────┘  └───────┬────────────┘
                      │                       │
                      │    @syfthub/sdk       │
                      └───────────────────────┤
                                              │
                      ┌───────────────────────┴────────────────┐
                      │                                        │
              ┌───────▼───────┐                    ┌───────────▼───────┐
              │  PostgreSQL   │                    │      Redis        │
              │  Database     │                    │  Sessions/Cache   │
              └───────────────┘                    └───────────────────┘

Layer	Technology
Backend	FastAPI + SQLAlchemy + PostgreSQL
Frontend	React 19 + TypeScript + Vite + Tailwind CSS
Package Management	uv (backend) + npm (frontend)
Testing	pytest (backend) + Playwright (frontend)
CI/CD	GitHub Actions with parallel jobs

SDKs

SyftHub provides official SDKs for Python and TypeScript. See the SDK documentation for full details.

Python SDK

pip install syfthub-sdk
# or
uv add syfthub-sdk

from syfthub_sdk import SyftHubClient

client = SyftHubClient(base_url="https://hub.syft.com")

# Authentication
client.auth.login(email="[email protected]", password="secret123")

# Browse public endpoints
for endpoint in client.hub.browse():
    print(f"{endpoint.name}: {endpoint.description}")

# Get trending endpoints
trending = client.hub.trending(min_stars=5)

# Create an endpoint
endpoint = client.my_endpoints.create({
    "name": "My ML Model",
    "type": "model",
    "visibility": "public",
    "description": "A powerful classification model"
})

# Star an endpoint
client.hub.star("alice/awesome-model")

TypeScript SDK

npm install @syfthub/sdk
# or
yarn add @syfthub/sdk

import { SyftHubClient } from '@syfthub/sdk';

const client = new SyftHubClient({ baseUrl: 'https://hub.syft.com' });

// Authentication
await client.auth.login({ email: '[email protected]', password: 'secret123' });

// Browse public endpoints
for await (const endpoint of client.hub.browse()) {
  console.log(`${endpoint.name}: ${endpoint.description}`);
}

// Create an endpoint
const endpoint = await client.myEndpoints.create({
  name: 'My Data Source',
  type: 'data_source',
  visibility: 'private',
  description: 'Internal company data'
});

API Overview

Base URL: /api/v1

Group	Endpoints	Description
Auth	`POST /auth/register` `POST /auth/login` `POST /auth/refresh` `GET /auth/me`	User authentication
Users	`GET /users/me` `PUT /users/me` `GET /users/{id}`	User management
Endpoints	`POST /endpoints` `GET /endpoints` `GET /endpoints/public` `GET /endpoints/trending` `POST /endpoints/{id}/star`	Endpoint CRUD & discovery
Organizations	`POST /organizations` `GET /organizations` `POST /organizations/{id}/members`	Organization management
IdP	`GET /token?aud={service}` `GET /.well-known/jwks.json` `POST /verify`	Identity provider
Public	`GET /{owner}/{slug}`	GitHub-style endpoint access

Full API documentation available at /docs (Swagger UI) when running the server.

Installation

Prerequisites

Docker (recommended) or:
- Backend: Python 3.9+ and uv
- Frontend: Node.js 18+ and npm

Install uv (for local development):

curl -LsSf https://astral.sh/uv/install.sh | sh

Quick Start

Clone the repository:

git clone https://github.com/IonesioJunior/syfthub.git
cd syfthub

Copy environment template:

cp .env.example .env

Start the development environment:

make dev

This starts all services (backend, frontend, PostgreSQL, Redis) via Docker.

Usage

Development Mode (Docker - Recommended)

Start the full-stack environment with one command:

make dev      # Start all services
make logs     # View container logs
make stop     # Stop all services

The application will be available at:

App: http://localhost
API Documentation: http://localhost/docs
Database: PostgreSQL on localhost:5432 (user: syfthub, password: syfthub_dev_password)

Local Development (Without Docker)

For backend-only local development:

cd backend
uv sync --all-extras --dev
uv run uvicorn syfthub.main:app --reload --port 8000

For frontend-only local development:

cd frontend
npm install
npm run dev

Production Mode

docker compose -f docker-compose.prod.yml up -d

Development

Running Tests

make test     # Run all tests (backend + frontend)

Or run separately:

# Backend tests
cd backend && uv run python -m pytest

# Frontend tests (Playwright E2E)
cd frontend && npm test

Code Quality

make check    # Run all code quality checks

This runs:

Backend: Ruff linting, Ruff formatting, mypy type checking
Frontend: ESLint, TypeScript type checking

Manual Quality Commands

Backend:

cd backend
uv run ruff check src/ tests/       # Linting
uv run ruff format src/ tests/      # Formatting
uv run mypy src/                    # Type checking

Frontend:

cd frontend
npm run lint                        # ESLint
npm run format                      # Prettier
npm run typecheck                   # TypeScript

Available Make Commands

make help     # Show available commands
make dev      # Start development environment
make stop     # Stop all services
make test     # Run all tests
make check    # Run code quality checks
make logs     # View container logs

Project Structure

syfthub/
├── backend/                  # Python FastAPI backend
│   ├── src/syfthub/          # Main Python package
│   │   ├── api/              # FastAPI routes & endpoints
│   │   │   └── endpoints/    # Route handlers (users, endpoints, orgs, tokens)
│   │   ├── auth/             # Authentication & security
│   │   │   ├── security.py   # JWT tokens, password hashing
│   │   │   ├── keys.py       # RSA key management for IdP
│   │   │   └── satellite_tokens.py  # Satellite token logic
│   │   ├── core/             # Configuration
│   │   ├── database/         # Database connection & dependencies
│   │   ├── domain/           # Value objects & exceptions
│   │   ├── models/           # SQLAlchemy ORM models
│   │   ├── repositories/     # Data access layer (Repository pattern)
│   │   ├── schemas/          # Pydantic request/response DTOs
│   │   ├── services/         # Business logic layer
│   │   ├── templates/        # Jinja2 templates (endpoint HTML views)
│   │   └── main.py           # FastAPI app entry point
│   ├── tests/                # Backend test suite
│   ├── scripts/              # Utility scripts
│   ├── pyproject.toml        # Dependencies & tool config
│   └── uv.lock               # Locked Python dependencies
├── frontend/                 # React TypeScript frontend
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── ui/           # shadcn/ui base components
│   │   │   ├── auth/         # Authentication (login, register modals)
│   │   │   ├── settings/     # Settings tabs (profile, security, etc.)
│   │   │   └── chat/         # Chat interface components
│   │   ├── context/          # React Context providers (auth, modals)
│   │   ├── hooks/            # Custom hooks (useAPI, useForm)
│   │   ├── lib/              # Utilities, SDK client, types
│   │   ├── layouts/          # Layout components
│   │   ├── pages/            # Route pages (lazy-loaded)
│   │   ├── assets/           # Static assets (fonts, images)
│   │   ├── styles/           # Global CSS & design tokens
│   │   ├── app.tsx           # App root with routing
│   │   └── main.tsx          # React entry point
│   ├── __tests__/            # Playwright E2E tests
│   ├── package.json          # Frontend dependencies
│   └── vite.config.ts        # Vite build configuration
├── sdk/                      # Official client SDKs
│   ├── python/               # Python SDK (syfthub-sdk)
│   │   ├── src/syfthub_sdk/  # SDK source code
│   │   ├── tests/            # SDK tests
│   │   └── pyproject.toml    # SDK dependencies
│   ├── typescript/           # TypeScript SDK (@syfthub/sdk)
│   │   ├── src/              # SDK source code
│   │   ├── dist/             # Built output
│   │   └── package.json      # SDK dependencies
│   └── README.md             # SDK documentation
├── nginx/                    # Nginx reverse proxy config
│   ├── nginx.dev.conf        # Development configuration
│   └── nginx.prod.conf       # Production configuration (SSL)
├── docs/                     # Documentation
│   ├── authentication.md     # Auth system documentation
│   └── pki-workflow.md       # PKI/IdP workflow documentation
├── docker-compose.dev.yml    # Development environment
├── docker-compose.prod.yml   # Production environment
├── .github/workflows/        # CI/CD pipelines
├── Makefile                  # Development commands
├── .pre-commit-config.yaml   # Code quality hooks
├── .env.example              # Environment template
└── README.md                 # This file

Authentication

SyftHub uses a dual-token authentication system:

Hub Tokens (HS256)

Standard JWT access + refresh tokens
Access tokens expire in 30 minutes (configurable)
Refresh tokens expire in 7 days (configurable)
Token blacklist for secure logout

Satellite Tokens (RS256)

Short-lived tokens for external services (60 seconds)
Signed with RSA private key
Services verify using JWKS endpoint without calling Hub API
Audience-scoped for specific services

For detailed authentication documentation, see docs/authentication.md.

For PKI and IdP workflow details, see docs/pki-workflow.md.

Environment Variables

Key environment variables (see .env.example for full list):

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	Required
`SECRET_KEY`	JWT signing secret (HS256)	Required
`CORS_ORIGINS`	Allowed CORS origins	`*`
`ACCESS_TOKEN_EXPIRE_MINUTES`	Access token lifetime	`30`
`REFRESH_TOKEN_EXPIRE_DAYS`	Refresh token lifetime	`7`
`ALLOWED_AUDIENCES`	Comma-separated satellite service names	`syftai-space`
`AUTO_GENERATE_RSA_KEYS`	Auto-generate RSA keys in dev	`true`

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.github/workflows		.github/workflows
aggregator		aggregator
backend		backend
docs		docs
frontend		frontend
mcp		mcp
nginx		nginx
scripts		scripts
sdk		sdk
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.deploy.example		.env.deploy.example
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.deploy.yml		docker-compose.deploy.yml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml

Uh oh!

License

OpenMined/syfthub

Folders and files

Latest commit

History

Repository files navigation

SyftHub

What is SyftHub?

Core Concepts

Endpoints

Organizations

Identity Provider (IdP)

Stars

Features

Endpoint Management

Organization Collaboration

Identity Provider

Authentication & Security

SDKs

Architecture

SDKs

Python SDK

TypeScript SDK

API Overview

Installation

Prerequisites

Quick Start

Usage

Development Mode (Docker - Recommended)

Local Development (Without Docker)

Production Mode

Development

Running Tests

Code Quality

Manual Quality Commands

Available Make Commands

Project Structure

Authentication

Hub Tokens (HS256)

Satellite Tokens (RS256)

Environment Variables

Contributing

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Languages

Packages