Skip to content
wlanboyPublic

About

Spring Boot Web Shell

Topics

Resources

Stars

8 stars

Watchers

1 watching

Forks

Repository files navigation

Java CI with Maven

WebShell

WebShell is a browser-based terminal frontend for executing shell commands on a remote host. It provides a TUI-like interface directly in the browser — no SSH client, no VPN, no additional tooling required. Useful for quick access to a containerized environment, a dev machine, or any host that is reachable via HTTP.

Features

  • Full-screen terminal UI with macOS-style titlebar
  • Command history navigation via ↑ / ↓ arrow keys
  • Inline output — commands and results appear in sequence, like a real shell session
  • Built-in commands: clear, help
  • Commands with a non-zero exit code are highlighted as errors
  • 30-second execution timeout with forced process termination
  • Form-based login with BCrypt-hashed passwords (Spring Security)
  • Runs as a single self-contained JAR or Docker container

WebShell TUI

Dependencies

  • Java 25
  • Maven 3.9

Users

Two users are pre-configured in application.yml:

Username Role
user SHELL
test SHELL

Passwords are stored as BCrypt hashes. To set your own passwords:

  1. Generate a hash with BCryptPasswordEncoder
  2. Replace the values for userpassword and testpassword in application.yml

Build

mvn package

Run

Windows

java -jar target\webshell-0.1.2-SNAPSHOT.jar

Linux

java -jar target/webshell-0.1.2-SNAPSHOT.jar

Port

The default port is 8001. Override with the PORT environment variable:

PORT=9000 java -jar target/webshell-0.1.2-SNAPSHOT.jar

Docker Hub

https://hub.docker.com/r/wlanboy/webshell

Docker build

docker build -f Dockerfile.25 -t webshell:latest .

Docker run

docker run --name webshell -d -p 8080:8001 -v /tmp:/tmp wlanboy/webshell:latest

Override port:

docker run --name webshell -d -p 9000:9000 -e PORT=9000 -v /tmp:/tmp wlanboy/webshell:latest

Behavior

  • Commands run without a shell: no pipes, redirects, variables or globs. Arguments can be quoted with 'single' or "double" quotes, and \ escapes a single character.
  • Commands run in /tmp as working directory.
  • Commands that run longer than 30 seconds are killed together with their child processes.
  • Output is limited to 1 MB. A command that writes more gets killed.
  • A non-zero exit code, a timeout or a killed command returns HTTP 422, and the UI shows the output as an error.
  • Empty or unparsable command lines return HTTP 400.
  • stderr is merged into stdout.
  • /execute requires a CSRF token. The server sets it as XSRF-TOKEN cookie, and the UI sends it back as X-XSRF-TOKEN header.

Working directory, timeout and output limit are set in application.yml and can be overridden with environment variables:

Property Environment variable Default
webshell.workdir WEBSHELL_WORKDIR /tmp
webshell.timeout WEBSHELL_TIMEOUT 30s
webshell.max-output WEBSHELL_MAX_OUTPUT 1MB

About

Spring Boot Web Shell

Topics

Resources

Stars

8 stars

Watchers

1 watching

Forks

Used by

Contributors

Languages