EN - Re-parenting processes to a new terminal with reptyr

25 Mar 2023

Reptyr lets you move a running process (e.g. started in one SSH session or terminal) into another terminal or into tmux/screen, without stopping it. Useful when you forget to start a long job inside tmux, or when you need to hand off a process to another session.

What is reptyr?

reptyr (“re-parent TTY”) attaches an existing process to your current terminal. Typical use: you started a long-running command (build, download, htop) in a plain SSH session, then realize you should have started it inside tmux or screen. Instead of killing and restarting, you can re-parent that process into your multiplexer so it survives disconnects.

Prerequisites (Linux)

reptyr uses ptrace, so on many distros you need to allow it once:

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

To make it persistent across reboots (Debian/Ubuntu):

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

Note: This relaxes a security setting. Use only on machines where you accept that processes can attach to each other (e.g. your own dev box or server).

Install

Package (Debian/Ubuntu)

sudo apt-get install reptyr

From source (if not in repos or you want the latest)

git clone https://github.com/nelhage/reptyr.git
cd reptyr
make
sudo cp reptyr /usr/local/bin/reptyr
cd ..
rm -rf reptyr

Basic workflow

1. Start a long-running process in the current terminal (e.g. htop, a build, or a server).
2. Background it: Ctrl+Z.
3. Resume it in the background: bg.
4. Get the PID of the job:

   jobs -l
   

   Example output:

   [1]+  11216 Stopped (signal)        htop
   

   Here the PID is 11216.

5. Disown the job so the shell no longer tracks it (optional but recommended before re-parenting):

   disown %1
   

   (Use the job number from jobs -l, e.g. %1 for [1].)

6. Start your terminal multiplexer in the same or another SSH session, e.g. tmux or screen.
7. Re-parent the process into this terminal:

   reptyr 11216
   

   Replace 11216 with the PID from step 4.

8. Detach from the multiplexer (e.g. Ctrl+B D in tmux) and close SSH. The process keeps running inside the multiplexer.
9. Later: reconnect via SSH, attach to the multiplexer (tmux attach), and your process is still there.

Example

After running reptyr 11216 inside tmux, the process (here, htop) is attached to the tmux session:

When this is useful

• You started a big compile or download in a “bare” SSH session and want it to survive disconnect → reptyr it into tmux/screen.
• You have a process in one terminal and want it in another (e.g. a different tmux window or pane).
• You’re about to close a terminal but don’t want to kill the process → reptyr it into a session you’ll keep open.

Once the process is re-parented into tmux or screen, you can safely detach and reconnect later without losing it.

comments powered by Disqus