stablyai / stablyai/orca

[Feature]: multi-endpoint auto-switching for desktop remote runtime environments (orca environment)

Open
#16,617 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
71.3k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

### Problem or use case

`orca environment add` saves exactly one websocket endpoint from the pairing offer. If that address becomes unreachable (laptop leaves the LAN, Tailscale path changes, host IP changes), the client only retries the same endpoint with backoff. The only recovery is to re-pair with a different `--pairing-address`.

The mobile app already solved this: `HostProfile.endpoints` stores up to 16 candidates (direct + relay), `mobile-direct-endpoint-probe` races all direct endpoints in parallel, direct vs relay is raced happy-eyeballs style, and `MobileEndpointHysteresis` upgrades back to direct automatically. None of that machinery exists for desktop/CLI runtime environments, and relay is currently excluded for `runtime` scope entirely.

Typical topology is the same as in #15615:

```text
orca serve :6768
LAN ws://192.168.x.x:6768
Tailscale ws://100.x.y.z:6768
```

Today the environment record can hold only one of these.

### Proposed solution

Apply the same candidate model to runtime environments:

1. Let the pairing offer (or `orca serve`) advertise multiple direct endpoints, and store them all in the saved environment.
2. On connect and on reconnect, race the known candidates and use the first that succeeds, like the mobile transport stack does.
3. Optionally allow relay as a last-resort candidate for `runtime` scope.

### Alternatives or additional context

- Workaround today: save multiple environments for the same server (one per address) and switch manually.
- #15615 proposes multi-candidate advertising for mobile pairing; #15491 proposes syncing direct endpoints post-pairing. This issue asks for the same capability on the desktop/CLI `orca environment` path, where reconnect issues like #9092 and #12684 would also be mitigated.

Contributor guide

Open the contributing guide

Research direction

Start at the `orca environment add` and `orca serve` pairing paths, then study the mobile `HostProfile.endpoints`, `mobile-direct-endpoint-probe`, and `MobileEndpointHysteresis` machinery. Determine how runtime candidates are advertised and persisted, and how reconnect selects among them. Done means runtime environments can retain multiple candidates and automatically reconnect through a working endpoint, with relay behavior resolved explicitly.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.