---
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 enabled on an instance, it requires an **Admiral** license and 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.** Only users with the **admin** role can open a console session.
- **Admiral license required when enabled.** The Host Console is a limited-availability surface that uses an Admiral license.
- **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 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 (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 enabled on the instance, and only for users with the **admin** role on an Admiral-licensed instance. Verify those conditions are met. If you recently activated an Admiral license, refresh the page.
  </Accordion>
</AccordionGroup>
