dengkx/webterm

Fetch the repository succeeded.

richgiteeai

Watch

Unwatch Watching Releases Only Ignoring

1 Star 0 Fork 0

dengkx/webterm

Code Issues 0 Pull Requests 0 Wiki Insights Pipelines

Service

Tencent Cloud Serverless

Create your Gitee Account

Explore and code with more than 14 million developers,Free private repositories !:)

Already have an account? Sign in

Clone or Download

Clone/Download

HTTPS SSH SVN SVN+SSH Download ZIP

Prompt

To download the code, please copy the following command and execute it in the terminal

To ensure that your submitted code identity is correctly recognized by Gitee, please execute the following command.

git config --global user.name userName 
git config --global user.email userEmail

When using the SSH protocol for the first time to clone or push code, follow the prompts below to complete the SSH configuration.

1 Generate RSA keys.

2 Obtain the content of the RSA public key and configure it in SSH Public Keys

To use SVN on Gitee, please visit the usage guide

When using the HTTPS protocol, the command line will prompt for account and password verification as follows. For security reasons, Gitee recommends configure and use personal access tokens instead of login passwords for cloning, pushing, and other operations.

Username for 'https://gitee.com': userName

Password for 'https://userName@gitee.com': # Private Token

New file Create Diagram file

New submodule

Upload file

Branches 15

Tags 21

contribute

Sync branch

Create Pull Request

known more

See difference Through Pull Request Sync

Sync branch

Through Pull Request Sync

A Pull Request will be created to the current
branch and will be merged in to complete the sync

Vikrant Chaudhary build: Resolve lifetime elision warning wi... b6064e7

127 commits

.github

agent

core

docs

frontend

relay

schema

scripts

.gitignore

.node-version

CHANGELOG.md

Cargo.lock

Cargo.toml

LICENCE.md

README.md

rust-toolchain.toml

rustfmt.toml

README

MIT

# Webterm

> [!CAUTION]
>
> **🐉 Here be dragons!**
>
> This project is in early development phase and not yet ready for production use. Features are incomplete and may
> undergo significant changes. Please treat this as experimental and expect nothing to work.

**Webterm** (short for "web terminal") is a lightweight and efficient tool for providing secure, browser-based access to
remote terminals. It is designed for environments where devices, servers, or containers cannot be accessed directly over
the public network — such as those behind firewalls, on private networks, or with blocked inbound ports. It is also
suitable for devices with dynamic or temporary IP addresses where traditional SSH access is either not feasible or not
desirable.

## Features

Written in Rust, Webterm is built from the ground up for security, performance, and extensibility.

- 🪶 **Extremely Lightweight**: Uses less than 10 MB of memory when idle.
- 🌍 **Works Anywhere**: Operates behind firewalls and NATs without open inbound ports.
- 🌐 **Browser-Based Terminal**: Access terminals securely via your web browser.
- 🔒 **Secure by Design**: Uses end-to-end encryption and a stateless relay that only passes encrypted data through.
- ⚡ **Optimised Communication**: Utilises [FlatBuffers](https://en.wikipedia.org/wiki/FlatBuffers) for high-performance,
 efficient data transmission.
- 🔄 **Persistent Sessions**: Leave a session open and reconnect days or weeks later, even if the server's IP address
 changes.
- 📟 **Multiple Terminals**: Open multiple terminals on the same device in a single session.

## Use Cases

* **Remote Access**: Connect to servers and devices securely using a browser.
* **Containers**: Manage Docker instances without opening network ports.
* **Embedded & IoT**: Run on Raspberry Pi and other Linux-based low-power systems.
* **Personal Devices**: Enable secure remote access to your home server or laptop.

## Quickstart

1. Install the Webterm agent:
 ```bash
 # This command will install a single binary at /usr/bin/webterm-agent, no other files will be touched
 curl -sSfL https://webterm.run/install.sh | bash
 ```

2. Start the Webterm agent:
 ```bash
 # Pass --daemon to run the agent in the background
 webterm-agent --device-name <DEVICE_NAME> --secret-key <SECRET_KEY>
 ```

3. Access the terminal on [https://webterm.run](https://webterm.run) using the same credentials.

_(Binary distributions and detailed installation instructions for more platforms are coming soon.)_

## Build from Source

See doc: [Build Instructions](./docs/build-instructions.md).

## Screenshots

![image](https://github.com/user-attachments/assets/06240ef7-e51d-4176-a957-87948688f8a6)

## How It Works

```mermaid
flowchart LR
 A["Frontend (Browser)"] <--"WebSocket"--> B[Relay] <--"WebSocket"--> C["Agent (Device)"]
```

Webterm is made of 3 components:

1. **Agent**: A lightweight binary that runs on your server or container.
2. **Relay**: A stateless server that routes communication between the Agent and the Frontend.
3. **Frontend (Browser)**: A fully static website used to access the terminal from any modern browser.

When `webterm-agent` runs on a device, it registers itself to a Relay with the specified _Device Name_ and keeps a
persistent WebSocket connection open. Whenever a Frontend requests to connect a _Device Name_, the Relay
requests a connection to the Agent, which verifies the Frontend using
[zero-knowledge proof](https://en.wikipedia.org/wiki/Zero-knowledge_proof). Upon successful verification, an encrypted
session is established using a key derived via [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2). The original _Secret
Key_ is never transmitted.

## Advantages over SSH

While [SSH](https://en.wikipedia.org/wiki/Secure_Shell) is a powerful tool, **Webterm** addresses scenarios in which SSH
may not be feasible:

* **Servers behind firewalls** where inbound connections are blocked.
* **Private IP-only** instances (e.g., behind a load balancer or NAT).
* **No open ports** or the inability to forward additional ports.
* **Home servers** where IP address may change frequently.
* **Browser-based** so you can connect from mobile devices or restricted environments with no installed SSH client.
* **Session persistence**: Come back to your terminal next day or next week; it will still be running.

## Security

**Webterm** was built with security at its core:

* **Zero-knowledge proof**: Authentication happens
 using [zero-knowledge proof](https://en.wikipedia.org/wiki/Zero-knowledge_proof). The secret key is never sent over
 the wire and the key for communication is derived using [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2).
* **End-to-end encryption**: All communication is encrypted
 using [AES256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode).
* **Zero-trust Relay**: The relay only forwards encrypted messages and cannot read them.
* **Static frontend**: The entire frontend code is within browser un-minified, making it easier to audit.
* **On-premise hosting**: Both frontend and relay can be hosted on your own infrastructure and agents can be configured
 to only connect to these relays for complete control (see self-hosting docs for [relay](./docs/deploy-relay.md)
 and [frontend](./docs/deploy-frontend.md))

## FAQs

* **Q**: _How to install the agent if I need terminal access in the first place?_

**A**: Webterm can be installed via SSH, CI/CD pipelines, system provisioning, cloud-init scripts, container scripts,
 or configuration
 management tools - once installed, it eliminates the need for future SSH access.

* **Q**: _What platforms does Webterm support?_

**A**: At present, only Linux bases systems are supported.

* **Q**: _Can I run my own Relay?_

**A**: Yes, both the frontend and relay can be hosted on-premise or on your private cloud for complete control.

* **Q**: _What is a `Device Name` and what is a `Device Subname`?_

**A**: Webterm allows multiple devices to connect with the same name to a relay. This makes it easier to manage
 multiple devices under the same name. For e.g., if you've an automation script that installs and runs Webterm agent,
 you can run the automation script on multiple servers without changing the `--device-name` value. Webterm will
 automatically assign a "Device Subname" to uniquely identify the device (by default hostname of the device is used as
 subname and may be suffixed by random letters if hostname is not enough to uniquely identify the device).

## Roadmap / Future Ideas

* **SSO Sign-In**: Integrate single sign-on and authorisation.
* **File Browser**: Browse & manage server files in the browser.
* **Auditing**: Add support for logging all stdin and stdout.
* **Metrics**: Show live server metrics (CPU, Memory etc) as well as historical metrics up to N days (user
 configurable).
* **Custom Plugins**: Add support for custom plugins.
* **Relay failover**: High-availibility, load balancing, and automaic failover for relays with near-zero interruptions
 to live sessions.

## Licence

Licenced under the [MIT Licence](./LICENCE.md).

_(Default relays are hosted on [webterm.run](https://webterm.run) and maintained
by [@nasa42](https://github.com/nasa42))._

MIT License Copyright (c) 2024 nasa42 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.