Skip to content

feat: GitHub Codespace integration with SSH tunnel support #307

@btessiau

Description

@btessiau

Summary

Add the ability to connect PolyPilot to a running GitHub Codespace, creating sessions that execute inside the codespace environment rather than on the local machine.

Motivation

Users working with GitHub Codespaces want to use PolyPilot's multi-session management while leveraging the codespace's environment (dependencies, tools, repo state). Currently the only option is Remote mode via DevTunnel, which requires manual setup inside the codespace.

Implementation (PR #308)

  • Discovery: gh cs list --json enumerates available codespaces
  • Connection: SSH tunnel (gh cs ssh) to copilot headless server running in the codespace
  • Health monitoring: Background loop detects tunnel failures and auto-reconnects
  • Session lifecycle: Sessions persist across app restarts; resume when tunnel reconnects
  • Alpha gate: Disabled by default, enabled via Settings → Alpha → Codespaces toggle

Requirements

  • GitHub CLI (gh) authenticated with codespace scope
  • SSH server running in the codespace (typically via dotfiles configuration)
  • Without SSH, the feature gracefully degrades to a "Setup Required" state — it cannot start copilot remotely

Known Limitations (Alpha)

  1. SSH process orphaning on app crash — Spawned gh cs ssh processes survive hard crashes. No PID tracking for cleanup on next launch. Tunnels die when codespace times out.
  2. Port-forward fallback is non-functionalgh cs ports forward cannot start copilot without SSH. Code correctly transitions to SetupRequired rather than hanging.
  3. No integration tests for tunnel lifecycle — Core reconnect/health-check paths require real SSH/gh CLI. Model, contract, and isolation tests are comprehensive (113 tests).
  4. No stale process cleanup on startup — Future improvement: track PIDs to clean up orphaned tunnels.

Files Changed

  • CodespaceService.cs / .Lifecycle.cs / .Diagnostics.cs — SSH tunnel and codespace management
  • CopilotService.Codespace.cs — Group lifecycle, health check, session resume
  • CopilotService.cs / .Persistence.cs / .Bridge.cs / .Organization.cs — Integration points
  • SessionSidebar.razor / CreateSessionForm.razor / SessionListItem.razor — UI
  • Settings.razor — Alpha toggle
  • ConnectionSettings.cs / SessionOrganization.cs — Model additions
  • 8 test files (113 new tests)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions