hub-seeder is a one-shot command-line tool for bootstrapping preview and test environments of the FLAME Hub (PrivateAIM) — a privacy-preserving analytics infrastructure that runs distributed computations across institutional boundaries without moving the underlying data. It talks to the Hub and Authup APIs to idempotently create nodes and projects, provision a node's OAuth client, generate its key pair, and write the values.yaml / private_key.pem files consumed by the flame-node Helm chart.

It is published both as a library (seedNodeCommand / seedProjectCommand) and as the hub-seeder executable.

Features

• 🌱 Idempotent seeding — every step is "create if missing", so the seeder is safe to re-run against the same environment.
• 🧩 Deferred-failure step runner — runs every step, collects errors with full request/response detail, and reports a complete diagnostic in a single run.
• 🔑 Credential provisioning — generates an ECDH P-256 key pair and rotates the node's Authup OAuth client secret & redirect URI.
• 📄 Chart-ready output — writes values.yaml and private_key.pem for the flame-node Helm chart.
• 📦 Library or CLI — drive it programmatically, from the shell, or as a Docker image.

Quick Start

Prerequisites

• Node.js 22+
• A reachable Hub and Authup instance, plus confidential client credentials (CLIENT_ID / CLIENT_SECRET).

Install

npm install @privateaim/hub-seeder

Or run it ad-hoc, without installing:

npx @privateaim/hub-seeder seed-node --node-name my-node

Commands

All configuration is provided via environment variables (see Configuration); the only CLI flag is --node-name.

| Command | Description | |---------|-------------| | seed-node 🌐 | Provision a node on the Hub and write credential files for the flame-node chart | | seed-project 📁 | Create a project on the Hub (if missing) |

seed-node

Creates the node (if missing), assigns the default registry, generates an ECDH P-256 key pair and sets the node's public key, provisions its Authup OAuth client (secret + redirect URI derived from NODE_URL), optionally assigns it to a project, and — only if every step succeeded — writes values.yaml and private_key.pem to OUTPUT_DIR.

HUB_URL=https://hub.example AUTHUP_URL=https://authup.example \
CLIENT_ID=seeder CLIENT_SECRET=*** \
NODE_TYPE=default NODE_URL=https://my-node.example OUTPUT_DIR=./out \
  hub-seeder seed-node --node-name my-node

seed-project

Creates a project on the Hub (if missing).

HUB_URL=https://hub.example AUTHUP_URL=https://authup.example \
CLIENT_ID=seeder CLIENT_SECRET=*** \
PROJECT_NAME=my-project \
  hub-seeder seed-project

Configuration

| Variable | Used by | Description | |----------|---------|-------------| | HUB_URL | both | Hub API base URL | | AUTHUP_URL | both | Authup API base URL | | REALM | both | Authup realm for the client-credentials token (default master) | | CLIENT_ID | both (required) | Confidential client id used to authenticate | | CLIENT_SECRET | both (required) | Confidential client secret | | NODE_NAME | seed-node | Node name to create/find (overridden by --node-name) | | NODE_TYPE | seed-node | default or aggregator (default default) | | NODE_URL | seed-node | Node base URL; used to derive the OAuth redirect URI (<url>/**) | | OUTPUT_DIR | seed-node | Directory for values.yaml / private_key.pem (default .) | | PROJECT_NAME | seed-project (required), seed-node (optional) | Project to create / to assign the node to | | PROJECT_DISPLAY_NAME | seed-project | Project display name (defaults to PROJECT_NAME) |

[!WARNING] For self-signed preview/test environments the CLI disables TLS certificate verification (NODE_TLS_REJECT_UNAUTHORIZED=0). This is intentional for that use case — do not rely on it in production contexts.

Programmatic Usage

The core commands are decoupled from the CLI and accept typed options:

import { seedNodeCommand, seedProjectCommand } from '@privateaim/hub-seeder';

await seedNodeCommand({ nodeName: 'my-node', outputDir: './out' });

await seedProjectCommand({ projectName: 'my-project' });

Environment variables (HUB_URL, AUTHUP_URL, CLIENT_ID, …) are read the same way as for the CLI.

Docker

The CLI ships as a Docker image with the binary as its entrypoint — append the subcommand and provide the environment:

docker run --env-file .env <image> seed-node

Built With

hub-seeder builds on open-source libraries from the FLAME / PrivateAIM ecosystem: Authup (identity & access), citty (CLI framework), and the @privateaim/* kits (Hub clients, crypto & server utilities).

Contributing

Before starting to work on a pull request, it is important to review the guidelines for contributing and the code of conduct. These guidelines will help to ensure that contributions are made effectively and are accepted.

License

Made with 💚

Published under MIT License.