DumbTerm: A Simple Web-Based Terminal Emulator with Starship Integration

Introduction

DumbTerm, developed by DumbWareio, is a remarkably simple yet powerful web-based terminal emulator. Written primarily in JavaScript, it allows users to access a fully functional command-line interface directly through their web browser, from any device. This project stands out by offering a pre-configured environment with essential tools and the highly customizable Starship prompt, all easily deployable via Docker. It's designed for scenarios ranging from creating sandboxed testing environments to securely accessing remote server CLIs.

Installation

Getting started with DumbTerm is straightforward, with Docker being the recommended method for quick deployment.

Prerequisites

Docker (recommended)
Node.js >=20.0.0 (for local development)

Docker Quick Start

For a simple setup, you can run DumbTerm using a single Docker command. This method leverages a Debian 13 Trixie-based container with pre-installed utilities.

docker run -p 3000:3000 \
  -v ./data:/root/data \
  -v ./config:/root/.config \
  -e DUMBTERM_PIN=1234 \
  -e SITE_TITLE=DumbTerm \
  -e BASE_URL=http://localhost:3000 \
  -e ALLOWED_ORIGINS=http://localhost:3000 \
  -e ENABLE_STARSHIP=true \
  -e TZ=America/Los_Angeles \
  -e LOCKOUT_TIME=15 \
  -e MAX_SESSION_AGE=24 \
  dumbwareio/dumbterm:latest

After running the command, navigate to http://localhost:3000 in your browser. If a PIN is configured, enter it to access your web terminal.

Docker Compose (Recommended)

For more customized deployments, Docker Compose offers a flexible solution. Create a docker-compose.yml file similar to the example below:

services:
  dumbterm:
    image: dumbwareio/dumbterm:latest
    container_name: dumbterm
    restart: unless-stopped
    ports:
      - ${DUMBTERM_PORT:-3000}:3000
    volumes:
      - ${DUMBTERM_CONFIG:-./config}:/root/.config
      - ${DUMBTERM_DATA_DIR:-./data}:/root/data
    environment:
      TZ: ${DUMBTERM_TZ:-America/Los_Angeles}
      SITE_TITLE: ${DUMBTERM_SITE_TITLE:-DumbTerm}
      DUMBTERM_PIN: ${DUMBTERM_PIN:-1234}
      BASE_URL: ${DUMBTERM_BASE_URL:-http://localhost:3000}
      ENABLE_STARSHIP: ${ENABLE_STARSHIP:-true}
      LOCKOUT_TIME: ${DUMBTERM_LOCKOUT_TIME:-15}
      MAX_SESSION_AGE: ${DUMBTERM_MAX_SESSION_AGE:-24}

Then, simply run:

docker compose up -d

For detailed local installation instructions and Windows-specific notes, please refer to the official GitHub repository's README.

Examples

DumbTerm is versatile and can be applied in various scenarios:

Sandboxed Development: Create isolated environments for testing scripts, code, or applications without cluttering your local machine. Emulate a VPS or showcase examples easily.
Remote CLI Access: Access client CLIs or your server's terminal through a web browser, providing convenience and flexibility.
Self-Hosting: Deploy DumbTerm behind a reverse proxy, authentication provider (like Authentik or Authelia), or Cloudflare Tunnels for secure external access. It serves as an excellent alternative to other web terminals such as ttyd or shellinabox.
Demonstrations: Utilize the demo mode (DEMO_MODE=true) for testing and showcasing the terminal's capabilities with a simulated environment.

Why Use It?

DumbTerm offers a compelling set of features that make it an attractive choice for web-based terminal access:

Accessibility: Access your terminal from any device with a web browser, offering unparalleled flexibility.
Rich Environment: Comes with a Debian-based Docker image pre-loaded with essential utilities like git, vim, nano, htop, curl, wget, ssh, and python3.
Enhanced User Experience: Integrates the Starship prompt for a beautiful, informative, and highly customizable terminal experience, including git status and command duration.
Security Features: Includes optional PIN protection, brute-force lockout, secure cookie handling, and CORS support, making it suitable for secure deployments when combined with external authentication providers.
Modern Web Features: Supports dark mode, responsive design, PWA (Progressive Web App) for mobile and desktop, and XTerm.js for fast, efficient terminal rendering.
Tab Management: Features drag-and-drop tab reordering, renaming, and persistence of terminal history across sessions.

DumbTerm: A Simple Web-Based Terminal Emulator with Starship Integration

Summary

Repository Info

Tags