README
¶
Nucleus Package Manager (nuc)
What is Nucleus?
Nucleus is not a traditional package manager like APT or Pacman. It's a decentralized P2P network where every user is both a consumer and a provider.
The Core Idea
"If one person compiled it, nobody else should have to."
When you install a package with nuc:
- It first searches the P2P network for a pre-compiled binary
- If found → downloads it instantly from another user
- If not found → compiles from source and becomes the first seed
You never need to configure anything. Install nuc and you automatically join the network, share binaries, and help others.
Architecture
All nucleus data lives in a single XDG-compliant directory:
~/.config/nucleus/
├── bin/ ← Installed binaries (auto-added to PATH)
├── storage/ ← P2P cache (downloaded & built binaries)
│ ├── <hash>/ ← Per-package binary storage for seeding
│ ├── downloads/ ← Temporary P2P downloads
│ └── builds/ ← Temporary build outputs
├── recipes/ ← Cached package recipes
├── keys/ ← ECDSA signing keys
└── nuc.db ← SQLite database (installed packages, hashes)
How it works:
- Binaries go to
~/.config/nucleus/bin/— no/usr/local/binpollution - The installer adds
~/.config/nucleus/bin/to your shell's PATH nuc installcompiles/downloads → copies tobin/andstorage/→ donenuc removedeletes frombin/— clean, no leftover copiesnuc daemonscans bothstorage/andbin/and announces available binaries to the P2P network
sudo is only needed for the initial sudo cp nuc /usr/local/bin/nuc. Installing and removing packages does not require root.
How the P2P Network Works
┌─────────────────────────────────────────────────────────────┐
│ nuc install fastfetch │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Resolve → Argon2id hash of "fastfetch" │
│ 2. Check SQLite → Already installed? ✅ Done │
│ 3. Query P2P DHT → "Who has this binary?" │
│ ┌────────────────────────────┬─────────────────────────┐ │
│ │ FOUND: Another user has it │ NOT FOUND: Nobody has it│ │
│ │ │ │ │
│ │ Download binary → Install │ Download source → Build │ │
│ │ Verify integrity → Install │ Install → Become seed │ │
│ │ Done in seconds │ Announce to network │ │
│ └────────────────────────────┴─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Every Installation Is a Server
When you install nuc, a background daemon starts automatically. It:
- Announces your available binaries to the network
- Serves binaries to other users
- Reconnects automatically when your machine boots
- Runs silently with no user interaction needed
Quick Start
Prerequisites
- Go 1.24+
- GCC (required for SQLite)
- Linux (primary target)
Install dependencies:
# Arch Linux
sudo pacman -S go gcc make cmake pkgconf
# Debian/Ubuntu
sudo apt install golang gcc make cmake pkg-config
# Fedora
sudo dnf install golang gcc make cmake pkgconf
These dependencies are required. Without Go and GCC the project will not compile.
Install Nucleus
# 1. Clone and build
git clone https://github.com/soylizardev/nucleus.git
cd ~/nucleus
CGO_ENABLED=1 go build -o nuc cmd/nuc/main.go
# 2. Install the binary
sudo cp nuc /usr/local/bin/nuc
sudo chmod 755 /usr/local/bin/nuc
# 3. Create nucleus directories
mkdir -p ~/.config/nucleus/bin ~/.config/nucleus/storage ~/.config/nucleus/recipes ~/.config/nucleus/keys
# 4. Add to PATH
echo 'export PATH="$HOME/.config/nucleus/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Verify Installation
nuc --help
nuc health
Usage
Install a Package
# Downloads from P2P if available, otherwise builds from source
nuc install fastfetch
# Also works with .nuc extension (stripped automatically)
nuc install fastfetch.nuc
The binary is installed to ~/.config/nucleus/bin/fastfetch — immediately available in your PATH. After installation, the P2P daemon is automatically started (if not already running) to begin seeding the binary.
Remove a Package
nuc remove fastfetch
Deletes the binary from ~/.config/nucleus/bin/ and removes it from the database. Clean, no leftovers.
Uninstall Nucleus
Remove Nucleus completely from your system:
nuc uninstall nuc
This removes everything: ~/.config/nucleus/ (all data), /usr/local/bin/nuc, the systemd service, and PATH entries from your shell configs. Add --force to skip confirmation.
Upload a Binary to the Network
Share any binary so others can download it:
# Upload from a specific path
nuc upload /path/to/my-binary
# Upload from current directory
nuc upload ./my-binary
# Search common paths automatically (~/.config/nucleus/bin, /usr/local/bin, /usr/bin, etc.)
nuc upload my-binary
# With custom name and version
nuc upload /usr/bin/my-tool my-tool 2.0.0
When you upload:
- The binary is copied to
~/.config/nucleus/storage/<hash>/ - It's announced to the P2P network via the DHT
- Other users can now
nuc install <name>and get it from you
Search Available Packages
nuc search
List Installed Packages
nuc list
Run Daemon Manually
# Interactive (shows logs)
nuc daemon
# Background (silent, for systemd)
nuc daemon --background
Manage Daemon Service
# Install systemd service (auto-starts on boot)
nuc daemon install
# Uninstall daemon service
nuc daemon uninstall
# Check daemon service status
nuc daemon status
The nuc daemon install command:
- Creates
~/.config/systemd/user/nuc-daemon.service - Reloads systemd and enables the service
- Starts the daemon immediately
- The daemon restarts automatically after reboots
Check Network Status
nuc peers # Show connected peers
nuc health # Node health status
Manage Signing Keys
nuc keygen # Generate ECDSA key pair
nuc sign /path/to/binary # Sign a binary
nuc verify /path/to/binary <sig> # Verify a signature
Firewall and Network Configuration
The P2P daemon listens on port 9000/TCP. For other users to download binaries from you, this port must be accessible.
Check if Your Port is Open
nuc health # Check connectivity and peer count
nuc peers # See connected peers
Open the Port
With ufw (Ubuntu/Debian):
sudo ufw allow 9000/tcp
With iptables:
sudo iptables -A INPUT -p tcp --dport 9000 -j ACCEPT
With firewalld (Fedora):
sudo firewall-cmd --add-port=9000/tcp --permanent
sudo firewall-cmd --reload
Behind NAT / Router
If you're behind a router, you need to forward port 9000/TCP to your machine's local IP. Check your router's admin panel for "Port Forwarding" settings.
Note: UPnP/NAT-PMP automatic port forwarding is planned for a future release.
Writing Recipes
A .nuc recipe is a TOML manifest that tells nuc how to build a package:
name = "my-package"
version = "1.0.0"
source_url = "https://example.com/my-package-1.0.0.tar.gz"
argon2_id = ""
system_deps = ["cmake", "gcc", "pkg-config", "libpci", "vulkan-headers"]
[build]
env = ["CFLAGS=-O2 -static"]
steps = [
"./configure --prefix=/usr",
"make -j$(nproc)",
"make install DESTDIR=$NUC_ROOT"
]
The system_deps field lists packages that must be present on the system before building. nuc will check for each dependency using pkg-config and which, and fail with a clear message if any are missing.
To add a package:
- Create a
.nucfile inregistry/packages/ - Submit a Pull Request
Project Structure
nucleus/
├── cmd/
│ ├── nuc/main.go # CLI binary (install, remove, upload, daemon...)
│ └── seed/main.go # Standalone seed/bootstrap node
├── pkg/
│ ├── crypto/ # Argon2id hashing + ECDSA signing
│ ├── parser/ # TOML recipe parser
│ ├── db/ # SQLite store (installed packages + cache)
│ ├── build/ # Build orchestrator (download → compile)
│ └── network/ # libp2p: DHT, GossipSub, binary registry, transfer
├── registry/packages/ # Package recipes (source of truth)
├── scripts/
│ ├── install # Entry point (runs install.sh)
│ ├── install.sh # Installer (handles all shells' PATH config)
│ ├── nuc.service # systemd service template
│ ├── demo.sh # Local P2P demo with 2 nodes
│ ├── deploy-seed.sh # Deploy seed node to a VPS
│ └── release.sh # Release automation
├── Makefile # Build commands
└── go.mod # Go module definition
Technology Stack
| Component | Technology | Why |
|---|---|---|
| Core Language | Go | Native concurrency, static binaries, efficient GC |
| P2P Network | libp2p | DHT (Kademlia), GossipSub, BitSwap, NAT traversal |
| Database | SQLite | Embedded, zero-config, local state |
| Hashing | Argon2id | Deterministic package identity, anti-fraud |
| Signatures | ECDSA (P-256) | Package integrity verification |
| Recipes | TOML | Human-readable, easy to parse |
Security
- Deterministic Hashing: Argon2id ensures consistent package identity
- Consensus Verification: Multiple peers must agree on binary checksums
- Integrity Checks: SHA-256 verified after every download and build
- ECDSA Signatures: Optional cryptographic signing
- Isolated Builds: Clean environment before compilation for reproducibility
Contributing
- Fork the repository
- Create a branch (
git checkout -b feature/my-feature) - Make changes and write tests
- Run tests (
make test) - Commit and push
- Open a Pull Request
Development Commands
make build # Build the CLI
make test # Run all tests
make test-coverage # Tests with coverage report
make static # Build statically linked binary
make cross # Cross-platform builds
make clean # Remove build artifacts
make install # Build + install to /usr/local/bin
Roadmap
- Phase 1: Core engine, Argon2id, recipe parser, SQLite
- Phase 2: Build orchestrator with isolated environments
- Phase 3: P2P network (libp2p, DHT, GossipSub, binary transfer)
- Phase 4: Full integration (P2P → build → notify → seed)
- Phase 5: Consensus verification, ECDSA signing, health monitoring
- Phase 6: Binary registry, DHT announcements,
nuc upload - Phase 7: Silent background daemon with systemd auto-start
- Phase 8: XDG-compliant storage (
~/.config/nucleus/) - Phase 8.1: Daemon scans both
bin/andstorage/directories - Phase 8.2: System dependency verification before builds (
system_deps) - Phase 8.3: Daemon service management (
nuc daemon install/uninstall/status) - Phase 8.4: Auto-start daemon after package installation
- Phase 9: BitSwap chunked transfer for large binaries
- Phase 10: Chroot/namespace isolation for builds
- Phase 11: UPnP/NAT-PMP automatic port forwarding
- Phase 12: Community registry website
License
MIT License. See LICENSE for details.
Links
- Repository: https://github.com/soylizardev/nucleus
- Issues: https://github.com/soylizardev/nucleus/issues
- Registry: https://github.com/soylizardev/nucleus/tree/master/registry/packages
Español
Un gestor de paquetes descentralizado P2P híbrido fuente/binario
¿Qué es Nucleus?
Nucleus no es un gestor de paquetes tradicional como APT o Pacman. Es una red P2P descentralizada donde cada usuario es consumidor y proveedor al mismo tiempo.
La Idea Central
"Si uno lo compiló, nadie más debería tener que hacerlo."
Cuando instalas un paquete con nuc:
- Primero busca en la red P2P un binario pre-compilado
- Si lo encuentra → lo descarga al instante de otro usuario
- Si no → compila desde fuente y se vuelve la primera semilla
No necesitas configurar nada. Instala nuc y automáticamente te unes a la red, compartes binarios y ayudas a otros.
Arquitectura
Todos los datos de nucleus viven en un solo directorio XDG-compliant:
~/.config/nucleus/
├── bin/ ← Binarios instalados (auto-agregado al PATH)
├── storage/ ← Caché P2P (binarios descargados y compilados)
│ ├── <hash>/ ← Almacenamiento por paquete para seeding
│ ├── downloads/ ← Descargas P2P temporales
│ └── builds/ ← Outputs de build temporales
├── recipes/ ← Recetas cacheadas
├── keys/ ← Claves de firmado ECDSA
└── nuc.db ← Base de datos SQLite (paquetes instalados, hashes)
Cómo funciona:
- Los binarios van a
~/.config/nucleus/bin/— no ensucia/usr/local/bin - El instalador agrega
~/.config/nucleus/bin/al PATH de tu shell nuc installcompila/descarga → copia abin/ystorage/→ listonuc removeelimina debin/— limpio, sin copias residualesnuc daemonescaneastorage/ybin/y anuncia binarios disponibles a la red P2P
sudo solo se necesita para el sudo cp nuc /usr/local/bin/nuc inicial. Instalar y eliminar paquetes no requiere root.
Cómo Funciona la Red P2P
┌─────────────────────────────────────────────────────────────┐
│ nuc install fastfetch │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Resolver → hash Argon2id de "fastfetch" │
│ 2. Verificar SQLite → ¿Ya instalado? ✅ Listo │
│ 3. Consultar DHT P2P → "¿Quién tiene este binario?" │
│ ┌────────────────────────────┬─────────────────────────┐ │
│ │ ENCONTRADO: Otro usuario │ NO ENCONTRADO: Nadie │ │
│ │ lo tiene │ lo tiene │ │
│ │ │ │ │
│ │ Descargar → Instalar │ Descargar fuente → Build│ │
│ │ Verificar → Listo │ Instalar → Ser seed │ │
│ │ En segundos │ Anunciar a la red │ │
│ └────────────────────────────┴─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Cada Instalación Es un Servidor
Cuando instalas nuc, un daemon en segundo plano se inicia automáticamente. Este:
- Anuncia tus binarios disponibles a la red
- Sirve binarios a otros usuarios
- Se reconecta automáticamente al encender tu máquina
- Funciona en silencio, sin interacción del usuario
Inicio Rápido
Requisitos
- Go 1.24+
- GCC (requerido para SQLite)
- Linux (objetivo principal)
Instalar dependencias:
# Arch Linux
sudo pacman -S go gcc make cmake pkgconf
# Debian/Ubuntu
sudo apt install golang gcc make cmake pkg-config
# Fedora
sudo dnf install golang gcc make cmake pkgconf
Estas dependencias son requeridas. Sin Go y GCC el proyecto no compilará.
Instalar Nucleus
# 1. Clonar y compilar
git clone https://github.com/soylizardev/nucleus.git
cd ~/nucleus
CGO_ENABLED=1 go build -o nuc cmd/nuc/main.go
# 2. Instalar el binario
sudo cp nuc /usr/local/bin/nuc
sudo chmod 755 /usr/local/bin/nuc
# 3. Crear directorios de nucleus
mkdir -p ~/.config/nucleus/bin ~/.config/nucleus/storage ~/.config/nucleus/recipes ~/.config/nucleus/keys
# 4. Agregar al PATH
echo 'export PATH="$HOME/.config/nucleus/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Verificar Instalación
nuc --help
nuc health
Uso
Instalar un Paquete
# Descarga de P2P si está disponible, si no compila desde fuente
nuc install fastfetch
# También funciona con extensión .nuc (se quita automáticamente)
nuc install fastfetch.nuc
El binario se instala en ~/.config/nucleus/bin/fastfetch — disponible inmediatamente en tu PATH. Tras la instalación, el daemon P2P se inicia automáticamente (si no está corriendo) para comenzar a compartir el binario.
Eliminar un Paquete
nuc remove fastfetch
Elimina el binario de ~/.config/nucleus/bin/ y lo remueve de la base de datos. Limpio, sin residuos.
Desinstalar Nucleus
Elimina Nucleus completamente de tu sistema:
nuc uninstall nuc
Esto elimina todo: ~/.config/nucleus/ (todos los datos), /usr/local/bin/nuc, el servicio systemd y las entradas de PATH de tus archivos de configuración del shell. Agrega --force para omitir la confirmación.
Subir un Binario a la Red
Comparte cualquier binario para que otros lo descarguen:
# Subir desde una ruta específica
nuc upload /ruta/a/mi-binario
# Subir desde el directorio actual
nuc upload ./mi-binario
# Buscar automáticamente en rutas comunes (~/.config/nucleus/bin, /usr/local/bin, /usr/bin, etc.)
nuc upload mi-binario
# Con nombre y versión personalizados
nuc upload /usr/bin/mi-herramienta mi-herramienta 2.0.0
Cuando subes:
- El binario se copia a
~/.config/nucleus/storage/<hash>/ - Se anuncia a la red P2P vía DHT
- Otros usuarios pueden hacer
nuc install <nombre>y obtenerlo de ti
Buscar Paquetes Disponibles
nuc search
Listar Paquetes Instalados
nuc list
Ejecutar Daemon Manualmente
# Interactivo (muestra logs)
nuc daemon
# Segundo plano (silencioso, para systemd)
nuc daemon --background
Gestionar Servicio Daemon
# Instalar servicio systemd (auto-inicio al arrancar)
nuc daemon install
# Desinstalar servicio daemon
nuc daemon uninstall
# Ver estado del servicio daemon
nuc daemon status
El comando nuc daemon install:
- Crea
~/.config/systemd/user/nuc-daemon.service - Recarga systemd y activa el servicio
- Inicia el daemon inmediatamente
- El daemon se reinicia automáticamente tras reinicios
Configuración de Firewall y Red
El daemon P2P escucha en el puerto 9000/TCP. Para que otros usuarios descarguen binarios de tu máquina, este puerto debe ser accesible.
Verificar si tu Puerto está Abierto
nuc health # Verificar conectividad y cantidad de peers
nuc peers # Ver peers conectados
Abrir el Puerto
Con ufw (Ubuntu/Debian):
sudo ufw allow 9000/tcp
Con iptables:
sudo iptables -A INPUT -p tcp --dport 9000 -j ACCEPT
Con firewalld (Fedora):
sudo firewall-cmd --add-port=9000/tcp --permanent
sudo firewall-cmd --reload
Detrás de NAT / Router
Si estás detrás de un router, necesitas reenviar el puerto 9000/TCP a la IP local de tu máquina. Revisa el panel de administración de tu router en "Port Forwarding".
Nota: El reenvío automático de puertos UPnP/NAT-PMP está planeado para una versión futura.
Escribir Recetas
Una receta .nuc es un manifiesto TOML que le dice a nuc cómo compilar:
name = "mi-paquete"
version = "1.0.0"
source_url = "https://example.com/mi-paquete-1.0.0.tar.gz"
argon2_id = ""
system_deps = ["cmake", "gcc", "pkg-config", "libpci", "vulkan-headers"]
[build]
env = ["CFLAGS=-O2 -static"]
steps = [
"./configure --prefix=/usr",
"make -j$(nproc)",
"make install DESTDIR=$NUC_ROOT"
]
El campo system_deps lista los paquetes que deben estar presentes en el sistema antes de compilar. nuc verificará cada dependencia usando pkg-config y which, y fallará con un mensaje claro si alguna falta.
Para agregar un paquete:
- Crea un archivo
.nucenregistry/packages/ - Envía un Pull Request
Estructura del Proyecto
nucleus/
├── cmd/
│ ├── nuc/main.go # CLI (install, remove, upload, daemon...)
│ └── seed/main.go # Nodo seed/bootstrap independiente
├── pkg/
│ ├── crypto/ # Hashing Argon2id + firma ECDSA
│ ├── parser/ # Parser de recetas TOML
│ ├── db/ # Store SQLite (paquetes + caché)
│ ├── build/ # Build orchestrator (descarga → compila)
│ └── network/ # libp2p: DHT, GossipSub, registry, transferencia
├── registry/packages/ # Recetas de paquetes (fuente de verdad)
├── scripts/
│ ├── install # Entry point (ejecuta install.sh)
│ ├── install.sh # Instalador (configura PATH para todos los shells)
│ ├── nuc.service # Plantilla de servicio systemd
│ ├── demo.sh # Demo P2P local con 2 nodos
│ ├── deploy-seed.sh # Deploy de seed node a un VPS
│ └── release.sh # Automatización de releases
├── Makefile # Comandos de build
└── go.mod # Definición del módulo Go
Stack Tecnológico
| Componente | Tecnología | Por qué |
|---|---|---|
| Lenguaje | Go | Concurrencia nativa, binarios estáticos, GC eficiente |
| Red P2P | libp2p | DHT (Kademlia), GossipSub, BitSwap, NAT traversal |
| Base de Datos | SQLite | Embebida, sin configuración, estado local |
| Hashing | Argon2id | Identidad determinista, anti-fraude |
| Firmas | ECDSA (P-256) | Verificación de integridad |
| Recetas | TOML | Legible, fácil de parsear |
Seguridad
- Hashing Determinista: Argon2id asegura identidad consistente
- Verificación de Consenso: Múltiples peers deben coincidir en checksums
- Checks de Integridad: SHA-256 verificado tras cada descarga y build
- Firmas ECDSA: Firma criptográfica opcional
- Builds Aislados: Variables de entorno limpias antes de compilar
Contribuir
- Haz un fork del repositorio
- Crea una rama (
git checkout -b feature/mi-feature) - Haz cambios y escribe tests
- Ejecuta tests (
make test) - Commitea y haz push
- Abre un Pull Request
Comandos de Desarrollo
make build # Compilar el CLI
make test # Ejecutar todos los tests
make test-coverage # Tests con reporte de cobertura
make static # Compilar binario estático
make cross # Builds multi-plataforma
make clean # Limpiar artefactos
make install # Compilar + instalar en /usr/local/bin
Roadmap
- Fase 1: Motor core, Argon2id, parser de recetas, SQLite
- Fase 2: Build orchestrator con entornos aislados
- Fase 3: Red P2P (libp2p, DHT, GossipSub, transferencia)
- Fase 4: Integración completa (P2P → build → notify → seed)
- Fase 5: Consenso, firmas ECDSA, health monitoring
- Fase 6: Registro de binarios, anuncios DHT,
nuc upload - Fase 7: Daemon silencioso con auto-start systemd
- Fase 8: Almacenamiento XDG (
~/.config/nucleus/) - Fase 8.1: Daemon escanea directorios
bin/ystorage/ - Fase 8.2: Verificación de dependencias del sistema (
system_deps) - Fase 8.3: Gestión de servicio daemon (
nuc daemon install/uninstall/status) - Fase 8.4: Auto-inicio del daemon tras instalar un paquete
- Fase 9: BitSwap para transferencia por fragmentos
- Fase 10: Aislamiento chroot/namespaces para builds
- Fase 11: Reenvío automático de puertos UPnP/NAT-PMP
- Fase 12: Website del registro de paquetes
Licencia
Licencia MIT. Ver LICENSE para detalles.
Directories