The web terminal is an in-browser interface that provides an interactive clickhouse-client session over WebSocket. It is served from any ClickHouse HTTP port at the /webterminal path.
Navigate to /webterminal on any ClickHouse HTTP port (for example, http://localhost:8123/webterminal) to open the terminal.
Enabling and disabling the feature
The /webterminal endpoint is enabled by default and is controlled by the enable_webterminal server setting. To disable it, set the setting to false; requests to /webterminal then return HTTP status 403 Forbidden.
enable_webterminal replaces the former allow_experimental_webterminal setting. The old name is still honored for backward compatibility when enable_webterminal is not set.
Authentication
The web terminal authenticates the user against the same Session and access-control checks as the HTTP protocol, but credentials are exchanged in-band over the established WebSocket connection rather than via the HTTP upgrade request. After the WebSocket handshake completes, the browser sends the first message as JSON:
The user field is optional: when it is omitted or empty, the user name falls back to the default_session_user server setting (or its per-endpoint override in a composable protocols configuration), default unless configured otherwise. If default_session_user is set to an empty string, connections without a user name are prohibited: an auth message with an omitted or empty user fails authentication, the server closes the WebSocket with code 1008, and, when the session_log section is enabled in the server configuration, the reject is recorded in system.session_log as a LoginFailure event with an empty user.
This avoids placing credentials in URL query parameters or Authorization headers attached to the upgrade request, where they could end up in browser history, server access logs, and reverse-proxy logs. URL parameters, HTTP Basic, and X-ClickHouse-User/X-ClickHouse-Key headers on the upgrade request are intentionally not consulted by /webterminal.
Invalid credentials cause the server to close the WebSocket with code 1008; the browser UI re-prompts for credentials.
What the session looks like
Once authenticated, the server runs clickhouse-client attached to a pseudoterminal and bridges its input and output over WebSocket. The session supports the full clickhouse-client experience, including:
- Syntax highlighting.
- Autocompletion.
- Multi-line queries.
- Command history (stored on the server side for the duration of the session).
The terminal uses xterm.js for rendering. All assets are served from the ClickHouse binary itself — no third-party CDNs are loaded.
Integration with /play
The /play Web SQL UI embeds the web terminal as a dockable panel. Toggle it with the terminal icon in the sidebar or press the ~ key when the query editor is empty. The /play page detects /webterminal availability at load time and hides the terminal controls when the endpoint is unavailable (for example, when enable_webterminal is set to false).
Integration with the documentation website
This documentation website embeds the same terminal in a narrow developer tray along the bottom of the page, connected to the ClickHouse playground as the read-only play user, so that the examples on any page can be tried out without leaving it. The fixed tray reserves matching space at the end of the page so it does not obscure footer controls. While the terminal is open, the documentation page is locked and its scrollbar is hidden. Scrolling over the terminal is contained within its scrollback and does not move the documentation page behind it. Click the “ClickHouse terminal” bar or press the ~ key to open the padded panel above the bar. Click the bar again, use its chevron, press ~ or Escape, or drag the panel’s top edge down to collapse it; that top edge also resizes it. Ending the session — exit or Ctrl+D — collapses the panel too.
Closing the panel keeps the session and its scrollback: reopening the terminal returns to the same prompt. The session lives in the page, so it survives navigation between documentation pages, but not a reload of the browser tab — after a reload the panel comes back with a new session.
The terminal tray is part of the desktop layout of the website and is not available on narrow viewports.
Security considerations
The web terminal exposes an interactive shell-like session to anyone who can authenticate against the ClickHouse HTTP endpoint, so the same caveats that apply to the HTTP protocol apply here:
- Always serve
/webterminal over HTTPS in untrusted environments to protect credentials and session traffic.
- Restrict access at the network level (firewall, reverse proxy, or the
listen_host configuration) the same way you restrict access to the HTTP protocol.
- The endpoint validates the
Origin header against the Host to mitigate cross-origin WebSocket hijacking; configure reverse proxies accordingly if you terminate TLS externally.
- Behind a TLS-terminating reverse proxy, the upstream connection to ClickHouse is plain
http even though the browser uses https, so the strict same-origin check would reject legitimate connections. For these deployments, set webterminal_allowed_origins to a comma-separated list of full origins that are allowed to open WebSocket sessions; when this setting is non-empty, it replaces the default same-origin check. Example: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.
The handler also enforces WebSocket protocol conformance per RFC 6455: unmasked client frames, reserved opcodes, oversized or fragmented control frames, and reserved RSV bits are rejected with protocol-error close codes.
The handler is compiled on all platforms ClickHouse supports. The pseudoterminal layer used by the embedded clickhouse-client runner is implemented on top of portable POSIX primitives (posix_openpt/grantpt/unlockpt), with a Linux-specific path that uses the thread-safe ptsname_r. The links to /webterminal on the ClickHouse start page and in /play are hidden automatically when the endpoint is unavailable (for example, when enable_webterminal is set to false). 
