# 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