Remote Orca Server

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Giữ Orca chạy trên một máy tính khác và kết nối từ laptop của bạn.

Một Remote Orca Server cho phép một máy làm việc trong khi máy khác chỉ cung cấp UI. Server giữ project, worktree, terminal, tab, tài khoản provider, và session agent. Laptop của bạn kết nối tới instance Orca đang chạy đó.

Cách cài đặt dễ nhất là app desktop Orca trên cả hai máy, kết nối qua Tailscale. Bạn không cần chạy orca serve cho đường này.

Cái gì chạy ở đâu

Máy client · Orca client
  Hiện UI và gửi input của bạn
  │
  │ đường mạng riêng
  ▼
Máy server · Orca server
  Lưu repo và worktree
  Chạy terminal và agent

Cài và xác thực Codex, Claude Code, OpenCode, git, và bất kỳ CLI provider nào trên máy server. Đăng nhập trên laptop của bạn không tự động chuyển sang server.

Trên một host orca serve headless, đăng ký tài khoản Claude/Codex được quản lý từ shell của server (client remote sẽ tắt Add account):

orca account add --agent claude
orca account add --agent codex
orca account list

Cài hoặc refresh skill agent mà không cần Settings UI:

orca skills install --skill orca-cli --skill orchestration
orca skills update --all

Khuyến nghị: app desktop + Tailscale

Bạn cần:

Orca đã cài và cập nhật trên cả hai máy.
Tailscale đã cài trên cả hai máy.
Cả hai máy đăng nhập cùng một tailnet.
Máy server đang thức, online, và chạy Orca.

Tailscale cấp cho server một địa chỉ riêng thường bắt đầu bằng 100.. Orca đặt địa chỉ đó lên đầu trong bộ chọn địa chỉ kết nối.

1. Tạo access link trên server

Trên máy nên giữ các session chạy:

Mở app desktop Orca.
Mở Settings → Remote Orca Servers.
Dưới Advertise this app as a server, click New Link.
Với Connection address, chọn địa chỉ Tailscale. Thường có dạng 100.x.y.z.
Click Generate Access Link.
Copy link dưới Pair another Orca client.

Nếu thiếu địa chỉ Tailscale, xác nhận Tailscale đang kết nối và click nút refresh cạnh Connection address.

Trên server: chọn địa chỉ Tailscale, tạo access link, và copy pairing URL đã che bớt. Quyền cấp có thể thu hồi sau

2. Thêm server trên laptop của bạn

Trên máy bạn muốn dùng làm client:

Mở Settings → Remote Orca Servers.
Click Add Server.
Nhập một tên dễ nhận biết, ví dụ Remote Server.
Dán access link từ server.
Click Add Server.
Nếu server đã lưu hiện Disconnected, click Connect.

Trên client: đặt tên server, dán access link của nó, và thêm vào. Mã pairing đã bị che trong ví dụ này

Thêm một server sẽ lưu nó lại mà không ép mọi project mới dùng nó. Chỉ mở Advanced → Active Server khi bạn muốn project, terminal, kiểm tra provider, và bàn giao trình duyệt hoặc mobile định tuyến qua server đó mặc định.

Dùng remote server

Khi server hiện Connected, chọn nó hoặc một trong các project của nó và dùng Orca như bình thường. Terminal, process agent, file, worktree, và state session nằm trên máy server.

Khi nhiều client đã pair dùng chung server đó, filter sidebar có thể đưa ra Hide other-client workspaces để thiết bị này chỉ liệt kê workspace nó tự tạo. Xem Worktree → Bố cục sidebar.

Điều đó nghĩa là:

Agent tiếp tục chạy khi laptop client ngủ hoặc mất kết nối.
Server cần repository, tool, và credential mà các agent đó dùng.
Server phải luôn thức và kết nối với tailnet.
Reconnect client sẽ đưa bạn về đúng state server sở hữu.
Project bạn xóa trên server sẽ biến mất khỏi sidebar của mọi client đã pair (không còn dòng ma vĩnh viễn).

Truy cập và bảo mật

Orca tạo một token riêng, thu hồi được cho mỗi client đã pair. Server liệt kê chúng dưới Shared Server Access.

Click nút thùng rác cạnh một quyền cấp để thu hồi nó. Client đang active dùng quyền đó bị ngắt kết nối ngay lập tức.
Tạo một link khác sẽ thay thế link chưa dùng trước đó. Client đã pair sẵn giữ nguyên quyền của họ cho tới khi bạn thu hồi.
Giữ ACL hoặc quyền cấp Tailscale hẹp nhất có thể theo setup của bạn.
Không forward port Orca trực tiếp ra internet công cộng. Ưu tiên Tailscale, WireGuard, một LAN tin cậy, forward qua SSH, hoặc một tunnel đã xác thực.
Không chọn 127.0.0.1 cho một máy khác. Địa chỉ đó chỉ hoạt động trên chính server.

Cách khác: `orca serve`

Dùng orca serve khi host nên chạy mà không có cửa sổ desktop - ví dụ một server Linux headless hoặc một VM do service quản lý. Với MacBook hay desktop bạn có thể để đăng nhập sẵn, cách setup trong app ở trên đơn giản hơn.

Cài Orca và CLI đi kèm của nó trên server, rồi chạy:

orca serve --pairing-address <server-tailscale-ip-or-hostname>

Ví dụ:

orca serve --pairing-address 100.64.1.20

Lệnh này:

Khởi động runtime Orca mà không mở cửa sổ desktop.
Chạy ở foreground cho tới khi bạn bấm Ctrl-C.
In ra endpoint đã bind và một pairing URL cho runtime.
Chỉ dùng --pairing-address cho địa chỉ mà client nên gọi vào.

Dán pairing URL được in ra vào Settings → Remote Orca Servers → Add Server trên client.

Thêm --port 6768 khi firewall, tunnel, hoặc định nghĩa service yêu cầu một port cố định:

orca serve --port 6768 --pairing-address 100.64.1.20

Chỉ dùng một chế độ host tại một thời điểm. Nếu app desktop Orca đã chia sẻ máy đó rồi, đừng khởi động thêm một process orca serve thứ hai cho cùng một setup.

Mobile từ một server headless

Với app Orca Mobile, yêu cầu một mã QR và link giới hạn cho mobile:

orca serve --pairing-address 100.64.1.20 --mobile-pairing

Giữ điện thoại trên cùng tailnet, mở Orca Mobile, chọn Pair, và scan mã QR trên terminal hoặc dán link được in ra.

App desktop hay `orca serve`?

	App desktop trên server	`orca serve`
Phù hợp nhất cho	Một laptop cũ, Mac mini, hay desktop	Một máy Linux headless, VM, hoặc service được quản lý
Cài đặt	Settings và nút bấm	Lệnh terminal và cấu hình service
Cửa sổ server	Có mở	Không có
Access link	New Link → Generate Access Link	In ra trên terminal
Vòng đời	Trong lúc app desktop đang chạy	Trong lúc process foreground hoặc service đang chạy

Remote Orca Server hay SSH?

Dùng Worktree SSH khi Orca trên laptop của bạn nên sở hữu runtime và chỉ dùng máy khác để chạy các worktree và terminal được chọn.

Dùng Remote Orca Server khi máy khác nên sở hữu toàn bộ runtime Orca và giữ session dùng chung cho client desktop, browser, mobile, hoặc automation.

Xem Các cách chạy Orca để so sánh đầy đủ.

Xử lý sự cố

Không thấy địa chỉ Tailscale trong danh sách

Trên server, xác nhận Tailscale đang kết nối, rồi click nút refresh cạnh Connection address. Cả hai máy phải đăng nhập cùng một tailnet. Địa chỉ IPv4 Tailscale thường bắt đầu bằng 100..

Server bị disconnected

Xác nhận máy server đang thức, Orca vẫn đang chạy, và Tailscale hiện cả hai thiết bị online. Kiểm tra ACL hoặc quyền cấp của tailnet nếu một thiết bị không tới được thiết bị kia.

Cập nhật Orca trên cả hai máy nếu dòng server báo phiên bản protocol không tương thích.

Access link bị chia sẻ nhầm người

Trên server, mở Settings → Remote Orca Servers → Shared Server Access và thu hồi quyền cấp đó. Tạo một link mới cho đúng client dự định.

Server không tìm thấy một CLI agent

Cài và xác thực CLI đó trên máy server. Session remote dùng PATH, home directory, và credential của server - không phải của client.

`orca serve` công bố sai địa chỉ

Dừng lệnh và khởi động lại với một địa chỉ client có thể tới được:

orca serve --pairing-address <reachable-tailscale-ip-or-hostname>

Không dùng địa chỉ wildcard hay 127.0.0.1 cho một client remote.

Bước tiếp theo

So sánh mọi chế độ chạy trong Các cách chạy Orca.
Dùng Worktree SSH khi laptop nên sở hữu runtime Orca.
Xem Orca CLI reference để biết flag của orca serve và các lệnh automation.

Phuc Tran

Software Engineer | Learning Claude