Web Terminal

Vapor features a built-in, secure web terminal interface, enabling administrators to execute shell commands directly on the host operating system without requiring out-of-band SSH client access.

---

Accessing the Terminal

1. Navigate to Host Management > Terminal in the web console.
2. A WebSocket connection will automatically be established to the host's shell endpoint.
3. By default, the shell session executes as the root user or under the system user context of the running Vapor daemon.

---

WebSocket Protocol & Session Lifecycle

For custom API clients, terminal emulator integrations, or automated tooling, Vapor exposes its terminal backend over WebSockets:

• WebSocket URL: ws://<host>:8080/ws/terminal (or port 8081 depending on network configurations).
• Communication Protocol: All messages exchanged over the WebSocket connection are structured JSON frames.

Step 1: Authentication

Upon establishing the connection, the client must transmit an authentication frame containing a valid JWT or API token:

{
  "type": "auth",
  "payload": {
    "token": "<auth_token>"
  }
}

Step 2: Channel Subscription

After successful authentication, the client must subscribe to the terminal channel, specifying the initial grid dimensions and the shell path:

{
  "type": "subscribe",
  "payload": {
    "channel": "terminal",
    "cols": 80,
    "rows": 24,
    "shell": "/bin/bash"
  }
}

Step 3: Interactive Input and Output

• Client Input: Send input (including keystrokes, control characters, and line breaks) using input type frames:

  {
    "type": "input",
    "data": "ls -la\n"
  }

• Server Output: The server streams back raw terminal output frames containing stdout/stderr streams.

Step 4: Window Resizing

Vapor dynamically updates the pseudo-terminal (PTY) geometry on the host when the client window resizes. The client sends a resize frame containing the updated row and column counts:

{
  "type": "resize",
  "payload": {
    "rows": 40,
    "cols": 120
  }
}

Step 5: Session Termination

To close the session cleanly, the client can send an exit command inside the input frame:

{
  "type": "input",
  "data": "exit\n"
}

Alternatively, disconnecting the WebSocket socket will automatically terminate the associated host PTY process.

---

CAUTION

The web terminal grants unrestricted administrative root access to the host filesystem and operating system. Vapor's standard API safety wrappers and resource policies do not apply to shell commands executed within this terminal. Use with extreme caution.