Gabor Koerber
3.2 KiB
Interactive Mode
When you run sandcage shell or pass --shell to an agent command, sandcage opens an
interactive terminal session inside the container. How that session is wired up depends on
your terminal — sandcage picks the best available method automatically.
Two backends
Native TTY (default)
Sandcage talks directly to the Docker API, puts your terminal into raw mode, and relays keystrokes and output between your terminal and the container. This gives you:
- Terminal resize tracking — the container shell adjusts when you resize the window
- Full TTY fidelity — colors, cursor movement, and interactive programs (vim, htop, etc.) work as expected
- Graceful shutdown — the container stops cleanly when the session ends
This is the same mechanism docker run -it uses under the hood.
Compose fallback
When native TTY isn't available, sandcage delegates to docker compose run, which manages
the terminal connection itself. You get the same interactive shell — the difference is
invisible in normal use. The fallback activates automatically; no configuration needed.
Which backend am I using?
Sandcage prints a diagnostic line to stderr when it makes its choice:
sandcage: tty probe → crossterm raw mode OK — using bollard TTY
or
sandcage: tty probe → MSYS2/MinGW detected (MSYSTEM set) — using compose
These messages appear once at session start and don't affect your shell.
When does the fallback activate?
The detection runs through these checks in order:
| Check | Triggers fallback when… |
|---|---|
compose_backend config |
Set to "compose" in sandcage.toml — forces compose unconditionally |
| MSYSTEM environment variable (Windows) | Present — indicates Git Bash or MSYS2, whose terminal emulator can't handle raw console mode |
| Console handle (Windows) | Invalid — stdin is piped or redirected, not a real terminal |
| Raw mode probe (all platforms) | Fails — terminal doesn't support raw mode |
If none of these trigger, sandcage uses native TTY.
Exiting the session
In native TTY mode, your keystrokes are relayed directly to the container shell. This means:
- Ctrl+D or typing
exitends the session (same as any shell) - Ctrl+C interrupts the current command inside the container — it does not kill the
session. This matches
docker run -itbehavior.
In compose fallback mode, Ctrl+C ends the session immediately.
Forcing compose mode
If you run into rendering issues in an unusual terminal, you can force the compose backend
by adding this to your sandcage.toml:
compose_backend = "compose"
This bypasses all detection and always uses docker compose run for interactive sessions.
Windows terminal compatibility
| Terminal | Backend used |
|---|---|
| Windows Terminal / PowerShell | Native TTY |
| CMD (Command Prompt) | Native TTY |
| Git Bash (MinTTY) | Compose fallback |
| MSYS2 / MinGW shells | Compose fallback |
| WSL | Native TTY |
On macOS and Linux, native TTY is used in all standard terminals (iTerm2, Terminal.app, GNOME Terminal, Alacritty, kitty, etc.). The compose fallback would only activate if stdin is piped or the terminal is otherwise non-interactive.