feat: add experimental SSH remote workspaces for Claude workers by singular78 · Pull Request #366 · SeemSeam/claude_codex_bridge · GitHub
Skip to content

feat: add experimental SSH remote workspaces for Claude workers - #366

Draft
singular78 wants to merge 3 commits into
SeemSeam:mainfrom
singular78:feat/remote-workspaces
Draft

singular78 wants to merge 3 commits into
SeemSeam:mainfrom
singular78:feat/remote-workspaces

Conversation

@singular78

@singular78 singular78 commented Oct 5, 2026 •

Copy link
Copy Markdown

A provider command template can launch a CLI over SSH, but it does not transfer a task's workspace, return edited files, or make synchronization part of CCB completion. This adds an opt-in remote-workspace transaction boundary and a resumable SSH/tmux transport for pane-backed Claude workers. The local controller owns dispatch, callbacks, review and Git integration.

Implementation

  • Add remote_workspace to agent configuration, serialization and stored specs. It selects a controller-owned profile outside the project, bound to a dedicated Git worktree. Local-only projects use a no-op synchronizer without importing the Linux transport.
  • Prepare allowlisted inputs before dispatch; collect and validate results before terminal completion, replies, callbacks or worker-slot release. A sync error blocks the profile. Unexpected ordinary files outside the remote allowlist now block collection instead of silently dropping task output; credential, control and fixed cache exclusions stay excluded.
  • Exchange bounded Git objects and ordinary files, checking paths, modes, hashes and ancestry. Do not copy .git config/hooks, .ccb, provider homes or credentials. Default publication preserves local HEAD/index for native review and integration. Remote messages and returned code remain untrusted.
  • Keep Claude in a dedicated remote tmux session, mirror its pinned transcript over a separate SSH channel, and reconnect with offset/hash and boot/generation checks. Explicit recovery never replays a prompt. Deployment verification/rollback and conservative retention tools are included.
  • Explicitly enroll a launch baseline for source, configuration, tools and endpoint identity. Reject drift before startup or remote dispatch; detach probe stdin so piped task text survives. Check only configured local provider CLIs, and use the pinned Git/SSH paths. Remote-only Claude does not require local Codex/Claude. Diagnostics and recovery remain available while the endpoint is offline.
  • Repair the crash window after a synchronized child's completed record but before its reply. Restore the missing reply from durable state, then use native idempotent continuation recovery. Failed/incomplete/unsynchronized jobs are never promoted.
  • A separate follow-up commit recognizes Codex 0.158/0.159.3 two-row and warning footers while preserving busy, nonempty-draft and unknown-layout guards. This was needed by the local reviewer in the prototype acceptance flow.

Validation

  • Current 8.7.5-based branch: 896 passed, 3 skipped on Linux/WSL2 with Python 3.12. Covers remote sync/deployment, config, dispatch, callbacks, provider parsing/profiles, input guards and control-plane environment. The skipped tests require explicit disposable VPS settings.
  • Includes real subprocess SIGKILL at six synchronization and three terminal/reply/callback persistence windows, checking idempotent recovery and no duplicate execution/reply/continuation. Includes missing/changed launch baselines, piped-input preservation, configured-provider prerequisites, omitted-file rejection and symlink handling.
  • Optional bubblewrap/libseccomp verifier integration was enabled and passed. Changed Python files parse successfully; git diff --check passes.
  • The opt-in real SSH capacity test now reads host, remote parent and tool paths from an external settings file. It contains no deployment-specific host/user paths; normal test runs do not contact a VPS or run models.
  • Earlier full suite on initial PR commit becab71, excluding provider_blackbox and ccb_lifecycle_smoke: 7596 passed, 24 skipped, 42 deselected, 6 failed. All six failures reproduced on unmodified upstream 18bf0af; all six passed in an ASCII checkout with the dependency-equipped Python on PATH/CCB_PYTHON. That full suite was not rerun after this hardening update; the current focused result is above.

Separate prior prototype evidence (8.7.3-based acceptance branch): 480 regressions, three real SSH capacity/timeout-recovery cases, one normal VPS reboot with checkpoint recovery, and a real local Codex -> remote Claude -> file return -> review -> native integration flow ending accepted / verified. The model flow included tool approvals and one fixture scope correction; it was not entirely unattended. These results are not fresh live SSH/model acceptance of this 8.7.5 PR tip, and overlapping test counts are not additive. Private deployment settings and raw model logs are not included.

Scope and remaining limits

This remains an experimental draft: explicitly configured v2 agents, Linux/WSL2 controllers, Linux Claude workers, dedicated SHA-1 worktrees, linear history and ordinary files. Remote-originated CCB commands/passive reply delivery, merge histories, symlinks/submodules, dynamic/v3 remote provisioning and transparent project migration are unsupported.

Completion still holds the project chain lock during bounded synchronization (32 MiB object/file budget, 48 MiB wire budget). Large projects need streaming/incremental transfer and an asynchronous synchronization phase. Other writers must remain off the dedicated worktree: per-file conflict checks are not an atomic filesystem transaction against racing writers. The optional local verifier is separate; this interface does not sandbox arbitrary reviewer commands or the remote account. Preflight detects deployment drift, not compromise of a host or every wrapper subprocess.

Forced power loss during real model/tool execution, multi-day weak-network testing and multi-worker stress remain unverified. Upgrading an enrolled deployment requires reviewing/redeploying the endpoint, explicitly replacing its baseline and restarting an idle controller.

Upstream CI

On updated head 9e2d197, the Windows PR Isolation check still fails on diff-marker:win32 / diff-marker:windows. The trusted base checker classifies added/removed text, including unsupported-platform documentation and simulated platform tests, as Windows scope and then rejects shared paths. This patch changes no Windows-owned paths and adds no platforms.windows imports. Compatibility coverage and gate policy are retained; maintainer triage is needed.

The updated Tests and CCBD Real Platform Smoke runs both report action_required with zero jobs started. Upstream CI has therefore not yet validated this draft; the passing results above are local validation.

@SeemSeam

SeemSeam commented Oct 6, 2026

Copy link
Copy Markdown
Owner

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants