Skip to content

installation.md

Latest commit

 

History

History
239 lines (167 loc) · 6.26 KB

installation.md

File metadata and controls

239 lines (167 loc) · 6.26 KB
Raw

Installation

TermDeck is a Python package that ships its own web UI. It needs a couple of small external programs to do its job — dtach above all, because that is what keeps terminals alive when the server goes away.

Requirements
OS macOS 13+ or Linux
Python 3.11+
Required dtach
Recommended ripgrep (project search and replace)
Optional claude and/or codex CLIs (agent session resume)

lsof and ps are also used, and are present by default on both macOS and every mainstream Linux distro.

The Python distribution is termdeck-agents, while the command is still termdeck. Install termdeck-agents from PyPI. termdeck on PyPI is a different project.

Homebrew (macOS)

brew install danialfarid/tap/termdeck
termdeck service install

The tap pulls in dtach and ripgrep automatically, and installs TermDeck's Python dependencies from prebuilt CPython 3.13 wheels, so nothing compiles at install time. Works on Apple Silicon and Intel.

Upgrade later with:

brew update
brew upgrade danialfarid/tap/termdeck
termdeck service restart

uv (macOS and Linux)

uv brings its own Python, so the system Python version doesn't matter.

uv tool install termdeck-agents

This installs the latest published release. Upgrade with uv tool upgrade termdeck-agents; pin a release with uv tool install termdeck-agents==0.12.3.

For development builds or a specific Git reference, install directly from GitHub instead:

uv tool install "git+https://github.com/danialfarid/termdeck.git@main"

Append @<tag> yourself to pin an older release.

pipx

pipx install termdeck-agents

pip

Only if you want it inside a specific environment rather than as a standalone tool:

python3 -m pip install termdeck-agents

PyPI and migration from older installations

Install with uv tool install termdeck-agents, pipx install termdeck-agents, or python3 -m pip install termdeck-agents. Upgrade with uv tool upgrade termdeck-agents or pipx upgrade termdeck-agents.

For uv installations from before 0.12.2, stop the service, remove the old tool environment, install the new package, and regenerate the service path. Do not delete ~/.termdeck:

termdeck service stop
uv tool uninstall termdeck
uv tool install termdeck-agents
termdeck service install

For pipx, use pipx uninstall termdeck and pipx install termdeck-agents instead. Homebrew users do not need this migration. Terminal data, settings, and the command name are unchanged.

Installing the external tools

Homebrew handles this for you. Everyone else:

brew install dtach ripgrep                 # macOS, Linuxbrew
sudo apt install dtach ripgrep             # Debian, Ubuntu
sudo dnf install dtach ripgrep             # Fedora, RHEL
sudo pacman -S dtach ripgrep               # Arch
sudo zypper install dtach ripgrep          # openSUSE

The agent CLIs, if you want session resume:

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex

From source

git clone https://github.com/danialfarid/termdeck.git
cd termdeck
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/termdeck --open

-e gives you an editable install, so edits to the Python source take effect on the next restart and edits to termdeck/static/ take effect on the next browser reload.

Verify the install

termdeck doctor
termdeck  http://127.0.0.1:8530
data dir  /Users/you/.termdeck
file root /Users/you
shell     /bin/zsh

[ok ] dtach    /opt/homebrew/bin/dtach
[ok ] zsh      /bin/zsh
[ok ] lsof     /usr/sbin/lsof
[ok ] ps       /bin/ps
[ok ] rg       /opt/homebrew/bin/rg
[ok ] claude   /Users/you/.local/bin/claude
[ok ] codex    /opt/homebrew/bin/codex

all required programs present

Anything missing is printed with the exact command to install it. doctor exits non-zero if a required program is missing, so it is safe to use in a setup script.

First run

termdeck --open

The server starts on http://127.0.0.1:8530 and your browser opens. Press ⌘B to open your first terminal.

To pick a different port or data directory:

termdeck --port 9000 --data-dir ~/somewhere-else

Install as a background service

So it is always there, and starts at login:

termdeck service install

Flags given at install time are baked into the generated unit:

termdeck --port 9000 --default-cwd ~/projects service install
macOS Linux
Mechanism launchd user agent systemd user unit
Unit file ~/Library/LaunchAgents/com.termdeck.plist ~/.config/systemd/user/termdeck.service
Logs ~/.termdeck/termdeck.log systemd journal
Start / stop termdeck service start / stop termdeck service start / stop
Restart termdeck service restart termdeck service restart

start and restart install the service if it has never been installed, and load its unit file if it is present but not loaded — so either one is safe as the first command on a fresh machine. stop unloads it until the next start or login; the unit file stays.

On Linux, to have the service run without a graphical login session:

sudo loginctl enable-linger $USER

Remove it with termdeck service uninstall.

Upgrading

Installed with Upgrade
Homebrew brew update && brew upgrade danialfarid/tap/termdeck && termdeck service restart
uv uv tool install --force "git+https://github.com/danialfarid/termdeck.git"
pipx pipx install --force "git+https://github.com/danialfarid/termdeck.git"
pip pip install --upgrade "git+https://github.com/danialfarid/termdeck.git"
Source git pull

If you run it as a service, restart it afterwards so the new version is picked up:

termdeck service restart

Your terminals will respawn and resume, so an upgrade costs you nothing but a few seconds.

Uninstalling

termdeck service uninstall     # stop the service and remove the unit file first
brew uninstall termdeck        # or: uv tool uninstall termdeck-agents / pipx uninstall termdeck-agents

Your data in ~/.termdeck is left alone. Delete it yourself if you want it gone.