mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-27 20:29:10 +00:00
Anso
718c1eb1ea
Security: - Enforce RBAC (system:console permission) on WebSocket upgrade - Validate token_version for user sessions on WS connections - Expand env var sanitization to cover additional secret patterns (PRIVATE, AUTH, PASSPHRASE, ENCRYPT, SIGNING) and connection strings (REDIS_URL, MONGO_URI, AMQP_URL, DSN) Reliability: - Add session tracking with max 5 concurrent console sessions - Add WebSocket heartbeat (30s ping, 60s pong timeout) to detect and clean up dead connections and orphaned PTY processes - Differentiate PTY spawn error messages (shell not found, permission denied, generic failure) - Guard against duplicate cleanup when both WS close and PTY exit fire Observability: - Add structured logging with [HostConsole] prefix for session lifecycle (open, close, duration, user, pid) - Add diagnostic logging behind developer_mode for terminal resize events and message parse errors Frontend: - Replace hardcoded hex colors with oklch CSS custom properties (--terminal-bg, --terminal-fg, --terminal-cursor, etc.) - Apply design system material tokens (shadow-card-bevel, recessed well shadow, card border hierarchy, strokeWidth 1.5) Tests: - Add 20 tests covering env sanitization patterns (10 keyword categories + safe vars + case insensitivity), session tracking, and console-token RBAC (admin, viewer, deployer, API tokens) Docs: - Document admin role requirement and session limits - Add troubleshooting section (session limits, shell not found, proxy timeouts, missing console tab) - Update security section with expanded env var coverage
97 lines
5.7 KiB
Plaintext
97 lines
5.7 KiB
Plaintext
---
|
|
title: Host Console
|
|
description: An interactive terminal on your host OS, directly in the browser - no SSH required.
|
|
---
|
|
|
|
The **Console** tab opens a full interactive terminal session on the machine running Sencho. It behaves exactly like an SSH session, but without needing an SSH server, client, or key management.
|
|
|
|
<Note>
|
|
The Host Console requires a **Sencho Admiral** license. Community and Skipper users will not see the Console tab in the navigation bar. [Learn more about licensing](/features/licensing).
|
|
</Note>
|
|
|
|
<Frame>
|
|
<img src="/images/host-console/host-console-overview.png" alt="Host Console showing a PowerShell prompt in the COMPOSE_DIR working directory" />
|
|
</Frame>
|
|
|
|
## What it is
|
|
|
|
The Host Console gives you a real terminal session on the Sencho host, streamed to your browser over a WebSocket. It supports:
|
|
|
|
- Full colour and cursor support
|
|
- Tab completion (provided by the host shell)
|
|
- Automatic terminal resizing when you resize the browser window
|
|
- Copy and paste
|
|
- Cursor blinking
|
|
|
|
## Opening the console
|
|
|
|
Click **Console** in the top navigation bar. The session starts immediately in the `COMPOSE_DIR` root. If a stack is selected in the sidebar, the terminal opens directly inside that stack's directory instead.
|
|
|
|
The header bar shows:
|
|
|
|
- **Host Console** label with a terminal icon
|
|
- The active **node name** (e.g. "Local" or a remote node)
|
|
- The **stack name** in parentheses, if one is selected
|
|
- A green **Connected** badge while the WebSocket session is active
|
|
- A **Close Console** button on the right to end the session
|
|
|
|
Clicking **Close Console** terminates the shell process on the host and disconnects the WebSocket.
|
|
|
|
## Shell type
|
|
|
|
The shell depends on the host operating system:
|
|
|
|
- **Linux / macOS hosts:** `bash` (falls back to `sh` if bash is not available)
|
|
- **Windows hosts:** PowerShell
|
|
|
|
In a typical Docker deployment, the Sencho container runs Linux, so the console opens a `bash` shell regardless of the Docker host's OS. The PowerShell prompt shown in the screenshot above reflects a native Windows development environment.
|
|
|
|
## Availability
|
|
|
|
The Host Console is available exclusively to users with the **admin** role on the **Admiral** tier. Other roles (node-admin, deployer, viewer, auditor) cannot access the console, even on Admiral-licensed instances. If your instance is on the Community or Skipper tier, the Console tab does not appear in the navigation bar at all. Attempting to access the console endpoint directly without the correct license or role is rejected.
|
|
|
|
## Session limits
|
|
|
|
Sencho enforces a maximum of **5 concurrent console sessions** per instance. If you hit this limit, close an existing session before opening a new one. Each session also includes an automatic heartbeat; if the browser tab is closed or the network drops, the server detects the dead connection and cleans up the session within about a minute.
|
|
|
|
## Security considerations
|
|
|
|
The Host Console has stricter access requirements than other features:
|
|
|
|
- **Admin role required.** Only users with the `admin` role can open a console session. Non-admin roles are blocked at both the UI and the API level.
|
|
- **Browser sessions only.** API tokens used for automation or multi-node communication cannot open a console session.
|
|
- **Admiral license required.** The license check is enforced at every layer, not just in the UI.
|
|
- **Session invalidation.** Changing a user's password or role immediately invalidates any active session tokens. A user who is downgraded from admin loses console access instantly.
|
|
- **Sensitive environment variables are stripped.** Environment variables whose names suggest secrets (passwords, tokens, keys, credentials, auth-related variables, private keys, passphrases, encryption and signing secrets) and certain well-known connection strings are automatically removed from the console environment. Running `env` or `printenv` inside the console will not reveal them.
|
|
|
|
<Warning>
|
|
The Host Console provides unrestricted shell access to the machine running Sencho. Do not expose Sencho on a public network without HTTPS and strong authentication.
|
|
</Warning>
|
|
|
|
## Common uses
|
|
|
|
- Inspecting files in your `COMPOSE_DIR` without leaving the browser
|
|
- Running `docker compose logs --follow` or `docker ps` directly
|
|
- Editing files with `nano` or `vim` for quick fixes
|
|
- Running maintenance scripts or one-off commands on the host
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Maximum console sessions reached">
|
|
Sencho limits concurrent console sessions to 5 per instance. Close one or more existing console sessions (either through the UI or by closing the browser tab) and try again. Stale sessions from disconnected browsers are cleaned up automatically within about a minute.
|
|
</Accordion>
|
|
|
|
<Accordion title="Session ends immediately after connecting">
|
|
This typically means the shell could not be found on the host. In a Docker deployment, ensure `bash` or `sh` is available inside the container. You can check by running `docker exec <container> which bash` from the host. Also verify that your user has the `admin` role and your instance has an active Admiral license.
|
|
</Accordion>
|
|
|
|
<Accordion title="Connection drops after a short time">
|
|
If you are running Sencho behind a reverse proxy (e.g. Nginx, Caddy, Traefik), the proxy may be closing WebSocket connections after its default idle timeout. Increase the WebSocket timeout in your proxy configuration. For Nginx, set `proxy_read_timeout` and `proxy_send_timeout` to a higher value (e.g. `3600s`).
|
|
</Accordion>
|
|
|
|
<Accordion title="Console tab is not visible">
|
|
The Console tab only appears for users with the `admin` role on an Admiral-licensed instance. Verify both conditions are met. If you recently upgraded your license, you may need to refresh the page.
|
|
</Accordion>
|
|
</AccordionGroup>
|