mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
8096799e49
Reframe docs, OpenAPI registries copy, and License trial/expiry helpers so Community is the full AGPLv3 product and Admiral leads with current assurance (Hardened Build, Recovery Vault, support, governance). Mesh, Secrets, and Host Console stay limited-availability without Admiral sales framing.
111 lines
6.3 KiB
Plaintext
111 lines
6.3 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 is a limited-availability operator surface. When it is present on an instance, it requires the **admin** role. [Learn more about licensing](/features/licensing).
|
||
</Note>
|
||
|
||
<Frame>
|
||
<img src="/images/host-console/host-console-overview.png" alt="Host Console showing a live bash session listing containers with the floating chip strip in the bottom right" />
|
||
</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 color 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, and a small back button appears in the masthead so you can return to the stack editor.
|
||
|
||
## Cockpit layout
|
||
|
||
The Console page is a vertical stack of two surfaces.
|
||
|
||
<Frame>
|
||
<img src="/images/host-console/host-console-masthead.png" alt="Masthead with brand-cyan accent on the left, Connected state in italic, and shell, viewport, and session uptime metadata on the right" />
|
||
</Frame>
|
||
|
||
The **masthead** holds the live connection state. The state word recolors with the tone of the session:
|
||
|
||
- **Connected** in brand cyan with a pulsing dot whenever output is flowing
|
||
- **Reconnecting** in amber when the WebSocket is being re-established
|
||
- **Disconnected** in red when the session has ended
|
||
|
||
The kicker reads `HOST CONSOLE · {NODE}`, so it always tells you which node the session belongs to. The right side carries three metadata pills:
|
||
|
||
| Pill | Meaning |
|
||
|------|---------|
|
||
| **SHELL** | The pill reads `BASH`. In a Docker deployment, the spawned shell is bash, falling back to `sh` if bash is unavailable inside the image. |
|
||
| **VIEWPORT** | Current terminal size in `{cols}×{rows}`, updated automatically when you resize the browser window. |
|
||
| **SESSION** | Time elapsed since the shell was opened (`M:SS UP` while under an hour, then `1H 05M` once it crosses an hour). |
|
||
|
||
The **terminal well** sits below the masthead and fills the remaining height with an xterm.js session.
|
||
|
||
<Frame>
|
||
<img src="/images/host-console/host-console-chip-strip.png" alt="Floating chip strip with Copy, Clear, Download, and Reconnect buttons" />
|
||
</Frame>
|
||
|
||
The **chip strip** floats over the bottom right of the terminal:
|
||
|
||
- **Copy** copies the current xterm selection to your clipboard
|
||
- **Clear** wipes the visible scrollback without killing the shell
|
||
- **Download** exports the full scrollback as a timestamped `.txt` file
|
||
- **Reconnect** closes and reopens the WebSocket without leaving the page
|
||
|
||
## Sessions and 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 runs a heartbeat; if the browser tab is closed or the network drops, the server detects the dead connection and cleans up the orphaned shell within 60 to 90 seconds.
|
||
|
||
## Environment variables
|
||
|
||
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 (`DATABASE_URL`, `REDIS_URL`, `MONGO_URI`, `AMQP_URL`, `DSN`) are stripped from the console environment before the shell spawns. Running `env` or `printenv` inside the console will not reveal them.
|
||
|
||
## Security considerations
|
||
|
||
The Host Console is one of the most powerful features in Sencho and is treated as such:
|
||
|
||
- **Admin role required when present.** The Host Console is a limited-availability surface; only users with the **admin** role can open a console session.
|
||
- **Browser sessions only.** Console sessions are only available from a signed-in browser session, not from API tokens.
|
||
- **Audited.** Every console session is recorded in the audit log. Opening and closing a session each write an entry capturing the user, node, client IP, and timestamp, so shell access is fully accountable.
|
||
|
||
<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 60 to 90 seconds.
|
||
</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 that Console is available on this instance.
|
||
</Accordion>
|
||
|
||
<Accordion title="Connection drops after a short time">
|
||
If you are running Sencho behind a reverse proxy (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 (for example `3600s`).
|
||
</Accordion>
|
||
|
||
<Accordion title="Console tab is not visible">
|
||
Console appears only when the surface is present on the instance, and only for users with the **admin** role. Verify those conditions are met, then refresh the page.
|
||
</Accordion>
|
||
</AccordionGroup>
|