Worktree SSH

Orca có thể điều khiển agent trên máy remote qua SSH - hữu ích cho build chạy dài, GPU box, hoặc bất kỳ môi trường nào mà laptop của bạn không phải nơi phù hợp để chạy công việc.

Một trong bốn chế độ chạy

SSH là một cách để đưa agent lên compute remote. Với local, server tự host, và VM tạm thời, xem Các cách chạy Orca.

Thêm một SSH target

1. Mở Settings → SSH.
2. Click Add Target. Form host mở trong một modal (không inline dưới danh sách), để Host, Advanced, và Save luôn dễ với tới kể cả khi danh sách host dài. Edit dùng cùng dialog và hiện nhãn target cộng user@host:port.
3. Điền host, user, port, và file identity tuỳ chọn - hoặc mở bộ chọn OpenSSH config trong cùng dialog để tìm trong ~/.ssh/config (kể cả các file được Include), chọn một host, và tự điền form. Host đã lưu sẵn trong Orca hiện badge In Orca. Bạn vẫn có thể import hàng loạt host từ config khi luồng đó khả dụng.
4. Nếu key có bảo vệ bằng passphrase, Orca sẽ hỏi ở lần đầu.
5. Click Test để xác minh kết nối, rồi Save.

Form add/edit đang có thay đổi chưa lưu sẽ bỏ qua click ra ngoài, để một cú click lỡ tay không làm mất dữ liệu bạn đã nhập; dùng Escape, Cancel, hoặc × để hủy bỏ.

Dùng một target

Khi tạo worktree, chọn một SSH target thay vì Local. Orca sẽ:

• Tạo git worktree trên host remote.
• Chạy agent từ xa qua kết nối SSH.
• Đồng bộ sự kiện file để editor, diff, và trình duyệt vẫn có cảm giác như local.

Tuỳ chọn kết nối nâng cao

Mở Settings → SSH, sửa một target, và mở rộng Advanced Connection khi host cần proxy, jump host, hoặc override multiplex SSH. Orca mặc định bật Reuse SSH connection for faster setup, dùng cơ chế reuse connection của OpenSSH trên macOS và Linux để các lệnh setup không phải trả phí bắt tay SSH mới mỗi lần. Chỉ tắt nó với các host có chính sách SSH từ chối session multiplex.

Passphrase

Passphrase được giữ trong bộ nhớ trong suốt vòng đời session Orca. Đóng Orca sẽ xóa chúng. Bạn có thể opt-in một TTL dài hơn trong settings SSH.

Trạng thái

Worktree remote hiện một chip trạng thái SSH live - xanh lá là connected, vàng là reconnecting, đỏ là disconnected. Trong lúc một host SSH vẫn đang kết nối, Orca có thể liệt kê workspace từ metadata local đã lưu, để sidebar không trống cho tới khi provider live sẵn sàng; các dòng đó refresh về state remote chính xác một khi kết nối đã ổn định. Mất kết nối không giết agent đang chạy; Orca sẽ reconnect và reattach lại. Khi một host rớt kết nối, card workspace bị ảnh hưởng có thể hiện control Connect / reconnect inline để bạn khôi phục mà không cần mở overlay terminal hay tìm trên status bar. Nếu một relay SSH rớt kiểu lỗi “Multiplexer disposed”, Orca tự phục hồi thay vì để pane kẹt cho tới khi bạn restart. Trạng thái agent (working / idle / blocked) truyền qua SSH giống hệt như local, nên sidebar và Agents feed phản ánh agent remote theo thời gian thực.

Session qua các lần đóng app

Đóng app desktop không còn giết session PTY remote của bạn nữa. Session terminal remote được lease qua relay chạy trên host remote, nên chúng sống sót qua việc Orca đóng trên laptop của bạn. Khi mở lại app và reconnect tới target, các PTY đã lease được khôi phục về đúng tab ở trạng thái attached, với scrollback còn nguyên. Một khoảng grace period ngắn (mặc định 5 phút, cấu hình được theo từng target) cho relay thời gian để chịu đựng một lần reconnect nhanh trước khi dỡ các session đã detach.

Tải file và thư mục remote

Right-click trong file explorer của worktree SSH:

• File → Download - dialog lưu file kiểu native; copy file về laptop của bạn.
• Folder → Download Folder - tải đệ quy vào một thư mục bạn chọn (chỉ desktop).

Orca dùng cùng đường truyền SSH với kết nối. Download Folder chỉ xuất hiện khi kết nối công bố hỗ trợ truyền thư mục đệ quy (thường là SFTP đầy đủ). Kết nối chỉ dùng transport OpenSSH hệ thống vẫn có thể tải file nhưng không hiện Download Folder.

Đây là action chỉ dành cho desktop - web client không có Download vì nó dựa vào dialog lưu của Electron.

Mở một workspace remote trong VS Code

Với worktree SSH, danh sách Open in của menu worktree có thể chuyển đường dẫn remote cho VS Code Remote-SSH khi app đã cấu hình là VS Code hoặc VS Code Insiders (code / code-insiders, hoặc một đường dẫn trực tiếp tới các launcher đó).

1. Cấu hình Settings → General → Open in menu để VS Code có trong danh sách (preset hoặc lệnh tuỳ chỉnh).
2. Right-click worktree SSH (hoặc dùng menu overflow của worktree) → Open in → VS Code.
3. Orca khởi chạy VS Code với Remote-SSH nhắm tới host đó và đường dẫn worktree (--remote ssh-remote+<host> <path>). Mục menu có thể hiện badge Remote SSH.

Không hỗ trợ cho đường remote này: Cursor, Zed, lệnh shell ghép, hoặc mở qua một runtime Remote Orca Server đang active (những cái đó giữ nguyên Local only). Chỉ dùng mục Finder/Explorer cho đường dẫn local.

Kerberos / GSSAPI

Nếu một host trong config OpenSSH đặt GSSAPIAuthentication yes, Orca ưu tiên dùng transport OpenSSH hệ thống cho target đó (client ssh2 tích hợp không nói được GSSAPI). Giữ một Kerberos ticket hợp lệ (kinit / SSO của tổ chức bạn) trước khi kết nối. Target thủ công cũng có thể bật GSSAPI khi cấu hình dùng SSH hệ thống.

Bạn không cần bật riêng một công tắc “Kerberos mode” cho host import từ config - import/ssh -G tự mang theo flag đó.

FIDO2 / security key

Identity OpenSSH có phần cứng hỗ trợ (ed25519-sk, ecdsa-sk, kể cả security key qua agent) cũng dùng OpenSSH hệ thống thay vì client ssh2 tích hợp. Orca nhận diện loại key từ file identity của bạn và giao kết nối cho binary OpenSSH của hệ điều hành để prompt chạm/PIN hoạt động như bình thường. Key Ed25519, ECDSA, và RSA thông thường vẫn dùng transport tích hợp. Nếu máy không có OpenSSH, các target FIDO2 đó không xác thực được cho tới khi OpenSSH được cài và có trong PATH (hoặc ở vị trí thường gặp trên Windows/macOS/Linux).

Host Linux thiếu toolchain C/C++

Ở lần kết nối đầu tiên, Orca cài một relay nhỏ trên máy remote. Terminal remote cần một module node-pty native. Gói Linux thường phải compile trên host; relay macOS/Windows dùng prebuild sẵn.

Nếu remote thiếu make, một C++ compiler, và python3, Orca vẫn hoàn tất kết nối cho file, git, và editor, nhưng terminal remote sẽ không hoạt động cho tới khi build tool được cài. Ví dụ gợi ý cài đặt Orca có thể hiện:

• Debian/Ubuntu: sudo apt-get install -y build-essential python3
• Fedora/RHEL: sudo dnf install -y make gcc gcc-c++ python3
• Alpine: sudo apk add build-base python3
• Arch: sudo pacman -S --needed base-devel python

Cài các tool đó, rồi reconnect để relay có thể cài module native.

Port forwarding

Với worktree remote, sidebar phải hiện một tab Ports (toggle bằng Cmd+Shift+I). Orca quét /proc/net/tcp trên remote và liệt kê các port đang listen dưới Detected - một click để forward chúng về laptop của bạn. Bạn cũng có thể thêm forward thủ công, sửa, hoặc xóa. Forward tồn tại qua các lần restart app và reconnect SSH, và các port remote privileged tự remap sang local (ví dụ remote 80 → local 10080).

Nguồn

Dịch và biên soạn từ trang SSH worktrees trong tài liệu chính thức của Orca ADE (onorca.dev).