RunCloud Web Terminal follows a security-first opt-in model. This ensures that terminal shell routes are never exposed unexpectedly on hardened production servers. Web Terminal feature is disabled by default on existing server installations until the server owner explicitly enables it.
This guide provides step-by-step instructions for server owners and workspace owners to manage the Web Terminal flag.
Access & Permission Requirements
The Web Terminal enable/disable switch is restricted exclusively to top-level owners:
- Individual Server: Only the Server Owner can request to enable or disable the feature.
- Workspace Server: Only the Workspace Owner role can request the enablement or disable the feature.
- Team Members / Collaborators: Team members cannot toggle or trigger enablement requests, regardless of their assigned server permissions.
Agent Configuration States
Web Terminal routes and WebSocket endpoints on the server agent (port 34210) behave according to the local agent configuration flag:
| Flag State | Server Terminal Behavior |
|---|---|
| off / Unset | All Web Terminal routes and WebSocket endpoints are blocked on the server agent. The Terminal tab in the RunCloud dashboard displays the feature introduction modal. No user can open or connect to a session. |
| on | Web Terminal HTTP and WebSocket routes are active and accessible to authorized team members who complete 2FA. The dropdown menu provides Launch Terminal and Disable Terminal Access options. |
Note: Enabling Web Terminal does not install external binary dependencies on your server. Web Terminal builds directly upon the existing RunCloud agent infrastructure.
How to Enable Web Terminal
Enabling Web Terminal requires a one-time email verification process per server to ensure that only the verified Server Owner or Workspace Owner can enable terminal access.
Step 1: Navigate to the Server
- Log in to the RunCloud Dashboard and select your target server.
- Click on the Enable Terminal tab in the top header menu.
- This will open a new modal with an overview of browser-based shell access, built-in safeguards, and real-time collaboration.
Step 2: Request Enablement
- Click the Enable Terminal button in the modal.
- RunCloud will send an 8-digit security verification code to the owner’s email address.
- The Web Terminal feature cannot be activated without entering the 8-digit verification code. Enter the 8-digit code into the verification fields.
- After entering the code in the provided text box, click Verify & Enable.
- After successful verification, the top-right menu in your RunCloud dashboard displays the Terminal dropdown menu with Launch Terminal and Disable Terminal Access.
Note: To prevent unauthorized activation, brute-force attacks, and inbox spamming, the verification flow enforces strict security limits. RunCloud maintains a per-user attempt counter with a 15-minute decay window. If a user inputs 5 incorrect attempts, the current verification code is immediately invalidated, and a new code must be requested. Sending a new verification code is rate-limited to a maximum of 3 resends per 24-hour period.
How to Disable Web Terminal
Whether you are performing routine server hardening or responding to a suspected security compromise, you can disable Web Terminal instantly. This quick emergency disable feature shuts down interactive shell access in real time and protects your server from unauthorized changes.
Follow these steps to turn off Web Terminal access on your server:
- Log in to your RunCloud dashboard.
- Navigate to your server or web application by selecting Servers > your server name or Web Applications > your web application name.
- Locate the “Terminal” dropdown menu in the upper-right corner of the page.
- Click the dropdown menu and select Disable Terminal Access.
- Review the confirmation prompt on your screen.
- Click Disable to confirm your choice and revoke terminal access immediately.
What Happens When You Disable Web Terminal?
When you confirm the action, RunCloud secures your server automatically in the background:
- Active Sessions End Immediately: All connected browser terminal sessions drop at once. Anyone with an open session will see an end-of-session notice, such as “Session ended: terminal-disabled” or “Session ended: session ended”.
- Terminal Routes Are Blocked: The RunCloud agent updates its internal configuration to “off”, immediately unregisters all terminal routes, and terminates all running pseudo-terminal (PTY) processes on your server.
- Re-Activation Protection: Because re-enabling Web Terminal requires a verification code sent to your registered email address, an attacker cannot reopen a terminal shell without access to the server owner’s email inbox.
If you have any other questions or need help, please feel free to get in touch with our 24/7 support team. We’re here to help!