Skip to Content
DocsApplicationsRemote AccessWeb Console
Web Console

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.

🖥️ Browser Terminal

Terminal-over-HTTP experience backed by bash

🔒 Authenticated Route

nginx basic auth via /etc/htpasswd.d/htpasswd.username

🔁 Reverse Proxy

User-scoped route at /username.console proxied to localhost

🌐 Local Bind

ttyd binds to 127.0.0.1 on the default port 4200

When to use it

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

Good fit

  • You are logged in as an administrator in the dashboard
  • You need a browser-based shell for quick maintenance or checks
  • nginx is serving user-scoped routes like /username.console
  • sshd is available on the server (required by the ttyd systemd unit)

What you get

  • Admin-only console page embedded in the dashboard
  • Local-only ttyd service bound to 127.0.0.1
  • Reverse-proxied route protected with HTTP basic auth
  • Service managed by ttyd.service under systemd

Installation

Web Console is listed as admin-installed software in QuickBox Pro and is managed through the QuickBox CLI.

Install from the QuickBox CLI

qb install webconsole -u username
Command
qb install webconsole -u username
Description
Install Web Console for the specified user
Command
qb reinstall webconsole -u username
Description
Reinstall Web Console and refresh service files
Command
qb remove webconsole -u username
Description
Remove Web Console and its service files
Command
qb update webconsole -u username
Description
Update the ttyd binary to the latest release

CLI Options

-u, --usernameRequired

Target QuickBox username for Web Console operations

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.

Item
User route
Value
/username.console
Item
Dashboard page
Value
System → Web Console (admin only)
Item
Local bind
Value
127.0.0.1:4200

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.

/
usr/
└── local/
│ └── bin/
│ │ └── ttyd# Installed ttyd binary
etc/
├── systemd/
│ └── system/
│ │ └── ttyd.service# Systemd unit with bind, port, and base path
├── nginx/
│ └── software/
│ │ └── webconsole.conf# Reverse proxy and auth_basic
└── htpasswd.d/
│ └── htpasswd.username# HTTP basic auth credentials

Common tasks

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

Command
systemctl status ttyd.service
Description
Check service status
Command
systemctl restart ttyd.service
Description
Restart the Web Console service
Command
systemctl stop ttyd.service
Description
Stop the Web Console service
Command
journalctl -u ttyd.service -f
Description
Tail service logs

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

No. The dashboard console page redirects non-admin users to the home page, so access is restricted to administrators.
The ttyd service is configured with -p 4200 and binds to 127.0.0.1. You can confirm the live port in /etc/systemd/system/ttyd.service.
The nginx location requires HTTP basic auth and uses /etc/htpasswd.d/htpasswd.username for credentials.

Best practices

Keep the Web Console predictable and secure with these habits.

Do

  • Use the dashboard path System → Web Console for admin-only access.
  • Verify the user route /username.console is reachable through nginx.
  • Check /etc/systemd/system/ttyd.service when validating the bind address or port.

Don't

  • Do not expose the ttyd port directly; keep it bound to 127.0.0.1.
  • Do not bypass nginx basic auth by modifying /etc/nginx/software/webconsole.conf manually.

Troubleshooting

Symptom: Web Console shows a blank frame

Checks: Confirm /username.console loads directly in a new tab and that nginx has the Web Console location in /etc/nginx/software/webconsole.conf.

Symptom: Authentication prompt repeats

Checks: Verify the htpasswd file exists at /etc/htpasswd.d/htpasswd.username and that nginx is reading it for the console route.

Symptom: Connection refused or timeout

Checks: Ensure ttyd.service is active and bound to 127.0.0.1 with port 4200 in /etc/systemd/system/ttyd.service.

Resources

Resources

ttyd GitHub Repository
QuickBox CLI Reference

Command structure and global CLI usage

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
noVNCX2Go