Web Terminal

Access your managed servers directly from the browser using Bloqd's WebSocket-based terminal.

Pro Feature

Web Terminal requires a Pro license.

Overview

The web terminal provides:

• Direct SSH-like access from browser
• No need for SSH client setup
• Audit logging of all sessions
• Role-based access control
• Session recording (optional)

How It Works

┌────────────┐   WebSocket    ┌────────────┐     SSH      ┌────────────┐
│  Browser   │◄─────────────►│   Bloqd    │◄───────────►│   Agent    │
│ (Terminal) │               │  (Proxy)   │             │  (Server)  │
└────────────┘               └────────────┘             └────────────┘

1. User opens terminal in browser
2. WebSocket connection established to Bloqd
3. Bloqd proxies commands to agent
4. Agent executes in local shell
5. Output streamed back to browser

Accessing Terminal

From Dashboard

1. Go to Servers page
2. Select a server
3. Click Terminal tab (or icon)
4. Terminal opens in browser

Direct URL

https://bloqd.example.com/servers/{serverId}/terminal

Terminal Features

Standard Features

• Full terminal emulation (xterm.js)
• Copy/paste support
• Scrollback buffer
• Terminal resize
• Color support
• UTF-8 support

Keyboard Shortcuts

Shortcut	Action
Ctrl+C	Cancel/interrupt
Ctrl+D	Exit shell
Ctrl+L	Clear screen
Ctrl+A	Move to line start
Ctrl+E	Move to line end
Ctrl+Shift+C	Copy selection
Ctrl+Shift+V	Paste

Session Management

• Sessions timeout after inactivity (configurable)
• Multiple concurrent sessions supported
• Session can be reconnected if connection drops

Configuration

Enable Terminal

In agent.yaml:

modules:
  terminal:
    enabled: true
    shell: /bin/bash
    timeout: 3600        # Session timeout in seconds
    max_sessions: 5      # Max concurrent sessions per server

Server-Side Settings

Via environment variables:

TERMINAL_ENABLED=true
TERMINAL_SESSION_TIMEOUT=3600
TERMINAL_MAX_SESSIONS=10

Or in Settings → Terminal:

Setting	Description	Default
Enabled	Enable terminal feature	Off
Session Timeout	Idle timeout (seconds)	3600
Max Sessions	Max concurrent sessions	10
Recording	Record all sessions	Off

Security

Access Control

Terminal access requires:

• Valid authentication
• terminal:access permission
• Server-specific access (if RBAC enabled)

Role Requirements

Role	Terminal Access
Viewer	No
Operator	Read-only (if enabled)
Admin	Full access

Audit Logging

All terminal sessions are logged:

• Session start/end time
• User who initiated
• Server accessed
• Commands executed (optional)

View audit logs:

1. Go to Settings → Audit Log
2. Filter by type: "Terminal"

Session Recording

When enabled, full session is recorded:

• All input/output captured
• Playback available in dashboard
• Useful for compliance and forensics

Enable recording:

TERMINAL_RECORDING=true
TERMINAL_RECORDING_PATH=/var/log/bloqd/sessions

Restricted Commands

Certain commands can be blocked:

# In agent.yaml
modules:
  terminal:
    blocked_commands:
      - rm -rf /
      - shutdown
      - reboot
      - init 0

Or via dashboard:

1. Go to Settings → Terminal
2. Add commands to blocklist
3. Save

Shell Environment

Default Shell

The default shell is /bin/bash. Configure:

modules:
  terminal:
    shell: /bin/zsh

Environment Variables

Set default environment:

modules:
  terminal:
    environment:
      EDITOR: vim
      TERM: xterm-256color

Working Directory

Default working directory:

modules:
  terminal:
    working_directory: /root

Troubleshooting

Connection Failed

Terminal Error: Connection failed

1. Check agent is running
2. Verify terminal module is enabled
3. Check WebSocket connectivity
4. Review browser console for errors

Session Timeout

Terminal: Session timed out

• Session exceeded idle timeout
• Reconnect by refreshing the page
• Increase timeout in settings if needed

Permission Denied

Terminal Error: Access denied

1. Verify user has terminal permission
2. Check server access rights
3. Contact admin to grant access

Commands Not Working

1. Verify shell exists on server
2. Check user has sudo if needed
3. Review blocked commands list

Best Practices

1. Use sparingly - Terminal is for emergencies and debugging
2. Enable recording - For compliance and audit purposes
3. Set appropriate timeout - Don't leave sessions open indefinitely
4. Use RBAC - Limit who can access terminal
5. Review audit logs - Regularly check terminal usage
6. Block dangerous commands - Prevent accidental damage

API Access

Start Session

curl -X POST "https://bloqd.example.com/api/v1/servers/{serverId}/terminal" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes WebSocket URL for connection.

List Active Sessions

curl "https://bloqd.example.com/api/v1/terminal/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Terminate Session

curl -X DELETE "https://bloqd.example.com/api/v1/terminal/sessions/{sessionId}" \
  -H "Authorization: Bearer YOUR_API_KEY"