feat: DevDesk v0.1.0, a persistent browser terminal for Claude Code

ttyd serves a single-file xterm.js UI styled with the LotusGuild TDS (web_template base.css). Sessions live in a dedicated tmux server unit (devdesk-tmux.service), so restarting or upgrading the web unit never stops Claude. Each named session maps to a project directory. A Claude SessionStart hook records the conversation ID, so after a reboot the session resumes that exact conversation. - bin/devdesk: attach / new / ls / end / pick, with an fzf picker - ttyd requires a credential that NPM injects; origin check enabled - debian/: dh 13 with --no-stop-on-upgrade for the tmux unit, bundled sha256-verified ttyd 1.7.7, lintian overrides, man page - CI: lint, test, build, smoke-test, artifact; v* tags publish to the Gitea apt registry and create a release Refs: tinker ticket 887531976 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 23:11:07 -04:00
commit 07a41bd625
52 changed files with 10769 additions and 0 deletions
@@ -0,0 +1,7 @@
+devdesk (0.1.0) bookworm; urgency=medium
+
+  * Initial release: persistent browser terminal for Claude Code
+    (ttyd + tmux) with LotusGuild TDS styling, multiple named sessions,
+    per-session conversation resume and Debian packaging.
+
+ -- Jared Vititoe <jjvititoe1@gmail.com>  Tue, 06 Oct 2026 22:58:26 -0400
@@ -0,0 +1,24 @@
+Source: devdesk
+Section: admin
+Priority: optional
+Maintainer: Jared Vititoe <jjvititoe1@gmail.com>
+# Node.js >= 18 with npm is also needed to build the web UI (provided by the CI image / nodesource).
+Build-Depends: debhelper-compat (= 13), bats, ca-certificates, curl, jq, tmux (>= 3.2)
+Standards-Version: 4.6.2
+Homepage: https://code.lotusguild.org/LotusGuild/devdesk
+Vcs-Browser: https://code.lotusguild.org/LotusGuild/devdesk
+Vcs-Git: https://code.lotusguild.org/LotusGuild/devdesk.git
+Rules-Requires-Root: no
+
+Package: devdesk
+Architecture: amd64
+Depends: ${misc:Depends}, fzf, jq, tmux (>= 3.2)
+Description: persistent browser terminal for Claude Code
+ DevDesk serves a LotusGuild-styled web terminal (ttyd with an xterm.js
+ front end) whose sessions live in a dedicated tmux server. Closing the
+ browser, restarting the web service or upgrading the package never stops
+ the Claude Code processes; after a reboot each named session resumes its
+ own conversation.
+ .
+ Authentication and TLS are expected to be handled by a reverse proxy
+ (Nginx Proxy Manager + Authelia), which also injects the ttyd credential.
@@ -0,0 +1,166 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: devdesk
+Source: https://code.lotusguild.org/LotusGuild/devdesk
+Comment: The binary package also contains third-party components:
+ the upstream ttyd static build (/usr/lib/devdesk/bin/ttyd), and xterm.js,
+ its addons and JetBrains Mono bundled into /usr/share/devdesk/index.html.
+
+Files: *
+Copyright: 2026 Jared Vititoe <jjvititoe1@gmail.com>
+License: MIT
+
+Files: vendor/web_template/*
+Copyright: 2026 Jared Vititoe
+License: MIT
+Comment: LotusGuild web_template design system (base.css).
+
+Files: vendor/ttyd/*
+Copyright: 2016-2022 Shuanglei Tao <tsl0922@gmail.com>
+License: MIT
+Comment: ttyd 1.7.7 static build (ttyd.x86_64), fetched at build time and
+ verified against SHA256SUMS. The static binary also links:
+ libwebsockets (MIT, Copyright 2010-2020 Andy Green and contributors),
+ libuv (MIT, Copyright Joyent, Inc. and other Node contributors),
+ json-c (MIT, Copyright 2009-2012 Eric Haszlakiewicz, 2004-2005 Metaparadigm Pte Ltd),
+ musl libc (MIT, Copyright 2005-2020 Rich Felker et al.),
+ zlib (Zlib, Copyright 1995-2024 Jean-loup Gailly and Mark Adler),
+ mbedtls (Apache-2.0 OR GPL-2.0-or-later, Copyright The Mbed TLS Contributors).
+ See /usr/share/common-licenses/Apache-2.0 and /usr/share/common-licenses/GPL-2.
+
+Files: web/*
+Copyright: 2026 Jared Vititoe <jjvititoe1@gmail.com>
+License: MIT
+Comment: Bundled into index.html at build time:
+ xterm.js and @xterm addons (MIT, Copyright 2017-2019 The xterm.js authors,
+ 2014-2016 SourceLair Private Company, 2012-2013 Christopher Jeffrey);
+ JetBrains Mono via @fontsource/jetbrains-mono (OFL-1.1,
+ Copyright 2020 The JetBrains Mono Project Authors).
+
+License: MIT
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+
+License: Zlib
+ This software is provided 'as-is', without any express or implied
+ warranty.  In no event will the authors be held liable for any damages
+ arising from the use of this software.
+ .
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+ .
+ 1. The origin of this software must not be misrepresented; you must not
+    claim that you wrote the original software. If you use this software
+    in a product, an acknowledgment in the product documentation would be
+    appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+    misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+
+License: OFL-1.1
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
+ This license is copied below, and is also available with a FAQ at:
+ http://scripts.sil.org/OFL
+ .
+ .
+ -----------------------------------------------------------
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+ -----------------------------------------------------------
+ .
+ PREAMBLE
+ The goals of the Open Font License (OFL) are to stimulate worldwide
+ development of collaborative font projects, to support the font creation
+ efforts of academic and linguistic communities, and to provide a free and
+ open framework in which fonts may be shared and improved in partnership
+ with others.
+ .
+ The OFL allows the licensed fonts to be used, studied, modified and
+ redistributed freely as long as they are not sold by themselves. The
+ fonts, including any derivative works, can be bundled, embedded,
+ redistributed and/or sold with any software provided that any reserved
+ names are not used by derivative works. The fonts and derivatives,
+ however, cannot be released under any other type of license. The
+ requirement for fonts to remain under this license does not apply
+ to any document created using the fonts or their derivatives.
+ .
+ DEFINITIONS
+ "Font Software" refers to the set of files released by the Copyright
+ Holder(s) under this license and clearly marked as such. This may
+ include source files, build scripts and documentation.
+ .
+ "Reserved Font Name" refers to any names specified as such after the
+ copyright statement(s).
+ .
+ "Original Version" refers to the collection of Font Software components as
+ distributed by the Copyright Holder(s).
+ .
+ "Modified Version" refers to any derivative made by adding to, deleting,
+ or substituting -- in part or in whole -- any of the components of the
+ Original Version, by changing formats or by porting the Font Software to a
+ new environment.
+ .
+ "Author" refers to any designer, engineer, programmer, technical
+ writer or other person who contributed to the Font Software.
+ .
+ PERMISSION & CONDITIONS
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
+ redistribute, and sell modified and unmodified copies of the Font
+ Software, subject to the following conditions:
+ .
+ 1) Neither the Font Software nor any of its individual components,
+ in Original or Modified Versions, may be sold by itself.
+ .
+ 2) Original or Modified Versions of the Font Software may be bundled,
+ redistributed and/or sold with any software, provided that each copy
+ contains the above copyright notice and this license. These can be
+ included either as stand-alone text files, human-readable headers or
+ in the appropriate machine-readable metadata fields within text or
+ binary files as long as those fields can be easily viewed by the user.
+ .
+ 3) No Modified Version of the Font Software may use the Reserved Font
+ Name(s) unless explicit written permission is granted by the corresponding
+ Copyright Holder. This restriction only applies to the primary font name as
+ presented to the users.
+ .
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+ Software shall not be used to promote, endorse or advertise any
+ Modified Version, except to acknowledge the contribution(s) of the
+ Copyright Holder(s) and the Author(s) or with their explicit written
+ permission.
+ .
+ 5) The Font Software, modified or unmodified, in part or in whole,
+ must be distributed entirely under this license, and must not be
+ distributed under any other license. The requirement for fonts to
+ remain under this license does not apply to any document created
+ using the Font Software.
+ .
+ TERMINATION
+ This license becomes null and void if any of the above conditions are
+ not met.
+ .
+ DISCLAIMER
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+ OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,29 @@
+[Unit]
+Description=DevDesk tmux server (persistent Claude Code sessions)
+Documentation=https://code.lotusguild.org/LotusGuild/devdesk
+Wants=network-online.target
+After=network-online.target
+
+# Deliberately an unrestricted root shell host: no ProtectSystem/ProtectHome/PrivateTmp.
+[Service]
+Type=simple
+User=root
+Environment=HOME=/root USER=root LOGNAME=root SHELL=/bin/bash LANG=C.UTF-8
+Environment=PATH=/root/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+EnvironmentFile=-/etc/devdesk/env
+WorkingDirectory=-/root
+RuntimeDirectory=devdesk
+RuntimeDirectoryMode=0700
+StateDirectory=devdesk
+StateDirectoryMode=0700
+ExecStart=/usr/bin/tmux -u -D -S /run/devdesk/tmux.sock -f /usr/share/devdesk/tmux.conf
+ExecStartPost=/usr/lib/devdesk/devdesk-tmux-ready
+# One OOM-killed build inside a session must not take every session down.
+OOMPolicy=continue
+KillMode=mixed
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,3 @@
+README.md
+docs/DEPLOY.md
+docs/npm-advanced.conf
@@ -0,0 +1,4 @@
+# ttyd is the upstream static release (musl, bundled libwebsockets/libuv/json-c/zlib/mbedtls),
+# shipped unmodified and verified against upstream SHA256SUMS. ttyd is not packaged for bookworm.
+devdesk: statically-linked-binary [usr/lib/devdesk/bin/ttyd]
+devdesk: embedded-library zlib [usr/lib/devdesk/bin/ttyd]
@@ -0,0 +1 @@
+docs/devdesk.1
@@ -0,0 +1,22 @@
+#!/bin/sh
+set -e
+
+case "$1" in
+configure)
+    # Credential ttyd requires; NPM injects it as an Authorization header.
+    if [ ! -s /etc/devdesk/secret.env ]; then
+        umask 077
+        secret=$(od -An -tx1 -N24 /dev/urandom | tr -d ' \n')
+        printf 'DEVDESK_CREDENTIAL=devdesk:%s\n' "$secret" >/etc/devdesk/secret.env
+    fi
+    chmod 600 /etc/devdesk/secret.env
+    # Apply tmux.conf changes to a running server without restarting it.
+    if [ -S /run/devdesk/tmux.sock ]; then
+        tmux -N -S /run/devdesk/tmux.sock source-file /usr/share/devdesk/tmux.conf >/dev/null 2>&1 || true
+    fi
+    ;;
+esac
+
+#DEBHELPER#
+
+exit 0
@@ -0,0 +1,11 @@
+#!/bin/sh
+set -e
+
+if [ "$1" = purge ]; then
+    rm -f /etc/devdesk/secret.env
+    rm -rf /var/lib/devdesk
+fi
+
+#DEBHELPER#
+
+exit 0
@@ -0,0 +1,19 @@
+[Unit]
+Description=DevDesk web terminal (ttyd)
+Documentation=https://code.lotusguild.org/LotusGuild/devdesk
+Wants=devdesk-tmux.service network-online.target
+After=devdesk-tmux.service network-online.target
+
+[Service]
+Type=simple
+User=root
+Environment=HOME=/root LANG=C.UTF-8
+Environment=PATH=/root/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+EnvironmentFile=/etc/devdesk/env
+EnvironmentFile=/etc/devdesk/secret.env
+ExecStart=/usr/lib/devdesk/devdesk-serve
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,19 @@
+#!/usr/bin/make -f
+
+%:
+	dh $@
+
+# Build runs `make`, which fetches the pinned ttyd release and verifies its sha256.
+
+# The tmux server unit owns every Claude process: never stop or restart it on
+# upgrade. The web unit (ttyd) is safe to restart and does so after upgrades.
+override_dh_installsystemd:
+	dh_installsystemd --name=devdesk-tmux --no-stop-on-upgrade
+	dh_installsystemd devdesk.service
+
+# ttyd is an upstream static binary; keep it byte-identical to its published checksum.
+override_dh_strip:
+	dh_strip -Xbin/ttyd
+
+override_dh_dwz:
+	dh_dwz -Xbin/ttyd
@@ -0,0 +1 @@
+3.0 (native)