cplieger/web-terminal-server repository overview

⁠web-terminal-server

web-terminal-server puts a shell in your browser, on a phone or a desktop, running in a container on your server. Each tab runs bash or a command you choose, and works on the folders you mount into the container.

⁠What it does

Use a terminal on your server from any browser, and pick it up again from any device.

• Gives each tab its own terminal, with a two-pane split view for two at once.
• Works on a phone, with on-screen keys for Tab, Esc, the arrows, Enter and Ctrl.
• Keeps every terminal running when you close the page, and reopens the same tabs on any device.
• Names each tab after what runs in it, or after a name you type.

⁠Who it is for

web-terminal-server is built for people who want a shell on their own server from a phone or a laptop, with nothing to install on them. Everyone who logs in shares the same tabs, and restarting the container ends them.

You need a Docker host, and a private network or a reverse proxy with a login in front of it.

Other tools suit a different setup:

• Consider ttyd⁠ if you want a single command-line tool that shares a terminal, read-only by default.
• Consider WeTTY⁠ if you want a browser login to SSH on any host.
• Consider Web Terminal for Kiro⁠, by the same author, if you want the Kiro agent in each tab.

web-terminal-server is free software under the MPL-2.0 license.

⁠Pull

docker pull cplieger/web-terminal-server:latest

Also published to ghcr.io/cplieger/web-terminal-server with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for web-terminal-server. See the README for all configuration options and hardening.
services:
  web-terminal-server:
    image: ghcr.io/cplieger/web-terminal-server:latest
    container_name: web-terminal-server
    restart: unless-stopped
    # Required. An init at PID 1 cleans up the processes each terminal leaves behind.
    init: true

    environment:
      # Change this before the first start. Without a password there is no login.
      AUTH_PASSWORD: "your-terminal-password"
      # Every host name or IP you open the terminal at. Any other name is refused.
      ALLOWED_HOSTS: "localhost,term.example.com"
      # The folder each new terminal starts in. It must exist in the container.
      WORK_DIR: "/work"

    ports:
      # Reachable from this host only. Read README "Security" before opening it wider.
      - "127.0.0.1:7681:7681"

    volumes:
      # The container runs as root, so files created here belong to root on the host.
      - "./work:/work"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How web-terminal-server works⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

MPL-2.0. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.

The image redistributes two web fonts under their own licences, each served beside the font it covers. Monaspace Neon NF is under the SIL Open Font License 1.1 (/vendor/fonts/MonaspaceNeonNF-LICENSE). Web Terminal Glyphs, the tiling overlay listed ahead of it, is under Apache-2.0 (/vendor/fonts/WebTerminalGlyphs-LICENSE, with its /vendor/fonts/WebTerminalGlyphs-NOTICE).