Shell module
Layer 8. Node. Node Exec runs on the node that holds the container.
shc shell opens an interactive PTY in a container of a running
deployment. The name on the command line is the stack axis. The exec
runs on the node that holds that deployment.
Source: modules/shell/commands/shell.go and modules/shell/service.go.
router.go serves WS /internal/ws/exec.
Responsibilities
Section titled “Responsibilities”- Look up the deployment’s home node via
/api/resource/Stack/<name>soshc shellworks identically from any cluster member. - Resolve the target container ID by hitting the target node’s
internal API (
GET /internal/containers?project=<name>&service=<svc>). If the listing fails, fall back to the conventional{project}-{service}-1name soshellstill works during partial API outages. - Open a WebSocket to
/internal/ws/execon the target node (portinternal_api_port) withcontainer_id,cmd, andtty=trueas query params. - Bridge stdin/stdout to the WebSocket bidirectionally, with
raw-mode terminal handling and initial
{"rows": …, "cols": …}sizing frame.
| Flag | What it does |
|---|---|
-e / --environment | Environment name (default: default) |
-S / --service | Which Compose service inside the deployment to exec into |
--sh | Explicit shell command; default auto-detects bash, falls back to sh |
-u / --user | Run shell as this user (emits su -s /bin/sh <user> -c '<shell>') |
-w / --workdir | Prefix the exec with cd <workdir> && |
The --user and --workdir flags are synthesized into a shell
command string rather than passed as docker exec --user/--workdir,
because the exec runs through the internal API’s generic
ws/exec endpoint which takes a single command string.
Wire path
Section titled “Wire path”sequenceDiagram participant CLI as "shc shell myapp" participant Any as Any node (usually loopback) participant Target as Target node 10.192.0.3:4003
CLI->>Any: 1. GET /api/resource/Stack/myapp Any-->>CLI: returns node_address 10.192.0.3 CLI->>Target: 2. GET /internal/containers (project, service) Target-->>CLI: returns container id (cid) CLI->>Target: 3. ws /internal/ws/exec (container_id, cmd, tty=true) Note over CLI,Target: PTY bridge CLI->>Target: SIGWINCH-like init frame {"rows": R, "cols": C} CLI->>Target: stdin (raw-mode) via ws.send Target-->>CLI: stdout/stderr via ws.recvinternal_api_port is 4003 by default, authenticated by the
internal mTLS + X-SHC-Internal-Token header. See
security for the internal-plane auth model and
architecture/flows/cluster-join for how
that token is provisioned.
TTY handling
Section titled “TTY handling”runInteractiveWS sets the local tty to raw mode (via
term.MakeRaw(fd)) for the duration of the session,
restores terminal settings in a defer block, and sends an
initial {"rows": …, "cols": …} JSON frame derived from terminal size
so container programs (vim, top, htop, etc.) render correctly.
Two goroutines run concurrently with an errgroup:
readStdin: reads from stdin so keyboard input streams without buffering.readWS: consumes inbound messages and routes text toos.Stdout.
When either completes, pending goroutines are cancelled and the terminal settings are restored.
Failure modes
Section titled “Failure modes”| Symptom | Root cause / fix |
|---|---|
no running containers found on remote node… | The deployment is stopped or the service filter didn’t match |
websocket exec failed (X500901OPFAIL) | Internal API unreachable; check cluster health + mesh |
| Garbled output / no color | Terminal doesn’t advertise size or doesn’t support raw |
| Session dies after idle | WebSocket ping timeout; tune websocket_ping_* config |
What shell is not
Section titled “What shell is not”- It’s not a REPL into SHC’s internals; there’s no Go
shell, no DB access, no cluster admin shell. It’s strictly
docker exec-equivalent. - It’s not the same as
shc logs; that uses a different streaming path over the resource API. - It doesn’t proxy through Traefik / a published ingress; it goes node-direct over the internal port (4003).
Related
Section titled “Related”- Security: how the internal API authenticates
the
ws/execcall - Network architecture: where port 4003 sits
- Reference: shell CLI: full flag list
- Reference: hud API: the UI-facing
sibling WebSocket that uses the same
/internal/ws/execbackend