Web-Terminal Documentation

A secure web-based terminal application with OIDC authentication and comprehensive API documentation.

Get started now View API Reference View on GitHub

---

Getting started

Web-Terminal - A secure web-based terminal application providing shell access through your browser with OIDC authentication support.

Key Features

• Web-Based Terminal: Access shell sessions through your browser using xterm.js
• Comprehensive Authentication: Basic Auth, JWT sessions, and OIDC provider support (Google, Microsoft, etc.)
• Session Management: Persistent terminal sessions with automatic reconnection
• WebSocket Communication: Real-time bidirectional terminal I/O via WebSocket
• API Documentation: Comprehensive Swagger UI for API endpoints
• Multi-Platform: DEBIAN and OmniOS packages with professional CI/CD

Architecture

graph TD
    A[Web Browser] -->|HTTPS| B[Web-Terminal Server]
    B -->|WebSocket| C[PTY Process]
    C -->|Shell| D[PowerShell/Bash]
    B -->|Authentication| E[JWT/OIDC]
    B -->|Session Data| F[(Database)]

View Detailed Architecture

Quick start

1. Installation: Install via DEBIAN package or build from source
2. Configuration: Edit /etc/web-terminal/config.yaml for your environment
3. Authentication: Configure users and OIDC providers
4. Access Terminal: Login via web browser and access shell
5. Try API: Visit the API documentation for REST API testing

Core Capabilities

Terminal Access

• Browser-Based Shell: Full terminal access via xterm.js in your browser
• Session Persistence: Terminal sessions survive page refreshes and disconnections
• WebSocket Communication: Real-time bidirectional I/O between browser and shell
• Automatic Reconnection: Sessions automatically reconnect after network interruptions

Authentication Options

• Basic Auth: Simple username/password authentication
• JWT Sessions: Secure browser-based sessions
• OIDC Integration: Sign in with Google, Microsoft, or other OIDC providers

API Access

• REST API: Terminal session management via REST endpoints
• Swagger UI: Interactive API documentation and testing
• Session Control: Start, stop, and manage terminal sessions programmatically

Documentation

Comprehensive documentation for all aspects of Web-Terminal:

• API Reference - Interactive Swagger UI documentation
• Getting Started Guide - Step-by-step setup
• Installation Guide - DEBIAN and OmniOS packages
• Authentication Guide - User management and API keys
• Configuration Reference - Complete config options

---

About the project

Web-Terminal is developed in © 2025 by STARTcloud.

License

Web-Terminal is distributed under a GPL-3.0 license.

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in our GitHub repo.

Thank you to the contributors of Web-Terminal

• 
• 
• 
• 

Code of Conduct

Web-Terminal is committed to fostering a welcoming community.

View our Code of Conduct on our GitHub repository.