19 KiB

Raw Blame History

Nippels User Guide

Complete guide to using Nippels (NimPak Cells) for application isolation

Introduction
Quick Start
CLI Commands Reference
Security Profiles
Isolation Levels
Common Use Cases
Troubleshooting
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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

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:

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

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:

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:

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:

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:

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:

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:

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:

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:

nip cell create untrusted --isolation=quantum --network=none

Common Use Cases

Use Case 1: Isolated Web Browsers

Scenario: Separate work and personal browsing

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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:

# 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):

# 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:

# 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:

# 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

# 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

19 KiB Raw Blame History

Nippels User Guide

Table of Contents

Introduction

When to Use Nippels

Quick Start

Creating Your First Nippel

Creating with a Security Profile

Listing and Managing Nippels

CLI Commands Reference

Core Commands

nip cell create <name> [options]

nip cell activate <name>

nip cell list [options]

nip cell show <name>

nip cell remove <name> [options]

Profile Management

nip cell profile list

nip cell profile show <name>

nip cell profile set <name> <profile>

Verification Commands

nip cell verify <name> [options]

nip cell query <utcp-address> [method]

Package Management

nip install --cell=<name> <package>

nip remove --cell=<name> <package>

nip update --cell=<name>

Backup and Restore

nip cell export <name> [options]

nip cell import <file> [options]

Security Profiles

1. Workstation Profile (Default)

2. Homestation Profile

3. Satellite Profile

4. NetworkIOT Profile

5. Server Profile

Isolation Levels

1. None

2. Standard (Default)

3. Strict

4. Quantum

Common Use Cases

Use Case 1: Isolated Web Browsers

Use Case 2: Gaming Environment

Use Case 3: Development Environments

Use Case 4: Banking and Financial Apps

Use Case 5: Untrusted Applications

Troubleshooting

Common Issues

Issue: "Permission denied" when creating Nippel

Issue: Application doesn't see system themes

Issue: Application can't access network

Issue: Nippel verification fails

Issue: Slow Nippel activation

Diagnostic Commands

Getting Help

Advanced Topics

Custom Profile Overrides

UTCP Protocol

Merkle Tree Verification

Decentralized Features

Performance Tuning

See Also

19 KiB

Raw Blame History

`nip cell create <name> [options]`

`nip cell activate <name>`

`nip cell list [options]`

`nip cell show <name>`

`nip cell remove <name> [options]`

`nip cell profile list`

`nip cell profile show <name>`

`nip cell profile set <name> <profile>`

`nip cell verify <name> [options]`

`nip cell query <utcp-address> [method]`

`nip install --cell=<name> <package>`

`nip remove --cell=<name> <package>`

`nip update --cell=<name>`

`nip cell export <name> [options]`

`nip cell import <file> [options]`