Skip to content

002-docker-exec-not-ssh.md

Latest commit

 

History

History
21 lines (16 loc) · 1.52 KB

002-docker-exec-not-ssh.md

File metadata and controls

21 lines (16 loc) · 1.52 KB

ADR-002: Docker exec with Idle Entrypoint, not SSH

Status: Accepted Date: 2026-04-13

Context: Cloud-mode sessions need to run interactive shells inside containers. The container must stay alive between shell sessions (for reconnect), and the PTY must be restartable without recreating the container.

Decision: Use docker exec with an idle entrypoint (sleep infinity or similar). The container is created once and stays running. Each terminal attachment is a new exec instance with TTY, managed via the bollard crate's async API.

Alternatives considered:

  • SSH into container — requires installing and configuring sshd in every container image, managing SSH keys, and a separate auth layer. Adds image bloat and attack surface. Doesn't integrate with the existing mTLS/token auth.
  • Container restart per session — simpler but loses filesystem state on restart. No reconnect capability. Slow startup for each new shell.
  • nsenter / PID namespace attach — requires host-level privileges and is Linux-specific. Fragile across Docker versions and runtimes.

Consequences:

  • Container stays alive — filesystem state persists across shell sessions
  • PTY is restartable: exec can be re-created without container recreation
  • Git worktree is mounted once, available across multiple exec instances
  • Exec resize is supported via the Docker API (resize_exec)
  • Trade-off: slightly more complex lifecycle management (container + exec as separate entities)
  • No SSH overhead: no sshd, no keys, no extra ports