DumbTerm

A stupidly simple web-based terminal emulator, with common tools and Starship enabled! 🚀

• Access your terminal from any device with a web browser
• Execute commands just like in a native terminal
• Starship prompt provides a beautiful terminal experience with git status, command duration, etc.
• PIN protection (recommended) prevents unauthorized access
• Use the data directory to persist files between container restarts
• Demo mode available for testing and demonstrations - simulated terminal (set DEMO_MODE=true)

Use cases:

• Build with docker: To create a sandboxed environment for testing scripts, code, applications, emulate a VPS, showcase examples and more. All without having to install dependencies on your local machine!
• Build locally: To access your client's cli/terminal through your browser instead!
• Self-hosting: Put behind a reverse proxy, auth provider (like authentik, authelia, etc), Cloudflare tunnels with application access rules, etc for secure external access.
• Another alternative to web terminals such as ttyd, shellinabox, etc

Table of Contents

• Features
• Quick Start
• Prerequisites
• Option 1: Docker (For Dummies)
• Option 2: Docker Compose (Recommended)
• Option 3: Running Locally
  • Windows-specific
• Configuration
• Environment Variables
• Starship usage
  • Starship Presets
• Keyboard Shortcuts
• Terminal Search
• Tab Management
• Security
• Features
• Technical Details
• Stack
• Dependencies
• Supported XTerm Addons
• Links
• Contributing
• Check Us Out
• Future Features

Features

• 🖥️ Web-based terminal access from anywhere
• 🌙 Dark mode support
• 📱 Responsive design for mobile and desktop
• 🐳 Docker support (Debian-based container)
• 🔧 Pre-installed utilities: starship, nerdfonts, apt-utils, curl, wget, ssh, git, vim, nano, htop, net-tools, iputils-ping, traceroute, fontconfig, unzip, locales, python3, etc.
• 🔒 Optional PIN protection (numeric)
• ✨ Starship prompt integration for beautiful terminal experience
• 🔍 Terminal search functionality (ctrl+f or cmd+f)
• 📂 Custom volume mappings
• 🔗 In-terminal hyperlinks
• ⌨️ Keyboard shortcuts for common actions
• 📑 Tab Management:
• Drag and drop reordering of tabs
• Double-click to rename tabs
• Direct tab selection with shortcuts
• Terminal history persistence across sessions
• 📱 PWA Support for mobile and desktop
• ⚡ XTerm.js for fast terminal rendering

Quick Start

Prerequisites

• Docker (recommended)
• Node.js >=20.0.0 (for local development)
• Windows-specific: WSL or Node.js v16 - Option 3: Running Locally

Option 1: Docker (For Dummies)

• Docker method uses a pre-installed Debian 13 Trixie-based container/environment.

# Pull and run with one command
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

1. Go to http://localhost:3000
2. Enter your PIN if configured
3. Enjoy your web-based terminal!

Option 2: Docker Compose (For Dummies who like customizing) - Recommended

Create a docker-compose.yml file or use the provided one:

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:
      # Container timezone
      TZ: ${DUMBTERM_TZ:-America/Los_Angeles}
      # The title shown in the web interface
      SITE_TITLE: ${DUMBTERM_SITE_TITLE:-DumbTerm}
      # Recommended PIN protection (leave empty to disable)
      DUMBTERM_PIN: ${DUMBTERM_PIN:-1234}
      # The base URL for the application
      BASE_URL: ${DUMBTERM_BASE_URL:-http://localhost:3000}
      ENABLE_STARSHIP: ${ENABLE_STARSHIP:-true}
      LOCKOUT_TIME: ${DUMBTERM_LOCKOUT_TIME:-15} # Minutes
      # Session duration in hours before requiring re-authentication
      MAX_SESSION_AGE: ${DUMBTERM_MAX_SESSION_AGE:-24} # Hours
      # (OPTIONAL) - List of allowed origins for CORS
      # ALLOWED_ORIGINS: ${DUMBTERM_ALLOWED_ORIGINS:-http://localhost:3000}

Then run:

docker compose up -d

Option 3: Running Locally (For Developers)

• Local method will use your local terminal environment (Windows: Powershell, Mac / Linux: bash).

• Install dependencies:

npm install

[!TIP]

Windows specific:

• If you encounter issues with node-pty you can try using Windows Subsystem for Linux (WSL) or may need to install:
• Node.js v16 (Look into nvm for windows for multi node version support):
• winget install CoreyButler.NVMforWindows
• with nvm installed use: nvm install 16 && nvm use 16
• windows-build-tools through Visual Studio Installer MSVC v142 - VS 2019 C++ {arch} Build Tools
• Contact us or View the official Microsoft documentation for more details

1. cp .env.example .env > Set environment variables in .env:

PORT=3000                  # Port to run the server on
DUMBTERM_PIN=1234          # Optional PIN protection
SITE_TITLE=DumbTerm        # Custom site title
BASE_URL=http://localhost:3000  # Base URL for the application

1. Start the server:

npm start

Configuration

Environment Variables

Variable	Description	Default	Required
PORT	Server port	3000	No
BASE_URL	Base URL for the application	http://localhost:PORT	No
DUMBTERM_PIN	PIN protection (numeric)	None	No
SITE_TITLE	Site title displayed in header	DumbTerm	No
TZ	Container timezone	America/Los_Angeles	No
ENABLE_STARSHIP	Enable Starship prompt (docker only)	true	No
NODE_ENV	Node environment mode (development or production)	production	No
ALLOWED_ORIGINS	Allowed CORS origins (comma-separated list)	* (all origins)	No
DEBUG	Enable debug logging	FALSE	No
LOCKOUT_TIME	Custom Pin Lockout Time (in minutes)	15	No
MAX_SESSION_AGE	Duration of authenticated session (in hours)	24	No
DEMO_MODE	Enable demo mode with simulated terminal	false	No

Starship usage

• Starship is a cross-shell prompt that provides a beautiful terminal experience.
• It is enabled by default in the Docker image and is the recommended method.
• To disable it, set ENABLE_STARSHIP to false in your environment variables.
• You can customize the Starship prompt by using one of the following steps:

1. Use a preset configuration from starship.

Starship Presets:

[!TIP] copy and paste one of the starship preset commands below into DumbTerm and that's it!

Example Preset Command:

[!WARNING] > Note: If running locally or mapped volume to your actual starship.toml config, the preset commands will overwrite your existing starship.toml file. Make sure to back it up as needed.

View All Starship Presets:

Preset Name	Command	Preview
Nerd Font Symbols	starship preset nerd-font-symbols -o ~/.config/starship.toml
Bracketed Segments	starship preset bracketed-segments -o ~/.config/starship.toml
Plain Text Symbols	starship preset plain-text-symbols -o ~/.config/starship.toml
No Runtime Versions	starship preset no-runtime-versions -o ~/.config/starship.toml
No Empty Icons	starship preset no-empty-icons -o ~/.config/starship.toml
Pure Prompt	starship preset pure-preset -o ~/.config/starship.toml
Pastel Powerline	starship preset pastel-powerline -o ~/.config/starship.toml
Tokyo Night (DumbTerm Default with mods)	starship preset tokyo-night -o ~/.config/starship.toml
Gruvbox Rainbow	starship preset gruvbox-rainbow -o ~/.config/starship.toml
Jetpack	starship preset jetpack -o ~/.config/starship.toml
No Nerd Fonts	starship preset no-nerd-font -o ~/.config/starship.toml	n/a

• You can also view the available presets by running starship preset -l in DumbTerm.

For more details, visit the Starship Presets page.

2. Modify the ~/.config/starship.toml file in your set volume mount or within the container.

• The default configuration is located in /root/.config/starship.toml.
• You can also mount a custom starship.toml file to the container using Docker volumes.
• Update or add your custom configurations to starship.toml.
• Visit Starship Configuration for more information on customizing the prompt.

3. Running locally

• If you are running DumbTerm locally, DumbTerm will inherit your current styles.
• Meaning if you already have starship enabled locally, you should be able to see your current styles accordingly.
• You must install Starship on your local machine if you wish to use DumbTerm with starship locally.
• To install Starship, follow the instructions on the Starship installation page.

Keyboard Shortcuts

DumbTerm provides a comprehensive set of keyboard shortcuts for efficient terminal management. The modifier keys vary by operating system:

• Windows/Linux: Ctrl+Alt+{key}
• macOS: Ctrl+Cmd+{key}

Action	Windows/Linux	macOS
New Terminal	Ctrl+Alt+T	Ctrl+Cmd+T
Close Terminal	Ctrl+Alt+W	Ctrl+Cmd+W
Rename Terminal	Ctrl+Alt+R	Ctrl+Cmd+R
Search in Terminal	Ctrl+F	Cmd+F
Next Terminal	Ctrl+Alt+> or Ctrl+Alt+.	Ctrl+Cmd+> or Ctrl+Cmd+.
Previous Terminal	Ctrl+Alt+< or Ctrl+Alt+,	Ctrl+Cmd+< or Ctrl+Cmd+,
Switch to Terminal 1-9	Ctrl+Alt+[1-9]	Ctrl+Cmd+[1-9]

Terminal Search

• Press Ctrl+F (Windows/Linux) or Cmd+F (macOS) to open the search bar
• Use Up/Down arrow buttons or Enter/Shift+Enter to cycle through matches
• Press Escape or the close button to exit search mode

Tab Management

• Drag and Drop: Click and drag tabs to reorder them
• Rename: Double-click a tab or use the keyboard shortcut to rename it
• History: Terminal content is automatically preserved across browser refreshes and resta