958 lines
19 KiB
Markdown
958 lines
19 KiB
Markdown
# Nippels User Guide
|
|
|
|
**Complete guide to using Nippels (NimPak Cells) for application isolation**
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Introduction](#introduction)
|
|
2. [Quick Start](#quick-start)
|
|
3. [CLI Commands Reference](#cli-commands-reference)
|
|
4. [Security Profiles](#security-profiles)
|
|
5. [Isolation Levels](#isolation-levels)
|
|
6. [Common Use Cases](#common-use-cases)
|
|
7. [Troubleshooting](#troubleshooting)
|
|
8. [Advanced Topics](#advanced-topics)
|
|
|
|
---
|
|
|
|
## Introduction
|
|
|
|
**Nippels (NimPak Cells)** are lightweight, namespace-based application isolation environments. They provide:
|
|
|
|
- ⚡ **Lightning-fast startup** (< 50ms overhead)
|
|
- 🔒 **Strong isolation** (Linux kernel namespaces)
|
|
- 🎨 **Perfect desktop integration** (native themes, fonts, clipboard)
|
|
- 💾 **Efficient storage** (content-addressable deduplication)
|
|
- 🔄 **Reproducibility** (merkle tree verification)
|
|
- 🤖 **AI-addressability** (UTCP protocol)
|
|
|
|
### When to Use Nippels
|
|
|
|
✅ **Perfect for:**
|
|
- Isolating web browsers (work vs personal)
|
|
- Gaming environments
|
|
- Development environments
|
|
- Untrusted applications
|
|
- Security-sensitive apps
|
|
|
|
❌ **Not ideal for:**
|
|
- System utilities (use regular nip packages)
|
|
- Command-line tools (use user environments)
|
|
- Server software (use Nexus Capsules)
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Creating Your First Nippel
|
|
|
|
```bash
|
|
# Create a Nippel with default settings
|
|
nip cell create my-browser
|
|
|
|
# Install Firefox into the Nippel
|
|
nip install --cell=my-browser firefox
|
|
|
|
# Activate the Nippel
|
|
nip cell activate my-browser
|
|
|
|
# Run Firefox (now isolated)
|
|
firefox
|
|
```
|
|
|
|
### Creating with a Security Profile
|
|
|
|
```bash
|
|
# Create with Workstation profile (balanced)
|
|
nip cell create work-browser --profile=workstation
|
|
|
|
# Create with Satellite profile (maximum portability)
|
|
nip cell create portable-browser --profile=satellite
|
|
|
|
# Create with Server profile (minimal desktop integration)
|
|
nip cell create headless-app --profile=server
|
|
```
|
|
|
|
### Listing and Managing Nippels
|
|
|
|
```bash
|
|
# List all Nippels
|
|
nip cell list
|
|
|
|
# Show Nippel details
|
|
nip cell show my-browser
|
|
|
|
# Remove a Nippel
|
|
nip cell remove my-browser
|
|
|
|
# Deactivate current Nippel
|
|
nip cell deactivate
|
|
```
|
|
|
|
---
|
|
|
|
## CLI Commands Reference
|
|
|
|
### Core Commands
|
|
|
|
#### `nip cell create <name> [options]`
|
|
|
|
Create a new Nippel.
|
|
|
|
**Options:**
|
|
- `--profile=<profile>` - Security profile (workstation, homestation, satellite, networkiot, server)
|
|
- `--isolation=<level>` - Isolation level (none, standard, strict, quantum)
|
|
- `--customize=<overrides>` - Custom profile overrides (JSON format)
|
|
- `--network=<mode>` - Network access (full, limited, none)
|
|
- `--filesystem=<mode>` - Filesystem access (full, home, limited, none)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Basic creation
|
|
nip cell create firefox-isolated
|
|
|
|
# With specific profile
|
|
nip cell create banking --profile=satellite --isolation=strict
|
|
|
|
# With custom settings
|
|
nip cell create dev-env --customize='{"desktopIntegration":true,"networkAccess":"full"}'
|
|
|
|
# With network restrictions
|
|
nip cell create untrusted --network=none --filesystem=none
|
|
```
|
|
|
|
#### `nip cell activate <name>`
|
|
|
|
Activate a Nippel for the current session.
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Activate Nippel
|
|
nip cell activate firefox-isolated
|
|
|
|
# Check active Nippel
|
|
nip cell status
|
|
|
|
# Deactivate
|
|
nip cell deactivate
|
|
```
|
|
|
|
#### `nip cell list [options]`
|
|
|
|
List all Nippels.
|
|
|
|
**Options:**
|
|
- `--active` - Show only active Nippels
|
|
- `--profile=<profile>` - Filter by profile
|
|
- `--format=<format>` - Output format (table, json, yaml)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# List all Nippels
|
|
nip cell list
|
|
|
|
# List active Nippels only
|
|
nip cell list --active
|
|
|
|
# List with specific profile
|
|
nip cell list --profile=satellite
|
|
|
|
# JSON output
|
|
nip cell list --format=json
|
|
```
|
|
|
|
#### `nip cell show <name>`
|
|
|
|
Show detailed information about a Nippel.
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Show Nippel details
|
|
nip cell show firefox-isolated
|
|
|
|
# Show with merkle tree info
|
|
nip cell show firefox-isolated --merkle
|
|
|
|
# Show with UTCP address
|
|
nip cell show firefox-isolated --utcp
|
|
```
|
|
|
|
#### `nip cell remove <name> [options]`
|
|
|
|
Remove a Nippel.
|
|
|
|
**Options:**
|
|
- `--purge` - Also remove user data
|
|
- `--force` - Force removal even if active
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Remove Nippel (keep user data)
|
|
nip cell remove firefox-isolated
|
|
|
|
# Remove with user data
|
|
nip cell remove firefox-isolated --purge
|
|
|
|
# Force removal
|
|
nip cell remove firefox-isolated --force
|
|
```
|
|
|
|
### Profile Management
|
|
|
|
#### `nip cell profile list`
|
|
|
|
List available security profiles.
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell profile list
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
Available Security Profiles:
|
|
- workstation: Balanced security and usability (default)
|
|
- homestation: Maximum desktop integration
|
|
- satellite: Maximum portability
|
|
- networkiot: Minimal resources, network-focused
|
|
- server: Minimal desktop integration
|
|
```
|
|
|
|
#### `nip cell profile show <name>`
|
|
|
|
Show current profile of a Nippel.
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell profile show firefox-isolated
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
Nippel: firefox-isolated
|
|
Profile: workstation
|
|
Isolation Level: standard
|
|
Desktop Integration: enabled
|
|
Network Access: full
|
|
Resource Limits: moderate
|
|
```
|
|
|
|
#### `nip cell profile set <name> <profile>`
|
|
|
|
Change the security profile of a Nippel.
|
|
|
|
**Example:**
|
|
```bash
|
|
# Change to stricter profile
|
|
nip cell profile set firefox-isolated satellite
|
|
|
|
# Verify change
|
|
nip cell profile show firefox-isolated
|
|
```
|
|
|
|
### Verification Commands
|
|
|
|
#### `nip cell verify <name> [options]`
|
|
|
|
Verify Nippel integrity using merkle tree.
|
|
|
|
**Options:**
|
|
- `--fix` - Attempt to fix integrity issues
|
|
- `--verbose` - Show detailed verification results
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Verify Nippel integrity
|
|
nip cell verify firefox-isolated
|
|
|
|
# Verify with detailed output
|
|
nip cell verify firefox-isolated --verbose
|
|
|
|
# Verify and fix issues
|
|
nip cell verify firefox-isolated --fix
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
Verifying Nippel: firefox-isolated
|
|
Merkle Root: xxh3-abc123def456...
|
|
Files Checked: 1,234
|
|
Status: ✅ VERIFIED
|
|
```
|
|
|
|
#### `nip cell query <utcp-address> [method]`
|
|
|
|
Query Nippel via UTCP protocol.
|
|
|
|
**Methods:**
|
|
- `state` - Get Nippel state
|
|
- `merkle` - Get merkle tree root
|
|
- `activate` - Activate Nippel
|
|
- `deactivate` - Deactivate Nippel
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Query Nippel state
|
|
nip cell query utcp://localhost/nippel/firefox-isolated state
|
|
|
|
# Get merkle root
|
|
nip cell query utcp://localhost/nippel/firefox-isolated merkle
|
|
|
|
# Activate via UTCP
|
|
nip cell query utcp://localhost/nippel/firefox-isolated activate
|
|
```
|
|
|
|
### Package Management
|
|
|
|
#### `nip install --cell=<name> <package>`
|
|
|
|
Install package into a Nippel.
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Install from default repository
|
|
nip install --cell=firefox-isolated firefox
|
|
|
|
# Install from AUR
|
|
nip install --cell=firefox-isolated --graft=aur firefox
|
|
|
|
# Install from Nix
|
|
nip install --cell=firefox-isolated --graft=nix firefox
|
|
|
|
# Install multiple packages
|
|
nip install --cell=dev-env gcc gdb valgrind
|
|
```
|
|
|
|
#### `nip remove --cell=<name> <package>`
|
|
|
|
Remove package from a Nippel.
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Remove package
|
|
nip remove --cell=firefox-isolated firefox-addon
|
|
|
|
# Remove multiple packages
|
|
nip remove --cell=dev-env gcc gdb
|
|
```
|
|
|
|
#### `nip update --cell=<name>`
|
|
|
|
Update packages in a Nippel.
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Update all packages in Nippel
|
|
nip update --cell=firefox-isolated
|
|
|
|
# Update specific package
|
|
nip update --cell=firefox-isolated firefox
|
|
```
|
|
|
|
### Backup and Restore
|
|
|
|
#### `nip cell export <name> [options]`
|
|
|
|
Export Nippel to portable archive.
|
|
|
|
**Options:**
|
|
- `--output=<file>` - Output file path
|
|
- `--compress=<level>` - Compression level (0-9)
|
|
- `--include-data` - Include user data (default: true)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Export Nippel
|
|
nip cell export firefox-isolated --output=firefox.nippel.tar.zst
|
|
|
|
# Export without user data
|
|
nip cell export firefox-isolated --output=firefox-clean.nippel.tar.zst --include-data=false
|
|
```
|
|
|
|
#### `nip cell import <file> [options]`
|
|
|
|
Import Nippel from archive.
|
|
|
|
**Options:**
|
|
- `--name=<name>` - Custom name for imported Nippel
|
|
- `--verify` - Verify integrity after import
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Import Nippel
|
|
nip cell import firefox.nippel.tar.zst
|
|
|
|
# Import with custom name
|
|
nip cell import firefox.nippel.tar.zst --name=firefox-restored
|
|
|
|
# Import and verify
|
|
nip cell import firefox.nippel.tar.zst --verify
|
|
```
|
|
|
|
---
|
|
|
|
## Security Profiles
|
|
|
|
Nippels support five security profiles, each optimized for different use cases:
|
|
|
|
### 1. Workstation Profile (Default)
|
|
|
|
**Best for:** Daily desktop use, balanced security and usability
|
|
|
|
**Settings:**
|
|
- Isolation Level: Standard
|
|
- Desktop Integration: Full
|
|
- Network Access: Full
|
|
- Resource Limits: Moderate
|
|
- XDG Strategy: Portable
|
|
|
|
**Use Cases:**
|
|
- Web browsers for general use
|
|
- Office applications
|
|
- Media players
|
|
- Communication apps
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create firefox-work --profile=workstation
|
|
```
|
|
|
|
### 2. Homestation Profile
|
|
|
|
**Best for:** Home desktop, maximum convenience
|
|
|
|
**Settings:**
|
|
- Isolation Level: Standard
|
|
- Desktop Integration: Maximum
|
|
- Network Access: Full
|
|
- Resource Limits: Relaxed
|
|
- XDG Strategy: System-integrated
|
|
|
|
**Use Cases:**
|
|
- Personal applications
|
|
- Gaming
|
|
- Media creation
|
|
- Home automation
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create gaming --profile=homestation
|
|
```
|
|
|
|
### 3. Satellite Profile
|
|
|
|
**Best for:** Portable environments, maximum isolation
|
|
|
|
**Settings:**
|
|
- Isolation Level: Strict
|
|
- Desktop Integration: Minimal
|
|
- Network Access: Limited
|
|
- Resource Limits: Strict
|
|
- XDG Strategy: Portable
|
|
|
|
**Use Cases:**
|
|
- Untrusted applications
|
|
- Security-sensitive apps
|
|
- Banking/financial apps
|
|
- Portable environments
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create banking --profile=satellite
|
|
```
|
|
|
|
### 4. NetworkIOT Profile
|
|
|
|
**Best for:** Network-focused, minimal resources
|
|
|
|
**Settings:**
|
|
- Isolation Level: Standard
|
|
- Desktop Integration: None
|
|
- Network Access: Full
|
|
- Resource Limits: Minimal
|
|
- XDG Strategy: System-integrated
|
|
|
|
**Use Cases:**
|
|
- Network services
|
|
- IoT applications
|
|
- Headless tools
|
|
- Monitoring agents
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create mqtt-client --profile=networkiot
|
|
```
|
|
|
|
### 5. Server Profile
|
|
|
|
**Best for:** Server applications, no desktop
|
|
|
|
**Settings:**
|
|
- Isolation Level: Strict
|
|
- Desktop Integration: None
|
|
- Network Access: Full
|
|
- Resource Limits: Moderate
|
|
- XDG Strategy: System-integrated
|
|
|
|
**Use Cases:**
|
|
- Server applications
|
|
- Background services
|
|
- Headless applications
|
|
- System daemons
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create web-server --profile=server
|
|
```
|
|
|
|
---
|
|
|
|
## Isolation Levels
|
|
|
|
Nippels support four isolation levels:
|
|
|
|
### 1. None
|
|
|
|
**Description:** No isolation, runs in host environment
|
|
|
|
**Namespaces:** None
|
|
|
|
**Use Cases:**
|
|
- Testing
|
|
- Development
|
|
- Debugging
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create test-app --isolation=none
|
|
```
|
|
|
|
### 2. Standard (Default)
|
|
|
|
**Description:** Balanced isolation for most applications
|
|
|
|
**Namespaces:**
|
|
- Mount namespace (filesystem isolation)
|
|
- PID namespace (process isolation)
|
|
- IPC namespace (inter-process communication isolation)
|
|
|
|
**Use Cases:**
|
|
- Web browsers
|
|
- Office applications
|
|
- Media players
|
|
- Most desktop apps
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create firefox-isolated --isolation=standard
|
|
```
|
|
|
|
### 3. Strict
|
|
|
|
**Description:** Strong isolation for security-sensitive apps
|
|
|
|
**Namespaces:**
|
|
- Mount namespace
|
|
- PID namespace
|
|
- IPC namespace
|
|
- Network namespace (network isolation)
|
|
- UTS namespace (hostname isolation)
|
|
|
|
**Use Cases:**
|
|
- Banking applications
|
|
- Password managers
|
|
- Untrusted applications
|
|
- Security-sensitive apps
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create banking --isolation=strict
|
|
```
|
|
|
|
### 4. Quantum
|
|
|
|
**Description:** Maximum isolation, complete separation
|
|
|
|
**Namespaces:**
|
|
- All namespaces (mount, PID, IPC, network, UTS, user)
|
|
- Complete filesystem isolation
|
|
- No network access
|
|
- No system integration
|
|
|
|
**Use Cases:**
|
|
- Completely untrusted applications
|
|
- Malware analysis
|
|
- Maximum security scenarios
|
|
|
|
**Example:**
|
|
```bash
|
|
nip cell create untrusted --isolation=quantum --network=none
|
|
```
|
|
|
|
---
|
|
|
|
## Common Use Cases
|
|
|
|
### Use Case 1: Isolated Web Browsers
|
|
|
|
**Scenario:** Separate work and personal browsing
|
|
|
|
```bash
|
|
# Create work browser
|
|
nip cell create work-browser --profile=workstation
|
|
nip install --cell=work-browser firefox
|
|
|
|
# Create personal browser
|
|
nip cell create personal-browser --profile=workstation
|
|
nip install --cell=personal-browser firefox
|
|
|
|
# Use work browser
|
|
nip cell activate work-browser
|
|
firefox # Opens work browser with work bookmarks/history
|
|
|
|
# Switch to personal browser
|
|
nip cell deactivate
|
|
nip cell activate personal-browser
|
|
firefox # Opens personal browser with personal bookmarks/history
|
|
```
|
|
|
|
**Benefits:**
|
|
- Complete separation of cookies, cache, history
|
|
- Different extensions per browser
|
|
- Work and personal data never mix
|
|
- Easy to backup each separately
|
|
|
|
### Use Case 2: Gaming Environment
|
|
|
|
**Scenario:** Isolated gaming setup
|
|
|
|
```bash
|
|
# Create gaming environment
|
|
nip cell create gaming --profile=homestation
|
|
nip install --cell=gaming steam discord lutris wine
|
|
|
|
# Activate and game
|
|
nip cell activate gaming
|
|
steam # Runs in isolated environment
|
|
|
|
# Backup gaming environment
|
|
nip cell export gaming --output=gaming-backup.tar.zst
|
|
```
|
|
|
|
**Benefits:**
|
|
- Keep game files separate from work files
|
|
- Easy backup of entire gaming setup
|
|
- No anti-cheat software scanning your system
|
|
- Portable to other machines
|
|
|
|
### Use Case 3: Development Environments
|
|
|
|
**Scenario:** Multiple isolated development environments
|
|
|
|
```bash
|
|
# Python development
|
|
nip cell create python-dev --profile=workstation
|
|
nip install --cell=python-dev python poetry pytest black mypy
|
|
|
|
# Node.js development
|
|
nip cell create node-dev --profile=workstation
|
|
nip install --cell=node-dev nodejs npm yarn typescript
|
|
|
|
# Rust development
|
|
nip cell create rust-dev --profile=workstation
|
|
nip install --cell=rust-dev rustc cargo
|
|
|
|
# Switch between environments
|
|
nip cell activate python-dev
|
|
python --version # Python environment
|
|
|
|
nip cell activate node-dev
|
|
node --version # Node.js environment
|
|
```
|
|
|
|
**Benefits:**
|
|
- No dependency conflicts
|
|
- Clean, isolated environments
|
|
- Easy to recreate
|
|
- Portable across machines
|
|
|
|
### Use Case 4: Banking and Financial Apps
|
|
|
|
**Scenario:** Maximum security for financial applications
|
|
|
|
```bash
|
|
# Create strict banking environment
|
|
nip cell create banking --profile=satellite --isolation=strict
|
|
|
|
# Install banking apps
|
|
nip install --cell=banking firefox
|
|
|
|
# Activate for banking
|
|
nip cell activate banking
|
|
firefox https://mybank.com # Completely isolated
|
|
|
|
# Deactivate when done
|
|
nip cell deactivate
|
|
```
|
|
|
|
**Benefits:**
|
|
- Complete isolation from other apps
|
|
- No access to personal files
|
|
- Limited network access
|
|
- Maximum security
|
|
|
|
### Use Case 5: Untrusted Applications
|
|
|
|
**Scenario:** Run untrusted software safely
|
|
|
|
```bash
|
|
# Create quantum-isolated environment
|
|
nip cell create untrusted --profile=satellite --isolation=quantum --network=none
|
|
|
|
# Activate and run untrusted app
|
|
nip cell activate untrusted
|
|
./suspicious-binary # Completely isolated, no network, no file access
|
|
|
|
# Verify integrity after
|
|
nip cell verify untrusted
|
|
```
|
|
|
|
**Benefits:**
|
|
- Complete isolation
|
|
- No network access
|
|
- No file system access
|
|
- Safe to run untrusted code
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### Issue: "Permission denied" when creating Nippel
|
|
|
|
**Cause:** Insufficient permissions for namespace creation
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Run with sudo (for system-wide Nippels)
|
|
sudo nip cell create my-app
|
|
|
|
# Or create user-level Nippel (no sudo needed)
|
|
nip cell create my-app --user
|
|
```
|
|
|
|
#### Issue: Application doesn't see system themes
|
|
|
|
**Cause:** Desktop integration disabled or wrong profile
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check current profile
|
|
nip cell profile show my-app
|
|
|
|
# Change to profile with desktop integration
|
|
nip cell profile set my-app workstation
|
|
|
|
# Or customize current profile
|
|
nip cell customize my-app --desktop-integration=true
|
|
```
|
|
|
|
#### Issue: Application can't access network
|
|
|
|
**Cause:** Network isolation enabled
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check isolation level
|
|
nip cell show my-app
|
|
|
|
# Change to standard isolation (allows network)
|
|
nip cell profile set my-app workstation --isolation=standard
|
|
|
|
# Or customize network access
|
|
nip cell customize my-app --network=full
|
|
```
|
|
|
|
#### Issue: Nippel verification fails
|
|
|
|
**Cause:** File corruption or tampering
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Verify with details
|
|
nip cell verify my-app --verbose
|
|
|
|
# Attempt to fix
|
|
nip cell verify my-app --fix
|
|
|
|
# If unfixable, restore from backup
|
|
nip cell import my-app-backup.nippel.tar.zst --name=my-app-restored
|
|
```
|
|
|
|
#### Issue: Slow Nippel activation
|
|
|
|
**Cause:** Large number of files or slow storage
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check Nippel size
|
|
nip cell show my-app
|
|
|
|
# Clean up cache
|
|
nip cell clean my-app --cache
|
|
|
|
# Optimize CAS
|
|
nip cas optimize
|
|
|
|
# Check for disk issues
|
|
nip doctor
|
|
```
|
|
|
|
### Diagnostic Commands
|
|
|
|
```bash
|
|
# Check Nippel health
|
|
nip cell doctor my-app
|
|
|
|
# Show detailed status
|
|
nip cell status --verbose
|
|
|
|
# Check CAS integrity
|
|
nip cas verify
|
|
|
|
# Show system information
|
|
nip info
|
|
|
|
# Enable debug logging
|
|
nip --log-level=debug cell activate my-app
|
|
```
|
|
|
|
### Getting Help
|
|
|
|
```bash
|
|
# Show help for any command
|
|
nip cell --help
|
|
nip cell create --help
|
|
nip cell profile --help
|
|
|
|
# Show version information
|
|
nip --version
|
|
|
|
# Report issues
|
|
nip bug-report
|
|
```
|
|
|
|
---
|
|
|
|
## Advanced Topics
|
|
|
|
### Custom Profile Overrides
|
|
|
|
You can customize any profile with specific overrides:
|
|
|
|
```bash
|
|
# Create with custom overrides (JSON)
|
|
nip cell create my-app --customize='{
|
|
"isolationLevel": "strict",
|
|
"desktopIntegration": true,
|
|
"networkAccess": "limited",
|
|
"resourceLimits": {
|
|
"maxMemory": "2GB",
|
|
"maxCPU": "50%"
|
|
}
|
|
}'
|
|
|
|
# Or use a file
|
|
nip cell create my-app --customize-file=overrides.json
|
|
```
|
|
|
|
### UTCP Protocol
|
|
|
|
Nippels are AI-addressable via UTCP (Universal Transport Control Protocol):
|
|
|
|
```bash
|
|
# Get UTCP address
|
|
nip cell show my-app --utcp
|
|
# Output: utcp://localhost/nippel/my-app
|
|
|
|
# Query via UTCP
|
|
nip cell query utcp://localhost/nippel/my-app state
|
|
|
|
# Remote query (if enabled)
|
|
nip cell query utcp://remote-host/nippel/my-app state
|
|
```
|
|
|
|
### Merkle Tree Verification
|
|
|
|
Nippels use merkle trees for integrity verification:
|
|
|
|
```bash
|
|
# Show merkle root
|
|
nip cell show my-app --merkle
|
|
# Output: Merkle Root: xxh3-abc123def456...
|
|
|
|
# Verify integrity
|
|
nip cell verify my-app
|
|
|
|
# Show merkle tree structure
|
|
nip cell merkle my-app --tree
|
|
|
|
# Compare with another Nippel
|
|
nip cell merkle diff my-app other-app
|
|
```
|
|
|
|
### Decentralized Features
|
|
|
|
Nippels support decentralized operation:
|
|
|
|
```bash
|
|
# Announce Nippel to network
|
|
nip cell announce my-app
|
|
|
|
# Discover Nippels on network
|
|
nip cell discover
|
|
|
|
# Sync with remote Nippel
|
|
nip cell sync my-app --from=utcp://remote-host/nippel/my-app
|
|
|
|
# Join decentralized cluster
|
|
nip cluster join my-cluster
|
|
```
|
|
|
|
### Performance Tuning
|
|
|
|
```bash
|
|
# Enable lazy namespace creation
|
|
nip config set lazy-namespaces true
|
|
|
|
# Adjust CAS cache size
|
|
nip config set cas-cache-size 1GB
|
|
|
|
# Enable parallel operations
|
|
nip config set parallel-ops true
|
|
|
|
# Tune merkle tree cache
|
|
nip config set merkle-cache-size 100MB
|
|
```
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [Nippels vs Flatpak](./NIPPELS_VS_FLATPAK.md) - Comparison with Flatpak
|
|
- [Nippels vs Packages](./NIPPELS_VS_PACKAGES.md) - When to use Nippels vs packages
|
|
- [Nippels Requirements](../../.kiro/specs/nip-nippels/requirements.md) - Technical requirements
|
|
- [Nippels Design](../../.kiro/specs/nip-nippels/design.md) - Architecture and design
|
|
- [Security Profiles](./SECURITY_PROFILES.md) - Detailed profile documentation
|
|
|
|
---
|
|
|
|
**Version:** 1.0
|
|
**Last Updated:** November 19, 2025
|
|
**Status:** User Documentation
|
|
**Target Audience:** End users and system administrators
|
|
|