dumbwareio/dumbterm repository overview

⁠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.
• 🔒 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 Bullseye-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).

1. Install dependencies:

npm install

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

⁠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:

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}

⁠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 restarts
• Direct Selection: Use number shortcuts (1-9) to quickly switch between the first 9 terminals

⁠Security

We're dumb, but not stupid. Use a full-featured auth provider for production use.

• https://github.com/goauthentik/authentik⁠ (More difficult to set up, but production ready)
• https://github.com/authelia/authelia⁠
• https://github.com/steveiliop56/tinyauth⁠ (Easy with docker compose integration)

⁠Features

• Variable-length PIN support (numeric)
• Constant-time PIN comparison
• Brute force protection:
  • 5 attempts maximum
  • 15-minute lockout after failed attempts
  • IP-based tracking
• Secure cookie handling
• Session-based authentication
• CORS support for origin restrictions (optional)
• HTTPS support (when configured with proper BASE_URL)

⁠Technical Details

⁠Stack

• Backend: Node.js (>=20.0.0) with Express
• Frontend: XTerm.js for terminal emulation
• Container: Docker with Debian Bullseye base
• Terminal: node-pty for process spawning
• Communication: WebSockets for real-time terminal I/O
• Security: cors for cross-origin requests

⁠Dependencies

• express: Web framework
• node-pty: Terminal process spawning
• xterm: Terminal frontend
• ws: WebSocket server
• cookie-parser: Cookie handling
• express-session: Session management
• cors: security for cross-origin requests

⁠Supported XTerm Addons

DumbTerm includes the following XTerm.js addons to enhance your terminal experience:

⁠Links

• GitHub: github.com/dumbwareio/dumbterm⁠
• Docker Hub: hub.docker.com/r/dumbwareio/dumbterm⁠

⁠Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commits
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See Development Guide for local setup and guidelines.

Made with ❤️ by DumbWareio⁠ & gitmotion⁠

⁠🌐 Check Us Out

• Website: dumbware.io⁠
• Buy Us a Coffee: buymeacoffee.com/dumbware⁠ ☕
• Join the Chaos: Discord⁠ 💬

⁠Future Features

• Additional authentication methods