RunDeck

A fast terminal dashboard for launching, managing, and jumping between personal development projects.

RunDeck brings your projects, tmux workspaces, Neovim, lazygit, local previews, deploy links, and project metadata into one clean keyboard-driven terminal UI.

Installation · Usage · Themes · Configuration · Troubleshooting

Why RunDeck
Features
Installation
- Quick install
- Install by platform
- Updating
- Uninstalling
Requirements
LazyVim setup
Recommended workflow
Usage
Dashboard keymaps
tmux workspace
Local preview
Supported project types
Monorepo and workspace support
Configuration
Homebrew tap
Themes
Optional Neovim and LazyVim plugin
Docker
Kubernetes
Troubleshooting
License

Why RunDeck?

Most developers keep switching between:

terminal folders
tmux sessions
Neovim
lazygit
localhost URLs
deploy links
project notes/configs

RunDeck turns that messy workflow into one fast terminal dashboard.

Instead of remembering where every project lives, which port it runs on, or which command starts it, RunDeck gives you a single keyboard-first place to launch and manage everything.

Features

Fast terminal dashboard built in Rust
Project launcher with tmux + Neovim workspace support
Automatic stack detection
Local preview launcher
Deploy URL launcher
lazygit shortcut
Add existing projects with fzf
Create new projects from the dashboard
Remove projects from RunDeck without deleting folders
Auto-removes missing projects when folders are deleted
Configurable keymaps
Multiple terminal-friendly themes
Optional Neovim/LazyVim companion plugin
Works great with custom dotfiles, tmux layouts, and terminal-first workflows

Installation

Quick install

curl -fsSL https://raw.githubusercontent.com/IntScription/rundeck/main/scripts/install.sh | bash

Then run:

rundeck

If rundeck is not found after installing, add Cargo/local binaries to your shell path:

export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"

For zsh:

echo 'export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Install by platform

macOS

Using Homebrew:

brew install IntScription/rundeck/rundeck

Or tap first:

brew tap IntScription/rundeck
brew install rundeck

Using the install script:

curl -fsSL https://raw.githubusercontent.com/IntScription/rundeck/main/scripts/install.sh | bash

From source:

cargo install --git https://github.com/IntScription/rundeck --force

Linux

Using the universal install script:

curl -fsSL https://raw.githubusercontent.com/IntScription/rundeck/main/scripts/install.sh | bash

Using Homebrew on Linux:

brew install IntScription/rundeck/rundeck

From source:

cargo install --git https://github.com/IntScription/rundeck --force

From a local clone:

git clone https://github.com/IntScription/rundeck.git
cd rundeck
cargo install --path . --force

Linux package-manager notes

RunDeck can be distributed to Linux users in multiple package formats. Use the package that matches your distro once release artifacts are available.

Ubuntu / Debian:

sudo apt install ./rundeck-linux-amd64.deb

Fedora / RHEL:

sudo dnf install ./rundeck-linux-x86_64.rpm

Arch Linux / Manjaro:

sudo pacman -U rundeck-linux-x86_64.pkg.tar.zst

If an AUR package is published later:

yay -S rundeck

Windows

RunDeck is designed around terminal tools like tmux, Neovim, lazygit, and local project folders. On Windows, WSL2 is recommended for the best experience.

Windows with WSL2 recommended

Inside your WSL terminal:

curl -fsSL https://raw.githubusercontent.com/IntScription/rundeck/main/scripts/install.sh | bash

Then run:

rundeck

Native Windows from source

Install Rust, Git, and Neovim, then run:

cargo install --git https://github.com/IntScription/rundeck --force

If you add a PowerShell installer later, you can expose it like this:

irm https://raw.githubusercontent.com/IntScription/rundeck/main/scripts/install.ps1 | iex

Updating

Homebrew:

brew update
brew upgrade rundeck

Source install:

cargo install --git https://github.com/IntScription/rundeck --force

Local clone:

cd rundeck
git pull
cargo install --path . --force

Docker:

docker pull ghcr.io/intscription/rundeck:latest

Uninstalling

Homebrew:

brew uninstall rundeck
brew untap IntScription/rundeck

Cargo/source install:

cargo uninstall rundeck

Remove RunDeck config:

rm -rf ~/.config/rundeck

Remove local data only if you know you no longer need it:

rm -rf ~/.local/share/rundeck

Requirements

RunDeck works best with:

tmux
git
fzf
lazygit
Neovim
LazyVim optional, but recommended for the full terminal IDE workflow
Rust/Cargo only required for source installs

Check your setup:

rundeck doctor

macOS tools

brew install tmux lazygit fzf neovim ripgrep fd

LazyVim is not a separate Homebrew package. It is a Neovim config setup. Install it using the LazyVim setup section below.

Linux tools

Ubuntu / Debian:

sudo apt update
sudo apt install -y git tmux fzf neovim ripgrep fd-find curl build-essential

Optional fd alias for Ubuntu/Debian, because the binary may be named fdfind:

mkdir -p ~/.local/bin
ln -sf "$(command -v fdfind)" ~/.local/bin/fd

Fedora:

sudo dnf install -y git tmux fzf neovim ripgrep fd-find curl gcc gcc-c++ make

Arch Linux / Manjaro:

sudo pacman -S git tmux fzf neovim ripgrep fd curl base-devel

Install lazygit using your distro package manager, Homebrew on Linux, or the official lazygit release package.

Windows tools

For the smoothest setup, install these inside WSL2 using the Linux commands above.

For native Windows, use Windows Terminal plus your preferred package manager:

winget install Git.Git Neovim.Neovim Rustlang.Rustup

LazyVim setup

LazyVim is optional, but it pairs well with RunDeck because RunDeck can launch project workspaces directly into Neovim.

Install LazyVim starter

Back up any existing Neovim config first:

mv ~/.config/nvim{,.bak}
mv ~/.local/share/nvim{,.bak}
mv ~/.local/state/nvim{,.bak}
mv ~/.cache/nvim{,.bak}

Clone the LazyVim starter:

git clone https://github.com/LazyVim/starter ~/.config/nvim
rm -rf ~/.config/nvim/.git
nvim

After opening Neovim, run:

:LazyHealth

Use my dotfiles

If you want the same terminal-first setup with LazyVim, tmux, Alacritty, and related configs, you can use my dotfiles:

git clone https://github.com/IntScription/dotfiles ~/.dotfiles
cd ~/.dotfiles
./install.sh

Or manually stow only the configs you want:

cd ~/.dotfiles
stow nvim tmux alacritty

The dotfiles repo is useful if you want a ready-to-use LazyVim and tmux workflow that matches the way RunDeck is intended to be used.

Recommended workflow

Step	Action
1	Open RunDeck with `rundeck`
2	Press `a` to add an existing project
3	Press `Enter` to open the selected project workspace
4	Use the top pane for Neovim and the bottom pane for shell commands
5	Press `g` when you need lazygit
6	Press `b` to start/open the local preview
7	Use `rundeck back` to return to the dashboard

This is the workflow RunDeck is built for: open a project, code in Neovim, manage Git with lazygit, preview locally, and jump back to your project list without breaking terminal flow.

Usage

Open the dashboard:

rundeck

Run diagnostics:

rundeck doctor

Add a project manually:

rundeck add ~/Projects/my-app --name "My App" --port 3000

Add a deploy URL:

rundeck add ~/Projects/my-app \
  --name "My App" \
  --port 3000 \
  --url "https://my-app.vercel.app"

Dashboard keymaps

Default keymaps:

Key	Action
`Enter`	Open project tmux workspace
`a`	Add existing project
`c`	Create new project
`d`	Remove project from RunDeck only
`b`	Start/open local preview
`B`	Open deployed preview
`g`	Open lazygit
`u`	Edit deploy URL
`e`	Edit RunDeck config
`T`	Theme picker
`D`	Doctor
`/`	Search projects
`?`	Help / commands
`q`	Quit
`h/l`	Switch focus
`j/k`	Move or scroll

Removing a project with d only removes it from RunDeck config. It does not delete the actual project folder.

tmux workspace

Pressing Enter opens a tmux workspace for the selected project.

By default:

Top pane opens your editor
Bottom pane opens a shell
The bottom pane shows useful RunDeck commands

Inside a project tmux session:

rundeck back

Return to RunDeck.

rundeck close

Return to RunDeck and close the current project session.

rundeck kill

Kill the current tmux session.

Local preview

Press b to start the project dev server and open localhost.

RunDeck detects common dev servers:

Next.js → 3000
Vite → 5173
Expo → 8081

For custom setups, edit config:

[[projects]]
name = "My App"
path = "/Users/me/Projects/my-app"
port = 3000
dev_command = "cd web && npm run dev"

Supported project types

RunDeck can detect common project stacks including:

Category	Examples
Frontend	React, Next.js, Vite, Tailwind
Mobile	Expo, React Native
Backend	Node.js, Python, Go, Rust
Infra / services	Supabase, Docker, Kubernetes
Desktop / native	Tauri, Rust
Workspaces	`web`, `mobile`, `apps`, `packages`, monorepos

The stack detector reads common project markers like package.json, framework configs, workspace folders, Rust manifests, Supabase folders, and other development files.

Monorepo and workspace support

RunDeck supports projects like:

my-project/
├─ web/
│  └─ package.json
├─ mobile/
│  └─ package.json
└─ supabase/

It shows one project in the dashboard:

My Project

Example detected stack:

Next.js · React · TypeScript · Tailwind · Expo · React Native · Supabase

Configuration

Config lives here:

~/.config/rundeck/config.toml

Open it from RunDeck with:

Example config:

editor = "nvim"
shell = "/bin/zsh"
theme = "catppuccin-mocha"
top_pane_ratio = 70
show_icons = true
project_picker = "fzf"
project_roots = ["~/Projects", "~/Developer"]

[keymaps]
quit = "q"
help = "?"
search = "/"
add_project = "a"
create_project = "c"
remove_project = "d"
workspace = "enter"
workspace_alt = "t"
local_preview = "b"
deploy_preview = "B"
editor = "o"
lazygit = "g"
edit_deploy = "u"
config = "e"
theme = "T"
doctor = "D"
kill_session = "x"
stop_dev = "X"
reload = "r"
left = "h"
right = "l"
down = "j"
up = "k"

Homebrew tap

RunDeck uses a separate Homebrew tap repository:

IntScription/homebrew-rundeck

That repository contains the Homebrew formula used by:

brew install IntScription/rundeck/rundeck

Or tap first:

brew tap IntScription/rundeck
brew install rundeck

The main repository contains the Rust source code. The Homebrew tap only contains the install recipe.

Themes

RunDeck ships with multiple terminal-friendly themes. The main screenshot at the top of this README uses the Catppuccin Mocha theme.

Open the theme picker from the dashboard:

Then press Enter to apply the selected theme, or q to close the picker.

You can also set a theme manually in ~/.config/rundeck/config.toml:

theme = "catppuccin-mocha"

Available theme values:

catppuccin-mocha
tokyo-night
kanagawa-wave
gruvbox-dark
rose-pine
nord
dracula

Theme gallery

The gallery expects the screenshots to be stored in the assets/ folder with these filenames:

catppuccin-mocha.png
tokyonight.png
kanagawa-wave.png
gruvbox-dark.png
rose-pine.png
nord.png
dracula.png

Catppuccin Mocha	Tokyo Night
Kanagawa Wave	Gruvbox Dark
Rose Pine	Nord
Dracula

Optional Neovim and LazyVim plugin

RunDeck includes an optional Neovim helper plugin.

Folder:

nvim/lua/rundeck.lua

LazyVim plugin setup:

return {
  dir = "~/Projects/Personal/rundeck/nvim",
  name = "rundeck.nvim",
  lazy = false,
  config = function()
    require("rundeck").setup({
      keymaps = {
        open = "<leader>rd",
        add = "<leader>ra",
        create = "<leader>rc",
        config = "<leader>re",
      },
    })
  end,
}

Commands:

:Rundeck
:RundeckAdd
:RundeckCreate
:RundeckConfig

Default keymaps:

Keymap	Action
`<leader>rd`	Open RunDeck dashboard
`<leader>ra`	Add current Neovim project to RunDeck
`<leader>rc`	Open create project helper
`<leader>re`	Edit RunDeck config

Docker

Docker support is mainly for development, testing, and container users. RunDeck is designed to run directly on the host because it integrates with tmux, Neovim, local folders, browser URLs, and user config.

Pull from GitHub Container Registry if the image is published:

docker pull ghcr.io/intscription/rundeck:latest

Run doctor:

docker run --rm ghcr.io/intscription/rundeck:latest doctor

Build locally:

docker build -t rundeck:local .

Run doctor locally:

docker run --rm rundeck:local doctor

Open a container shell:

docker compose run --rm shell

Kubernetes

Kubernetes support is provided as example manifests for running RunDeck as a toolbox/job container.

Apply:

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/job.yaml

View doctor output:

kubectl logs -n rundeck job/rundeck-doctor

Run toolbox pod:

kubectl apply -f k8s/toolbox-pod.yaml
kubectl exec -n rundeck -it rundeck-toolbox -- zsh

Clean up:

kubectl delete namespace rundeck

Troubleshooting

rundeck command not found

Add Cargo/local binaries to your shell path:

export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"

For zsh:

echo 'export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

tmux workspace does not open

Check that tmux is installed:

tmux -V

Then run diagnostics:

rundeck doctor

lazygit does not open

Check that lazygit is installed:

lazygit --version

Neovim does not open

Check your editor:

echo $EDITOR

Or set the editor in ~/.config/rundeck/config.toml:

editor = "nvim"

Local preview opens the wrong port

Set the project port manually:

[[projects]]
name = "My App"
path = "/Users/me/Projects/my-app"
port = 3000
dev_command = "npm run dev"

License

MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
assets		assets
examples		examples
k8s		k8s
nvim/lua		nvim/lua
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

RunDeck

Contents

Why RunDeck?

Features

Installation

Quick install

Install by platform

macOS

Linux

Linux package-manager notes

Windows

Windows with WSL2 recommended

Native Windows from source

Updating

Uninstalling

Requirements

macOS tools

Linux tools

Windows tools

LazyVim setup

Install LazyVim starter

Use my dotfiles

Recommended workflow

Usage

Dashboard keymaps

tmux workspace

Local preview

Supported project types

Monorepo and workspace support

Configuration

Homebrew tap

Themes

Theme gallery

Optional Neovim and LazyVim plugin

Docker

Kubernetes

Troubleshooting

rundeck command not found

tmux workspace does not open

lazygit does not open

Neovim does not open

Local preview opens the wrong port

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages