Installation Guide

This guide will help you install and configure Peeka in different environments.

Table of Contents

1. System Requirements
   1. Basic Requirements
   2. Python Version Comparison
2. Installation Methods
   1. Install with pip (Recommended)
      1. Basic Version (CLI Only)
      2. Full Version (with TUI)
   2. Install with uv
   3. Install from Source
3. Additional Configuration for Python < 3.14
   1. Debian/Ubuntu
   2. RHEL/CentOS/Fedora
   3. macOS
4. Permission Configuration
   1. Linux Systems
      1. Temporarily Relax ptrace Restrictions (Testing Only)
      2. Permanent Configuration (Recommended for Production)
      3. SELinux Systems (Fedora/RHEL)
   2. Docker Containers
5. Verify Installation
   1. Check Version
   2. Run Tests
   3. Check Dependencies
6. Common Issues
   1. Attachment Failed: Insufficient Permissions
   2. Python < 3.14 on Linux: Debugging Symbols Not Found
   3. GDB Version Too Old
   4. macOS: LLDB Unavailable or Permission Denied
7. Next Steps
8. Getting Help

---

System Requirements

Basic Requirements

• Python Version: Python 3.8.1 or higher
• Operating System: Linux (recommended), macOS
• Permissions: Permission to attach to target processes (same UID or CAP_SYS_PTRACE)

Python Version Comparison

Python Version	Attach Mechanism	Additional Requirements
3.14+	PEP 768 sys.remote_exec	None
3.8.1-3.13	Linux: GDB + ptrace; macOS: LLDB + dlopen	Linux: GDB 7.3+, python3-dbg, CAP_SYS_PTRACE; macOS: Xcode Command Line Tools

---

Installation Methods

Install with pip (Recommended)

Basic Version (CLI Only)

pip install peeka

Full Version (with TUI)

pip install peeka[tui]

Install with uv

# Basic version
uv pip install peeka

# Full version (with TUI)
uv pip install "peeka[tui]"

# Development environment (from source)
uv sync --dev

Install from Source

# Clone the repository
git clone https://github.com/peeka-project/peeka.git
cd peeka

# Install (basic version)
uv pip install -e .

# Install (with TUI)
uv pip install -e ".[tui]"

# Development environment (full dependencies)
uv sync --dev

---

Additional Configuration for Python < 3.14

For Python 3.8.1-3.13, Linux needs GDB and Python debugging symbols; macOS uses LLDB and needs Xcode Command Line Tools.

Debian/Ubuntu

sudo apt-get update
sudo apt-get install gdb python3-dbg

RHEL/CentOS/Fedora

sudo yum install gdb python3-debuginfo

macOS

xcode-select --install

---

Permission Configuration

Linux Systems

Temporarily Relax ptrace Restrictions (Testing Only)

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Permanent Configuration (Recommended for Production)

Edit /etc/sysctl.d/10-ptrace.conf:

kernel.yama.ptrace_scope = 1

Then apply the configuration:

sudo sysctl -p /etc/sysctl.d/10-ptrace.conf

SELinux Systems (Fedora/RHEL)

# Check SELinux status
getenforce

# Temporarily allow ptrace
sudo setsebool -P deny_ptrace off

# Or create SELinux policy for specific processes

Docker Containers

Add --cap-add=SYS_PTRACE parameter when running Docker containers:

docker run --cap-add=SYS_PTRACE your-image

Or configure in docker-compose.yml:

services:
  app:
    image: your-image
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined

---

Verify Installation

Check Version

peeka-cli --version
# peeka-cli 0.1.10

Run Tests

# Start demo application
python -m peeka.examples.demo --mode loop

# Test attachment in another terminal
peeka-cli attach <pid>

Check Dependencies

# Check Python version
python --version

# Check GDB (Linux, Python < 3.14)
gdb --version

# Check LLDB (macOS, Python < 3.14)
lldb --version

# Check Python debugging symbols (Linux, Python < 3.14)
python -c "import sys; print(hasattr(sys, 'gettotalrefcount'))"

---

Common Issues

Attachment Failed: Insufficient Permissions

Error Message:

Error: Operation not permitted

Solution:

1. Ensure you have the same UID as the target process, or use sudo
2. Check ptrace_scope settings
3. For Docker, ensure CAP_SYS_PTRACE is added

Python < 3.14 on Linux: Debugging Symbols Not Found

Error Message:

Error: Python debugging symbols not found

Solution:

# Debian/Ubuntu
sudo apt-get install python3-dbg

# RHEL/CentOS
sudo yum install python3-debuginfo

GDB Version Too Old

Error Message:

Error: GDB version 7.3+ required

Solution:

# Update GDB
sudo apt-get update
sudo apt-get install --only-upgrade gdb

# Or compile the latest version from source

macOS: LLDB Unavailable or Permission Denied

Error Message:

Error: LLDB not found
Error: LLDB attach failed: permission denied

Solution: Install Xcode Command Line Tools:

xcode-select --install

---

Next Steps

After installation, you can:

• Quick Start - Learn basic usage
• Command Reference - View all available commands
• Examples - Real-world application scenarios

---

Getting Help

If you encounter problems during installation:

1. Check Troubleshooting
2. Ask questions on GitHub Issues