Skip to content

architecture.md

Latest commit

 

History

History
101 lines (69 loc) · 2.33 KB

architecture.md

File metadata and controls

101 lines (69 loc) · 2.33 KB

Architecture

Intent

This setup treats SSH as the primary interface, not a side path.

The repository is structured so that:

  • interactive entrypoints stay small and predictable
  • SSH integration examples stay separate from runtime code
  • deployment concerns do not leak into the launcher logic
  • future host-specific automation can be added without reshaping the tree

Runtime model

The login path is:

ssh client
  -> sshd
  -> forced command or direct shell entry
  -> bin/codex-ssh
  -> tmux session lookup
  -> start Codex once or attach to existing session

This model is efficient because reconnects attach to the same persistent session instead of cold-starting the tool each time.

Why tmux

tmux is the right abstraction here for SSH-centric use:

  • SSH disconnects do not kill the running session.
  • Reattach is near-instant.
  • Operators already understand it.
  • It avoids inventing a custom session manager.

Why these folders

bin/

  • user-facing executable entrypoints only
  • minimal surface area
  • easy to review in diffs

scripts/

  • install and validation helpers
  • non-runtime operational tasks
  • safe place for platform-specific setup to grow later

config/

  • examples that mirror where operators expect SSH config to live
  • keeps deploy snippets separate from business logic
  • reduces merge noise when production values differ per host

docs/

  • rationale, rollout notes, and repository conventions
  • avoids burying operating guidance inside shell code comments

Efficient defaults

The launcher keeps startup cheap by:

  • sourcing one simple env file
  • only creating the tmux session if missing
  • avoiding unnecessary subprocesses after attach
  • using shell scripts instead of a heavier runtime

Recommended production layout

For a dedicated SSH user:

/home/codex/.local/bin/codex-ssh
/home/codex/.config/codex-ssh/codex-ssh.env
/home/codex/codex-workspace

For system-managed deployment:

/usr/local/bin/codex-ssh
/etc/ssh/sshd_config.d/10-codex-ssh.conf
/srv/codex

Extension points

Logical next additions, if needed:

  • host bootstrap scripts for package installation
  • audit logging wrappers
  • per-project workspace selectors
  • restricted command routing for multiple SSH keys
  • healthcheck integration for managed hosts

Those can be added without changing the current public entrypoint.