mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
dd54a2e483
* feat: graduate Host Console to Community admins Make Host Console available to Community and Admiral admins (system:console), add host-console-community for mixed fleets, and keep opaque API tokens off the host shell. * docs: document Host Console deep links Cover root and stack-scoped Console URLs, correct the phone treatment note, and pin parse/build round-trips in senchoRoute tests. * fix: bind Host Console socket to the resolved node Treat unresolved activeNode as loading, target the WebSocket with an explicit nodeId, and wait for stack deep-link hydration so the shell cannot open on the wrong node or compose root. Add regression coverage for node/stack retargeting and fail-closed directory resolution. * fix: harden Host Console node binding, audit acting_as, and console_session tokens Reject unknown or malformed nodeIds before spawning a PTY. Record hub operators in audit_log.acting_as for remote console_session bridges. Path-scope and one-time-consume console_session JWTs so Host Console mints cannot open container exec or be replayed. * test: expect acting_as in audit CSV export header Align the CSV export assertion with the P0-2B acting_as column added to audit log exports.
119 lines
6.9 KiB
Plaintext
119 lines
6.9 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>
|
||
Host Console requires the **admin** role. [Learn more about roles](/features/rbac).
|
||
</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.
|
||
|
||
You can also open Console from a bookmark or shared link. Every Console view has a stable URL under [Deep links and URLs](/features/deep-links):
|
||
|
||
- `/nodes/local/host-console` opens Host Console on the local node at the compose root
|
||
- `/nodes/local/host-console/radarr` opens the same terminal rooted in the Radarr stack directory
|
||
- Remote nodes use their node slug the same way (for example `/nodes/nas-box-42/host-console`)
|
||
|
||
Console requires the **admin** role. The URL stays in the address bar on a phone, but Host Console is meant for a desktop browser.
|
||
|
||
## 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.** 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 with the session principal, node, client IP, and timestamp. When the session is opened through a remote hub bridge, the principal is `console_session` and the hub operator is recorded in `acting_as`, so remote shell access stays accountable to the signed-in admin.
|
||
|
||
<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.
|
||
</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 for users with the **admin** role. If you are an admin and still do not see it, refresh the page. On a remote node, the Console tab may show a lock card when that node does not support Host Console (for example a Pilot Agent node, or a Distributed API Proxy node that does not advertise Host Console).
|
||
</Accordion>
|
||
</AccordionGroup>
|