Skip to content
SHC Docs

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.

  1. Look up the deployment’s home node via /api/resource/Stack/<name> so shc shell works identically from any cluster member.
  2. 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}-1 name so shell still works during partial API outages.
  3. Open a WebSocket to /internal/ws/exec on the target node (port internal_api_port) with container_id, cmd, and tty=true as query params.
  4. Bridge stdin/stdout to the WebSocket bidirectionally, with raw-mode terminal handling and initial {"rows": …, "cols": …} sizing frame.
FlagWhat it does
-e / --environmentEnvironment name (default: default)
-S / --serviceWhich Compose service inside the deployment to exec into
--shExplicit shell command; default auto-detects bash, falls back to sh
-u / --userRun shell as this user (emits su -s /bin/sh <user> -c '<shell>')
-w / --workdirPrefix 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.

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.recv

internal_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.

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 to os.Stdout.

When either completes, pending goroutines are cancelled and the terminal settings are restored.

SymptomRoot 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 colorTerminal doesn’t advertise size or doesn’t support raw
Session dies after idleWebSocket ping timeout; tune websocket_ping_* config
  • 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).