zellij пошагово: рабочий терминал на сервере, который переживает обрыв ssh

В посте "Из браузера в терминал" было обещание: наберутся реакции – будет пошаговая статья. Реакции набрались, вот статья.

К концу на сервере будет свой zellij: панели и вкладки, рабочее место из файла раскладки, отключение без потери работы, воскрешение сессии после падения сервера, переподключение при обрыве ssh и меню сессий по Alt+s. Нужен только опыт работы с ssh, с tmux и screen можно не быть знакомым.

Всё ниже прогнано на чистой Ubuntu 22.04 с zellij 0.45.1, последним релизом на конец октября 2026. Клавиши даны для пресета Default. Поведение, взятое из исходников, помечено файлом из тега v0.45.1. Скриншоты – снимки окна терминала: zellij работал в такой же Ubuntu 22.04 в контейнере, рядом с учебным кластером k3s.

Что понадобится

• сервер с Linux на x86_64 или ARM (здесь Ubuntu 22.04), доступ по ssh и curl;
• на ноутбуке ssh-клиент и bash или zsh, для функции переподключения в шаге 8;
• fzf для меню сессий в шаге 9.

Шаг 1. Установка

В репозиториях Ubuntu 22.04 zellij нет. Проще всего взять готовый статический бинарь из релиза на GitHub:

V=0.45.1
A=zellij-x86_64-unknown-linux-musl      # на ARM: zellij-aarch64-unknown-linux-musl
cd /tmp
curl -fsSLO https://github.com/zellij-org/zellij/releases/download/v$V/$A.tar.gz
curl -fsSLO https://github.com/zellij-org/zellij/releases/download/v$V/$A.sha256sum
tar -xzf $A.tar.gz
echo "$(cut -d' ' -f1 $A.sha256sum)  zellij" | sha256sum -c -
install -D -m 755 zellij ~/.local/bin/zellij

Обычный sha256sum -c $A.sha256sum здесь упадёт с FAILED open or read. В файле лежит хэш самого бинаря, записанный под путём сборки target/x86_64-unknown-linux-musl/release/zellij. Поэтому сначала распаковываем, потом сверяем хэш с распакованным zellij и ждём ответа zellij: OK.

В релизе есть ещё сборка zellij-no-web-… без встроенного веб-сервера, если он не нужен.

Ubuntu добавляет ~/.local/bin в PATH из ~/.profile, и только если каталог существовал на момент входа. Каталог только что создан, поэтому перед проверкой версии перелогиньтесь или выполните source ~/.profile:

zellij --version
# zellij 0.45.1

Команда, выполненная по ssh без входа в шелл (ssh srv 'zellij ls'), ~/.profile не читает и ответит command not found. Поэтому в скриптах ниже PATH выставлен явно.

Шаг 2. Первый запуск и режимы

zellij

Первым откроется окно First Run Setup Wizard с выбором из двух пресетов:

В статье используется Default, он выбирается по Enter. Выбор сохранится в ~/.config/zellij/config.kdl. Этот файл zellij создаёт уже при первом запуске, в нём полный конфиг со всеми клавишами. После выбора пресета zellij переписывает его, а прежнюю версию кладёт рядом как config.kdl.bak.

При каждом старте сессии поверх экрана выходит окно About Zellij с подсказкой дня. Esc его закрывает, Ctrl+c отключает подсказки при старте. Закрыть его стоит сразу: пока оно на экране, у вкладки включён слой плавающих панелей, и Alt+n откроет новую панель плавающей поверх экрана.

Если в строке вкладок и строке статуса вместо стрелок квадраты, в шрифте терминала нет символа U+E0B0 из набора Powerline. Поставьте шрифт из Nerd Fonts или включите в config.kdl строку simplified_ui true: zellij нарисует те же строки без стрелок (zellij-utils/assets/config/default.kdl:284).

Строка статуса внизу показывает режимы и их клавиши, поэтому учить таблицу наизусть не нужно:

Из любого режима в обычный возвращают Esc или Enter.

У Default есть цена: Ctrl+p в bash – предыдущая команда, а zellij перехватывает его раньше. Когда сочетание нужно программе внутри панели, нажмите Ctrl+g. Строка статуса покажет -- INTERFACE LOCKED --, Ctrl+p уйдёт в bash, а повторный Ctrl+g снимет блокировку.

Если вы на macOS, Alt-сочетания доходят до сервера, только когда Option в терминале работает как Meta (в iTerm2 это настройка Esc+ для клавиши Option).

Шаг 3. Панели и вкладки

Несколько деталей, которые видно только в работе:

• Alt+l в самой правой панели переходит на следующую вкладку, с последней вкладки – на первую. Alt+h работает так же влево.
• Если плавающих панелей во вкладке ещё нет, первое Ctrl+p → w или Alt+f создаёт новую плавающую.
• В стопке видна целиком одна панель, от остальных остаются строки заголовков. Это удобно, когда панелей много, а экран маленький.
• Alt+= растит текущую панель: соседние сворачиваются в стопку, после нескольких нажатий панель занимает всю вкладку. Alt+- уменьшает её обратно.

Шаг 4. Сессии: отключиться и вернуться

Сессия – это сервер zellij со всеми вкладками и процессами внутри. Без имени zellij придумает случайное (loyal-yak, splendid-peach), своё задаётся ключом -s:

zellij -s work

В сессии запустите что-нибудь долгое, например sleep 100000, и отключитесь: Ctrl+o → d. Терминал вернётся в шелл с сообщением Bye from Zellij!, а процесс продолжит работать:

zellij ls -n                 # список сессий; -n – без цветов, удобно для скриптов
# work [Created 25s ago]
pgrep -a -x sleep
# 2508457 sleep 100000
zellij attach work           # вернуться: вкладки, панели и sleep на месте

Остальные команды для сессий:

zellij attach -c work        # подключиться, а если сессии нет – создать
zellij kill-session work     # остановить сервер: процессы умрут, раскладка останется
zellij delete-session work   # удалить остановленную сессию совсем

Изнутри сессии список всех сессий с числом вкладок и подключённых клиентов открывает Ctrl+o → w (Session Manager).

Шаг 5. Ctrl+q и правка конфига

По умолчанию Ctrl+q в zellij – Quit (zellij-utils/assets/config/default.kdl:198): все процессы сессии завершаются. После этого zellij ls покажет work [...] (EXITED - attach to resurrect). Вкладки вернуть можно, но всё запущенное придётся поднимать заново. Ctrl+q стоит переназначить на отключение раньше, чем он сработает случайно:

sed -i 's/bind "Ctrl q" { Quit; }/bind "Ctrl q" { Detach; }/' ~/.config/zellij/config.kdl
grep -n 'Ctrl q' ~/.config/zellij/config.kdl
# 174:        bind "Ctrl q" { Detach; }

Новые клавиши гарантированно подхватываются при следующем подключении: Ctrl+o → d, затем zellij attach work. После этого Ctrl+q отключает от сессии, а zellij ls показывает её живой, без EXITED.

Остальное в config.kdl можно не трогать. В рабочем конфиге на главном сервере руками изменены ровно две строки, всё остальное записал мастер первого запуска:

-        bind "Ctrl q" { Quit; }
+        bind "Ctrl q" { Detach; }
+        bind "Alt s" { Run "/home/ubuntu/.local/bin/lc-pick" { floating true; close_on_exit true; name "сессии"; }; }

Про Alt+s – в шаге 9.

Шаг 6. Раскладка: рабочее место одной командой

Раскладка – это файл KDL с описанием вкладок, панелей и команд. Файлы из ~/.config/zellij/layouts/ можно вызывать по имени, например ~/.config/zellij/layouts/work.kdl ниже вызывается как work:

layout {
    default_tab_template {
        pane size=1 borderless=true {
            plugin location="zellij:tab-bar"
        }
        children
        pane size=2 borderless=true {
            plugin location="zellij:status-bar"
        }
    }
    tab name="код" focus=true cwd="~/project" {
        pane split_direction="vertical" {
            pane size="65%"
            pane command="git" {
                args "log" "--oneline" "-20"
            }
        }
    }
    tab name="сервер" {
        pane command="htop"
        pane command="df" size="30%" {
            args "-h"
        }
    }
}

default_tab_template – шаблон для каждой вкладки: сверху строка вкладок, снизу строка статуса, на месте children – панели самой вкладки. Без шаблона zellij откроет вкладки голыми, без этих двух строк. pane command= запускает программу вместо шелла. Когда программа завершается, панель остаётся на экране с кодом выхода в заголовке, например git log --oneline -20 [ EXIT CODE: 0 ].

~/project замените на свой каталог. Если каталога нет, zellij ошибку не покажет и откроет панели в том каталоге, откуда запущен.

Запуск:

zellij -s dev -n work        # -n – раскладка по имени или по пути к файлу

Если сессия dev уже есть, zellij откажется: Session with name "dev" already exists. Use attach command to connect to it or specify a different name. Обёртка, которая сама выбирает между созданием и подключением, – в шаге 8.

Пример ближе к повседневной работе с Kubernetes – раскладка ~/.config/zellij/layouts/ops.kdl. Во вкладке "кластер" k9s, во вкладке "логи" поток логов воркеров и kubectl get pods --watch, во вкладке "код" репозиторий. На сервере нужны kubectl, k9s и доступ к кластеру, shop – пространство имён учебного кластера:

layout {
    default_tab_template {
        pane size=1 borderless=true {
            plugin location="zellij:tab-bar"
        }
        children
        pane size=2 borderless=true {
            plugin location="zellij:status-bar"
        }
    }
    tab name="кластер" focus=true {
        pane command="k9s" {
            args "-n" "shop"
        }
    }
    tab name="логи" {
        pane command="kubectl" {
            args "-n" "shop" "logs" "-f" "-l" "app=worker" "--prefix" "--tail" "8"
        }
        pane command="kubectl" size="40%" {
            args "-n" "shop" "get" "pods" "--watch"
        }
    }
    tab name="код" cwd="~/project" {
        pane split_direction="vertical" {
            pane size="60%"
            pane command="git" {
                args "log" "--oneline" "-15"
            }
        }
    }
}

Запуск – zellij -s ops -n ops. Так выглядят вкладки "кластер" и "логи", во время снимка в нижней панели шёл kubectl rollout restart деплоймента web:

Рабочая раскладка на главном сервере короче. В ней одна вкладка, меню агентов, а остальные вкладки открываются из меню:

layout {
    default_tab_template {
        pane size=1 borderless=true {
            plugin location="zellij:tab-bar"
        }
        children
        pane size=2 borderless=true {
            plugin location="zellij:status-bar"
        }
    }
    tab name="☰ меню (Alt-s)" focus=true {
        pane command="/home/ubuntu/.local/bin/lc-pick" {
            args "--loop"
        }
    }
}

Шаг 7. Воскрешение после падения сервера

Сохранение сессий включено по умолчанию (zellij-server/src/screen.rs:8074). Раз в 60 секунд (zellij-server/src/background_jobs.rs:124) zellij записывает раскладку сессии в ~/.cache/zellij/contract_version_1/session_info/<имя>/session-layout.kdl: вкладки, панели, их каталоги и команды, запущенные в панелях. sleep 100000, набранный руками в шелле, попадает туда как команда панели:

pane command="sleep" cwd="home/ubuntu/zellij-statya" size="50%" {
    args "100000"
    start_suspended true
}

Сохранить сразу, не дожидаясь минуты:

zellij action save-session

Теперь уроним сервер. zellij kill-session work и kill -9 процесса zellij --server ведут себя одинаково: процессы в панелях умирают вместе с сервером, а сессия остаётся в списке:

zellij ls -n
# work [Created 10s ago] (EXITED - attach to resurrect)
pgrep -a -x sleep | grep 100000 || echo "sleep умер вместе с сервером"
# sleep умер вместе с сервером

zellij attach work вернёт вкладки, панели и каталоги, но команды сразу не запустит. Из-за start_suspended true на месте каждой будет:

Waiting to run: sleep 100000
<ENTER> run, <ESC> drop to shell, <Ctrl-c> exit

Так выглядит вкладка "логи" из ops.kdl после падения сервера, обе команды kubectl ждут Enter:

Чтобы запустить все команды сразу:

zellij attach -f work        # --force-run-commands
pgrep -a -x sleep | grep 100000
# 2513575 sleep 100000

PID новый: воскрешение запускает команды заново, прежние процессы погибли вместе с сервером. Состояние программ и вывод на экране пропадают, раскладка и каталоги остаются. Если сервер упал раньше первого сохранения, воскрешать нечего: сессия, созданная и убитая в первые секунды, из zellij ls пропадает целиком. Файл раскладки лежит в ~/.cache, а сокеты сервера – в /tmp/zellij-<uid>/.

Шаг 8. Переподключение при обрыве ssh

Сама сессия на сервере обрыв переживает, ssh-клиент – нет. Его нужно запустить заново и снова подключиться. Это делают две маленькие обёртки: скрипт на сервере и функция на ноутбуке.

Скрипт на сервере, ~/.local/bin/work-attach, выбирает одно из трёх действий:

#!/usr/bin/env bash
# work-attach – войти в zellij-сессию: создать, воскресить или подключиться
export PATH="$HOME/.local/bin:$PATH"
S="${1:-work}"
st=$(zellij ls -n 2>/dev/null | grep -E "^$S ")
if [ -z "$st" ]; then
  exec zellij -s "$S" -n work            # сессии нет – поднять из раскладки
elif echo "$st" | grep -q EXITED; then
  exec zellij attach -f "$S"             # сервер умер – воскресить и сразу запустить команды
else
  exec zellij attach "$S"                # живая – подключиться
fi

chmod +x ~/.local/bin/work-attach

Ветки нужны потому, что zellij attach -c создаёт сессию без раскладки, а zellij -s с раскладкой падает на существующем имени. export PATH стоит из-за того, что по ssh без входа в шелл ~/.local/bin в PATH не попадает.

Функция на ноутбуке, в ~/.bashrc или ~/.zshrc. srv – хост из ~/.ssh/config:

w() {
  while :; do
    ssh -t -o ServerAliveInterval=10 -o ServerAliveCountMax=3 srv "~/.local/bin/work-attach" && break
    echo "связь потеряна, переподключаюсь через 3 с (Ctrl-C – выход)"; sleep 3
  done
}

При отключении по Ctrl+q zellij выходит с кодом 0, ssh возвращает 0, и цикл заканчивается. При обрыве ssh завершается с кодом 255, и цикл подключается снова.

Без ServerAlive* функция бесполезна при самом частом обрыве, когда сеть пропала, а TCP-соединение формально не закрыто. ssh тогда просто висит. Это проверялось так: ssh пускался через socat, который потом замораживался kill -STOP. С параметрами из функции (10 секунд × 3 проверки) новое соединение поднялось через 42 секунды после заморозки. С ServerAliveInterval=0 ssh провисел почти три минуты без признаков жизни, после чего проверку остановили. Те же параметры можно прописать и для хоста в ~/.ssh/config.

На главном сервере эта пара называется lc и lc-attach и устроена так же. Есть одно отличие: при подключении к живой сессии фокус сразу переходит на первую вкладку с меню, даже если отключались с другой:

#!/usr/bin/env bash
# lc-attach – вход в рабочее место: zellij-сессия "lc" (создать / подключиться / воскресить)
export PATH="$HOME/.local/bin:$PATH"
S="${LC_SESSION:-lc}"
st=$(zellij ls -n 2>/dev/null | grep -E "^$S ")
if [ -z "$st" ]; then
  exec zellij -s "$S" -n "$HOME/.config/zellij/layouts/lc.kdl"
elif echo "$st" | grep -q EXITED; then
  exec zellij attach -f "$S"
else
  ( sleep 1.5; zellij --session "$S" action go-to-tab 1 ) >/dev/null 2>&1 &
  exec zellij attach "$S"
fi

Шаг 9. Меню сессий на fzf

Когда сессий больше двух, удобно выбирать их из списка с поиском и сразу видеть, что в каждой открыто. Нужны fzf и jq: sudo apt install fzf jq (на Ubuntu 22.04 fzf версии 0.29) или fzf бинарём из релиза на GitHub. Скрипт ниже проверен на fzf 0.29 и 0.74.5.

~/.local/bin/zpick:

#!/usr/bin/env bash
# zpick – меню zellij-сессий на fzf: слева сессии, справа что в них открыто.
# Enter – перейти, новое имя + Enter – создать, Esc – выход.
export PATH="$HOME/.local/bin:$PATH"

card() {   # карточка сессии для превью: состояние, вкладки и что в них запущено
  local s=$1
  echo "$s"
  if zellij ls -n 2>/dev/null | grep -E "^$s " | grep -q EXITED; then
    echo "○ остановлена, Enter воскресит"
    echo
    awk -F'"' '/^ *tab name=/ {print $2} / pane command=/ {print "  " $2}' \
      ~/.cache/zellij/*/session_info/"$s"/session-layout.kdl 2>/dev/null
  else
    echo "● работает · подключено клиентов: $(zellij -s "$s" action list-clients 2>/dev/null | tail -n +2 | wc -l)"
    echo
    jq -rn --argjson tabs "$(zellij -s "$s" action list-tabs -j 2>/dev/null || echo '[]')" \
           --argjson panes "$(zellij -s "$s" action list-panes -a -j 2>/dev/null || echo '[]')" '
      $tabs[] as $t | $t.name,
      ($panes[] | select(.tab_position == $t.position and (.is_plugin | not))
                | "  " + (.terminal_command // "шелл") + (if .is_floating then " (плавающая)" else "" end))'
  fi
}
[ "$1" = --card ] && { card "$2"; exit 0; }

list() {   # ● имя  возраст  – из zellij ls
  zellij ls -n 2>/dev/null | sed -E 's/^([^ ]+) \[Created ([^]]*) ago\](.*)$/\1\t\2\t\3/' |
    awk -F'\t' '{ printf "%s %-22s %s%s\n", ($3 ~ /EXITED/ ? "○" : "●"), $1, $2, ($3 ~ /current/ ? " · здесь" : "") }'
}

out=$(list | fzf --print-query --reverse --no-sort --info=inline --prompt='сессия> ' \
        --header='Enter – перейти · новое имя – создать · Esc – выход' \
        --preview="$0 --card {2}" --preview-window='down,50%,wrap')
[ $? -eq 130 ] && exit 0
name=$(sed -n 2p <<<"$out" | awk '{print $2}')
name=${name:-$(sed -n 1p <<<"$out")}
[ -n "$name" ] || exit 0
if [ -n "$ZELLIJ" ]; then
  zellij action switch-session "$name"   # уже внутри zellij – переключиться
else
  exec work-attach "$name"               # из шелла – войти
fi

chmod +x ~/.local/bin/zpick

В списке у каждой сессии значок: ● – работает, ○ – сервер остановлен. Внизу карточка выбранной сессии: её вкладки и что в каждой запущено. У живой сессии это берётся из zellij action list-tabs и list-panes, у остановленной – из сохранённой раскладки в ~/.cache/zellij, так что видно, что поднимется после воскрешения. --print-query нужен для новых сессий: если набрать имя, которого нет в списке, скрипт получит набранный текст и создаст сессию с этим именем. Внутри zellij переменная ZELLIJ задана, и скрипт переключает текущий терминал на другую сессию через zellij action switch-session. Той же командой создаётся сессия с новым именем (раскладка у неё стандартная, work применяется только при входе из шелла) и воскрешается остановленная.

Чтобы меню открывалось плавающим окном поверх любой вкладки, в config.kdl в блок shared_except "locked" { добавляется одна строка:

        bind "Alt s" { Run "zpick" { floating true; close_on_exit true; name "сессии"; }; }

В пресете Default сочетание Alt+s свободно. После переподключения к сессии Alt+s открывает окно "сессии" со списком, выбор переключает сессию, окно закрывается само (close_on_exit).

На главном сервере то же меню (lc-pick) работает поверх реестра сессий агентов со всех четырёх серверов. Enter открывает сессию агента во вкладке или переходит в уже открытую. Есть клавиши завершить, скрыть и обновить, в превью – карточка сессии. Реестр – отдельный скрипт под эту задачу, поэтому здесь показан общий вариант над zellij ls. Принцип тот же: fzf над списком, Alt+s через Run, вкладка меню в раскладке.

Веб-клиент

В zellij встроен веб-сервер: сессию можно открыть из браузера. По умолчанию он выключен. Запускается командой zellij web, вход по токену из zellij web --create-token, слушает 127.0.0.1:8082 (zellij-client/src/web_client/mod.rs:96-99). Сессии, запущенные из терминала, в браузер по умолчанию не отдаются (web_sharing, по умолчанию "off"). Общий доступ для такой сессии включается в окне Share (Ctrl+o → s). В этой статье веб-клиент не прогонялся, подробности – в документации zellij.

Оформление

Цвета, рамки и стрелки меняются в том же ~/.config/zellij/config.kdl, по одной строке на настройку. Новая сессия подхватывает их при запуске.

В zellij 0.45.1 встроена 41 тема (zellij-utils/src/consts.rs:24), среди них catppuccin, dracula, gruvbox, nord, solarized и tokyo-night. Полный список – каталог zellij-utils/assets/themes в репозитории zellij. Если терминал сам переключает светлую и тёмную схему, zellij может следовать за ним, для этого нужны обе строки: theme_dark "nightfox" и theme_light "dayfox" (zellij-utils/assets/config/default.kdl:370-376, на стенде не проверялось).

Итого

На сервере теперь работает сессия, которая переживает отключение, падение сервера zellij и обрыв ssh. Вход – функцией w, выбор сессии – по Alt+s. Команды и клавиши из статьи одной таблицей: