Oz > Handoff

Handoff from the terminal UI to the cloud

Fork a local Warp Agent conversation into an Oz cloud run from the terminal UI with the /handoff command, preserving your transcript, workspace changes, and attachments.

The /handoff command forks an in-progress local Warp Agent conversation in the terminal UI into an Oz cloud agent run. Warp keeps your local transcript visible, gathers the cloud configuration in a blocking card, transfers the applicable local context, and then lets you open the cloud run, continue locally, or start a new conversation.

Key features

Keyboard-first handoff - Run /handoff with an optional prompt and complete the entire flow from the card without leaving the terminal.
Preserved local conversation - Handoff forks your conversation, so the local transcript stays intact and you can keep working locally after the cloud run starts.
Context transfer - The cloud run inherits your conversation history, a snapshot of your workspace changes when one is available, and any pending image attachments.
Explicit next steps - After the cloud run is created, you choose whether to open it, continue locally, or start a new conversation.

How it works

/handoff moves work from a local Warp Agent conversation into a cloud run without discarding the local session. Instead of replacing the current conversation with a cloud view, Warp forks the conversation so the source transcript remains available and the forked nature of the handoff stays clear.

Handoff always runs remotely on the Oz harness. You choose the environment and the model for the cloud run — execution location, harness, worker host, and API key are not configurable from the terminal UI.

What carries over

A forked conversation - For a conversation that already has content, handoff creates an independent cloud fork. The original local conversation and transcript stay available and do not sync with later cloud changes.
A workspace snapshot - Warp waits for the local workspace snapshot to settle before creating the cloud run. If deriving or uploading the snapshot fails, handoff is not blocked — it continues without the snapshot, and your conversation history is still handed off.
Pending images - Images attached to your local input move with the handoff prompt and are included in the cloud run.

For more on what the snapshot captures and how it is applied, see Snapshots.

The initial cloud prompt

If you provide a prompt with /handoff <prompt>, it is sent to the cloud run unchanged (apart from trimming surrounding whitespace and the same query-mode parsing that applies to normal prompts).

If you run /handoff with no prompt, Warp derives the initial prompt from the state of the source conversation:

Interrupted work with a snapshot - Continue. Apply the workspace changes from my previous session.
Interrupted work without a snapshot - Continue.
Idle conversation with a snapshot - Apply the workspace changes from my previous session.
Idle conversation without a snapshot - No initial prompt is sent.

Handing off a conversation to the cloud

Use /handoff when a local conversation has grown into work that is better suited to the cloud — long-running tasks, parallel variants, or work you want to steer from another device.

Prerequisites

A local Warp Agent conversation - Have the conversation you want to hand off selected in the terminal UI.
Handoff enabled - Your handoff settings, account policy, privacy settings, AI availability, and platform must permit local-to-cloud handoff.
A cloud environment - The cloud run needs an environment. If you have none, the card links you to Oz to create one.

Start the handoff

In a local Warp Agent conversation, select /handoff from the slash-command menu. This inserts /handoff into the input instead of running immediately; ghost text indicates that adding a prompt is optional.
Submit either /handoff on its own or /handoff <prompt> with the initial prompt for the cloud run.
Warp cancels any in-progress local response and opens the Hand off to cloud card below your transcript. The transcript stays visible and unchanged.

Configure the cloud run

The card shows exactly two editable values: Environment and Model.

Warp preselects your saved or recent environment when one is available. While the card is open, Warp also inspects the current directory’s Git repository in the background and may suggest a matching environment, unless you have already chosen one yourself.
The model starts as your local conversation’s model when that model can run in Oz cloud. If it can’t, the card marks the model as (incompatible), confirmation stays unavailable, and you must choose a compatible model — Warp never silently substitutes another model.
From the card summary, press Enter to hand off, Ctrl + E to edit the configuration, or Ctrl + C to cancel.
When editing, the card shows two searchable selector pages in order — environment, then model. Press Enter to accept the highlighted value and advance, Tab or the left/right arrows to move between pages, and Esc to return to the summary.

Confirm and track the run

Press Enter on a valid configuration to commit the handoff. Confirmation is the point of no return: the configuration and cancellation controls disappear, the card shows Creating cloud run…, and local input stays blocked until the run is created or handoff fails. Ctrl + C is ignored while handoff is in progress.
Once Warp receives a cloud run identifier, the card becomes a static created card. It does not keep tracking the cloud task’s queued, running, or completed state.
On the created card, press Enter to open the cloud run in your browser, C to continue locally, or N to start a new conversation.

Opening the cloud run launches its Oz URL in your system browser. It does not dismiss the card, replace the transcript, or unblock local input.

After handoff

Continue locally - The created card collapses into a compact banner in your transcript at the handoff location. It reads Conversation forked to cloud; continuing locally with the cloud-run link on the next row, and clean local input reopens so you can keep working.
Start new conversation - Warp removes the card and starts a new conversation without adding the transcript banner.

If handoff fails after confirmation, Warp removes the card, reopens local input, restores your prompt argument and pending images, and shows a transient error. There is no in-card retry — run /handoff again to try once more.

Handoff overview - What handoff is, the directions it supports, and what carries over.
Handoff from local to cloud - The equivalent flow in the Warp desktop app.
Snapshots - How Warp captures and applies workspace changes during handoff.
Environments - Configure the repos, image, and setup commands the cloud agent starts in.
Cloud-synced conversations - How conversations sync between local and cloud so handoff can find them.