attach Command

Table of Contents

  1. Overview
    1. How It Works
  2. TUI Usage
  3. Syntax
    1. Parameters
    2. Options
  4. Usage Examples
    1. Basic Attachment
    2. Finding Process PID
    3. Attach and Execute Command Immediately
  5. Permission Requirements
    1. Linux Systems
      1. Same User
      2. Different Users (Requires sudo)
      3. ptrace_scope Configuration
    2. Docker Containers
    3. SELinux Systems
  6. Output Format
    1. Success Response
    2. Error Response
  7. Troubleshooting
    1. Error: Operation not permitted
    2. Error: Process not found
    3. Error: Python debugging symbols not found (Linux, Python < 3.14)
    4. Error: GDB not found (Linux, Python < 3.14)
    5. Error: LLDB not found (macOS, Python < 3.14)
    6. Error: Timeout attaching to process
  8. Security Considerations
    1. Process Isolation
    2. Principle of Least Privilege
    3. Code Injection Security
  9. Reliability Improvements
  10. Version History
  11. Related Commands
  12. References

Overview

The attach command is the first step in using Peeka. It injects Peeka Agent code into the target process and starts a Unix Domain Socket server, establishing a communication channel for subsequent diagnostic commands.

How It Works

Python 3.14+:

  • Uses PEP 768’s sys.remote_exec() API
  • Secure, efficient, officially supported

Python 3.8.1-3.13:

  • Uses GDB + ptrace on Linux
  • Uses LLDB + dlopen on macOS
  • Compatibility fallback solution

TUI Usage

TUI Auto-Attach on Launch: Running peeka command directly launches TUI and automatically shows process selector:

  1. Run peeka (no arguments)
  2. In process selector, choose target process
  3. Press Enter to auto-attach and enter main interface

TUI Features:

  • Real-time process list refresh
  • Display process PID, command line, CPU/memory usage
  • Support search/filter (type keywords to filter)
  • Auto-validate permissions (show PEP 768, GDB, or LLDB availability)
  • Since v0.1.14, the attach flow shows Progress and Attach Log areas, displays the real failure inline, resets the panel with Esc on error, ignores Esc while attach is in progress, and exits with Esc when idle

CLI Equivalent Commands: All examples below use CLI commands for demonstration. TUI provides the same functionality with a graphical interface.

Syntax 

peeka-cli attach <pid> [options]

Parameters

Parameter Type Required Description
pid int ✅ PID of the target process

Options

Option Description Default
--timeout Attachment timeout (seconds) 30
--socket-dir Socket file directory /tmp

Usage Examples

Basic Attachment 

# Attach to process 12345
peeka-cli attach 12345

Output:

{"type":"status","level":"info","message":"Attaching to process 12345"}
{"type":"status","level":"info","message":"Using PEP 768 remote_exec"}
{"type":"success","command":"attach","data":{"pid":12345,"socket":"/tmp/peeka_12345.sock"}}

Finding Process PID 

# Using ps
ps aux | grep python

# Using pgrep
pgrep -f "my_app.py"

# Using pidof
pidof python3

Attach and Execute Command Immediately 

# Attach then immediately observe
peeka-cli attach 12345 && peeka-cli watch "app.func"

Permission Requirements

Linux Systems

Same User

The simplest approach is to run Peeka as the same user:

# Both target process and Peeka run as user1
user1$ python my_app.py  # PID: 12345
user1$ peeka-cli attach 12345  # ✅ Success

Different Users (Requires sudo) 

# Target process runs as user1, need sudo
user1$ python my_app.py  # PID: 12345
user2$ sudo peeka-cli attach 12345  # ✅ Success

ptrace_scope Configuration

Check current configuration:

cat /proc/sys/kernel/yama/ptrace_scope
Value Description Peeka Availability
0 No restrictions (not recommended) ✅ All users can attach
1 Only parent-child processes or CAP_SYS_PTRACE ✅ Recommended setting
2 Only CAP_SYS_PTRACE ✅ Requires sudo
3 Completely disabled ❌ Cannot use

Temporary modification (for testing):

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

Permanent modification:

echo "kernel.yama.ptrace_scope = 1" | sudo tee /etc/sysctl.d/10-ptrace.conf
sudo sysctl -p /etc/sysctl.d/10-ptrace.conf

Docker Containers

Need to add SYS_PTRACE capability:

# Add when running container
docker run --cap-add=SYS_PTRACE your-image

# docker-compose.yml
services:
  app:
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined

SELinux Systems

Check SELinux status:

getenforce  # Enforcing, Permissive, Disabled

Temporarily allow ptrace:

sudo setsebool -P deny_ptrace off

Output Format

Success Response 

{
  "type": "success",
  "command": "attach",
  "data": {
    "pid": 12345,
    "socket": "/tmp/peeka_12345.sock",
    "python_version": "3.12.0",
    "attach_method": "remote_exec"
  }
}

Error Response 

{
  "type": "error",
  "command": "attach",
  "error": "Operation not permitted: ptrace access denied"
}

Troubleshooting

Error: Operation not permitted

Cause: Insufficient permissions

Solutions:

  1. Use same user or sudo
  2. Check ptrace_scope setting
  3. Check SELinux configuration
# Check process owner
ps -o user= -p 12345

# Use sudo
sudo peeka-cli attach 12345

# Relax ptrace restrictions (for testing)
echo 1 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Error: Process not found

Cause: PID doesn’t exist or has exited

Solutions:

# Confirm process exists
ps -p 12345

# Re-find PID
pgrep -f "my_app.py"

Error: Python debugging symbols not found (Linux, Python < 3.14)

Cause: Missing Python debugging symbols (required for the Linux GDB fallback)

Solutions:

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

# RHEL/CentOS
sudo yum install python3-debuginfo

Error: GDB not found (Linux, Python < 3.14)

Cause: GDB not installed

Solutions:

# Debian/Ubuntu
sudo apt-get install gdb

# RHEL/CentOS
sudo yum install gdb

Error: LLDB not found (macOS, Python < 3.14)

Cause: Xcode Command Line Tools are not installed

Solutions:

xcode-select --install

Error: Timeout attaching to process

Cause: Attachment timeout (target process may be hung)

Solutions:

# Increase timeout
peeka-cli attach 12345 --timeout 60

# Check target process status
ps -p 12345 -o stat=

Security Considerations

Process Isolation

  • Peeka can only attach to local processes
  • Remote attachment not supported
  • Unix Domain Socket limited to local access only

Principle of Least Privilege

  • Production environments should use same user
  • Avoid using root privileges
  • Detach promptly when diagnostics are no longer needed

Code Injection Security

  • Agent code only performs diagnostic functions
  • Does not modify business logic
  • All injections can be reverted via reset command

Reliability Improvements

Peeka v0.1.9–v0.1.14 introduced several reliability enhancements for attachment:

  • TUI attach panel gained progress, log, elapsed time, and inline error display (v0.1.14: 56fa814, 4a300f9)
  • Native _socket.socket accept handling was fixed for a more stable notify server in monkey-patched runtimes (v0.1.14: 5617058)
  • Connection error messages are more descriptive (v0.1.11: 88da13e)
  • Streaming client identification improved to reduce connection failures (v0.1.9: a90d080)
  • Socket handling and connection validation strengthened (v0.1.11–v0.1.12: 9ef3222)
  • Broadcast frames correctly skipped for improved streaming client stability (v0.1.12: 9c90675)

Version History

Version Release Date Changes
0.1.14 2026-05-24 TUI attach progress/log/inline error display; fixed native socket accept for notify server
0.1.12 2026-05-08 Socket handling enhancements (9ef3222), broadcast frame skip (9c90675)
0.1.11 2026-05-07 Attach reliability fix, error surfacing improvements (88da13e)
0.1.9 2026-05-04 Streaming client identification improvements (a90d080)

References

Back to top

Copyright © 2026 Peeka contributors. Distributed under the Apache License 2.0.

This site uses Just the Docs, a documentation theme for Jekyll.