ngn-agent/.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md

Phase 6: Default Repos & SSH Mount - Context

Gathered: 2026-06-14 Status: Ready for planning

## Phase Boundary

Enable automatic availability of DEFAULT_REPOS in every new Hermes session and provide on-demand repo cloning capability. Repos are mounted directly from host filesystem (not cloned inside Docker) to preserve git worktrees and avoid redundant clones.

In scope: SSH key mounting for git auth, repo volume mounts for 3 default repos, shell init script for session workspace setup, DEFAULT_REPOS configurability, on-demand cloning for additional repos

Out of scope: Hindsight memory integration (Phase 5 already done), session lifecycle skill (Phase 7), cron reporting (Phase 8), migration of existing session data

## Implementation Decisions

Git Auth Strategy

• D-01: Mount specific SSH keys read-only into Docker — ~/.ssh/id_ed25519razer and ~/.ssh/id_rsa plus ~/.ssh/config
  • Config: Add to terminal.docker_volumes in ~/.hermes/config.yaml
  • ~/.ssh/id_ed25519razer:/root/.ssh/id_ed25519razer:ro
  • ~/.ssh/id_rsa:/root/.ssh/id_rsa:ro
  • ~/.ssh/config:/root/.ssh/config:ro
  • The existing ~/.ssh/config already maps bitbucket.org → id_ed25519razer

Repo Workspace Mounts

• D-02: Mount repo directories directly from host filesystem — repos live at ~/Razer/<repo> and are mounted into Docker as host-mounted volumes
  • Config: Add to terminal.docker_volumes:
  • ~/Razer/rai-ops:/workspace/rai-ops:rw
  • ~/Razer/rai-deployment:/workspace/rai-deployment:rw
  • ~/Razer/rai-devtools:/workspace/rai-devtools:rw
  • This preserves existing git worktrees, branches, and avoids re-cloning
  • Container has read-write access for git operations

Session Init Script

• D-03: Create session-init.sh in ~/.hermes/scripts/ (already mounted to /usr/local/bin:ro). Script checks that DEFAULT_REPOS are mounted at expected paths and logs status
  • Config: Add to terminal.shell_init_files: ["/usr/local/bin/session-init.sh"]
  • Behavior: check each repo in DEFAULT_REPOS exists at /workspace/<name>, log status, skip if absent (no blocking)

DEFAULT_REPOS Configurability

• D-04: DEFAULT_REPOS defined as an env var in ~/.hermes/.env:
  • DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools
  • Forwarded into Docker via docker_forward_env
  • The session init script reads this env var to validate mounts
  • User can add/remove repos by editing .env + adding/removing volume mounts

On-Demand Repo Cloning (REPO-02)

• D-05: Agent clones additional repos into /workspace/ using git clone inside Docker. SSH keys are mounted so auth works for any Bitbucket repo the user has access to
  • Clones are ephemeral (lost on container restart) — suitable for temporary work
  • Agent uses git clone git@bitbucket.org:razersw/<repo>.git
  • No dedicated skill needed — git is available in the Docker image

the agent's Discretion

• Init script error handling: The script should exit gracefully if a repo is missing (non-blocking — session should still start)
• On-demand clone destination: Default to /workspace/ unless user specifies otherwise

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Existing Hermes Configuration

• ~/.hermes/config.yaml §terminal.docker_volumes — Current volume mounts (SSO cache, scripts) — the planner must append to this list
• ~/.hermes/config.yaml §terminal.shell_init_files — Currently empty, needs session-init.sh
• ~/.hermes/config.yaml §terminal.docker_forward_env — Currently forwards JIRA_EMAIL and JIRA_API_TOKEN
• ~/.hermes/scripts/ — Existing scripts directory (ngn-jira, ngn-confluence, ngn-bitbucket) — session-init.sh goes here
• ~/.hermes/.env — Existing env vars (OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, JIRA_API_TOKEN, etc.)

SSH Configuration

• ~/.ssh/config — Maps bitbucket.org → id_ed25519razer
• ~/.ssh/id_ed25519razer — Razer-specific SSH key
• ~/.ssh/id_rsa — RSA key

Project Documents

• .planning/REQUIREMENTS.md §REPO-01, REPO-02 — Requirement definitions
• .planning/ROADMAP.md §Phase 6 — Phase goal and success criteria
• .planning/research/SUMMARY.md §Phase 2 — Research on repo mounting vs cloning, credential strategies
• .planning/research/PITFALLS.md — Git clone failures in Docker, SSH credential exposure risks </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• ~/.hermes/scripts/ mount: Already mounted to /usr/local/bin:ro — new session-init.sh goes here automatically
• Docker volumes pattern: Existing mount entries in config.yaml show the pattern (host:container:mode)

Established Patterns

• Read-only sensitive files: .aws/config mounted :ro — SSH keys follow the same pattern for security
• Scripts mounted to /usr/local/bin: ngn-* scripts already use this pattern — session-init.sh follows it

Integration Points

• ~/.hermes/config.yaml §terminal.docker_volumes — Append SSH key + repo mounts
• ~/.hermes/config.yaml §terminal.shell_init_files — Set to ["/usr/local/bin/session-init.sh"]
• ~/.hermes/config.yaml §terminal.docker_forward_env — Append DEFAULT_REPOS
• ~/.hermes/.env — Add DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools
• ~/.hermes/scripts/session-init.sh — New file (create) </code_context>

## Specific Ideas

• Mount repos read-write (:rw) so git operations inside container (branch, commit, push) work seamlessly — this is the core advantage over cloning
• The session-init.sh should be lightweight: just verify mounts exist and log status. Do NOT attempt git operations — the repos are already on disk with active worktrees

## Deferred Ideas

• Auto-register repos as git worktrees via Hermes' worktree: true config — already handled by the host-side git setup
• Per-repo deploy keys instead of personal SSH key — future security hardening

---

Phase: 6-Default Repos & SSH Mount Context gathered: 2026-06-14