Web Console

Browser-based terminal access powered by ttyd

Web Console (ttyd) is a Terminal-over-HTTP service that delivers a browser-based shell using Xterm.js with CJK and IME support. In QuickBox Pro, it runs as a systemd service and is exposed through nginx under a user-scoped route.

It is not an SSH server or a multi-user shell manager; it provides a browser terminal session backed by the server’s bash shell.

Overview

Web Console provides an in-dashboard terminal experience for QuickBox administrators. The dashboard page embeds the console in an iframe, while nginx routes the user-scoped path to a localhost-only ttyd service.

This keeps the console reachable through the dashboard while the ttyd process itself stays bound to the loopback interface.

Key features

Web Console focuses on secure, user-scoped terminal access with minimal moving parts.

When to use it

Use Web Console when you need a quick administrative shell without leaving the QuickBox dashboard.

Enabling Web Console

Web Console is a built-in dashboard module — there is no package to install from the catalog. An administrator enables it with the built-in toggle, then opens the console in the browser.

Enable from the Dashboard

In App Dashboard → Package Management (/dashboard?mode=packages), Web Console shows as a built-in module with an Active / Off toggle rather than an Install button. Switch it on, then open the terminal at System → Web Console (/system/console). The module is admin-only — non-admin users do not see it and are redirected away from the console page. Toggling it on or off is recorded in the audit log.

Provision the ttyd console from the CLI (automation)

For automated provisioning, the CLI installs the standalone ttyd console — a per-user, reverse-proxied terminal served under /username.console (separate from the built-in dashboard module):

qb install webconsole -u username
qb reinstall webconsole -u username
qb update webconsole -u username
qb remove webconsole -u username

Full flag reference: CLI Reference.

Access and authentication

Web Console is accessed through a user-scoped route and protected with HTTP basic authentication.

URL / route

The console is available at the user-scoped path and is embedded in the dashboard console page.

Login / credentials / tokens

The nginx location uses HTTP basic auth and references a per-user htpasswd file at /etc/htpasswd.d/htpasswd.username.

Security notes

The systemd unit requires sshd.service and binds the ttyd process to localhost, ensuring access flows through nginx and its authentication layer.

Configuration and files

Web Console configuration is distributed across systemd and nginx, with a single ttyd binary installed system-wide.

Common tasks

These service-level tasks map directly to the systemd unit used by Web Console.

Typical workflows:

• Open System → Web Console to launch the embedded terminal (admin only).
• Use the direct route /username.console if you need a standalone browser tab.
• Confirm the active port in /etc/systemd/system/ttyd.service if access fails.
• Restart the ttyd.service after nginx or system updates.

FAQ

Best practices

Keep the Web Console predictable and secure with these habits.

Troubleshooting

Web Console runs as a single ttyd.service systemd unit bound to 127.0.0.1:4200, reverse-proxied by nginx under /username.console. Start any diagnosis with the service status and journal:

systemctl status ttyd.service
journalctl -u ttyd.service -f

systemctl reload nginx
systemctl restart ttyd.service

systemctl status sshd.service
systemctl start sshd.service
qb reinstall webconsole -u username

systemctl restart ttyd.service

Resources