Skip to content
Wayland Docs

Flux Failover and Resilience

When you are in a conversation and the model backend stops responding, whether from a credential error, a provider outage, or a dropped connection, Wayland does not silently fail. It surfaces a remedy card in the conversation and gives you a single action to continue without losing your context.

This page explains what that mechanism is and why it works the way it does.

The problem: mid-conversation backend failure

Section titled “The problem: mid-conversation backend failure”

Agent backends like Claude Code, Codex, and the Wayland engine maintain a live connection to their provider. If that connection drops or returns an auth error (for example, a 401 from the upstream API), the current turn fails and the backend can no longer accept new turns.

At that point you have a choice: try to fix the provider configuration, switch to a different model manually, or have Wayland handle the recovery automatically. The Flux failover is the automatic path.

What happens when failover triggers

Section titled “What happens when failover triggers”

When Wayland detects a disconnected backend mid-conversation, it shows a remedy card in the conversation thread. The card offers one action: Route through Flux and replay.

Clicking that action runs a four-step chain:

  1. Connect Flux. Wayland opens a Flux Router connection. If you do not already have a Flux key, the connect flow prompts you to add one. If the connect step fails, the remedy card stays up. No state is lost.

  2. Switch the conversation to Flux. The conversation is re-spawned with the Flux provider. The full conversation history travels with it. Your context is preserved.

  3. Replay the failed turn. The message that was in-flight when the backend died is replayed automatically into the new connection. You do not need to retype or copy it.

  4. Clear the remedy card. Only after the full chain succeeds does Wayland remove the remedy card. A partial failure (for example, Flux connected but the model switch failed) leaves the card up and shows an error, so you always have an explicit affordance to retry.

The entire sequence is guarded against double-triggers. If you click the button while a failover is already in progress for that conversation, the second click is dropped. The in-flight chain completes and the card clears on success.

The diagram below shows the full sequence, including the guard against a second click while failover is in flight.

sequenceDiagram
    actor User
    participant Conv as Conversation
    participant Backend as "Original backend"
    participant Card as "Remedy card"
    participant Flux as "Flux Router"

    Backend->>Conv: Error (session unrecoverable)
    Conv->>Card: Show remedy card
    User->>Card: Click "Route through Flux and replay"
    Card->>Card: Lock (drop any second click)
    Card->>Flux: Connect Flux
    alt Flux connect fails
        Flux-->>Card: Error
        Card->>Card: Stay visible (no state lost)
    else Flux connect succeeds
        Flux-->>Card: Connected
        Card->>Conv: Re-spawn conversation on Flux
        Conv->>Conv: Full history preserved
        Conv->>Flux: Replay failed turn
        Flux-->>Conv: Response
        Conv->>Card: Clear remedy card
    end

Which backends it covers

Section titled “Which backends it covers”

Flux failover is wired into the ACP (Agent Control Protocol) conversation platform, which handles the desktop app’s connections to agent backends. That includes:

  • Claude Code (claude CLI backend)
  • Codex (OpenAI Codex backend)
  • The Wayland engine (wayland-core ACP backend)

If one of these backends returns an error that indicates the session is unrecoverable, the remedy card appears. The failover then routes the conversation through Flux Router for the remainder of the session.

What Flux Router is in this context

Section titled “What Flux Router is in this context”

Flux Router is a multi-provider routing layer with broad model coverage. When a specific backend goes down, Flux provides a stable fallback that Wayland can reconnect to without requiring you to configure an additional provider or switch conversations manually.

If you do not have a Flux key when failover triggers, the connect step in the chain walks you through obtaining one. The key is stored and available for future failovers.

Context preservation

Section titled “Context preservation”

The failover preserves context through the model switch because the full conversation history is passed to the re-spawned agent on the new connection. From the model’s perspective it is resuming an existing thread, not starting a new one. The replayed turn picks up from exactly where the failed turn left off.

The one case where context could be reduced is if the conversation is long enough to hit the new model’s context window limit. In that case Wayland’s normal context compression rules apply.

Next

Section titled “Next”