Agents > Handoff

Handoff from local to cloud

Promote a local Warp Agent conversation to a cloud agent run with the full transcript and your uncommitted workspace changes — without re-explaining the task.

Hand off a local Warp conversation to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh.

Use this handoff direction when:

You have a long-running task and don’t want to keep your laptop awake.
You want to fan out variants of the same task across multiple cloud agents in parallel.
You want to walk away and check on the agent from a different device.
You want the agent to keep working while you start a new conversation locally.

What the cloud agent receives

When you hand off from local to cloud, the receiving cloud agent inherits:

A forked conversation - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See Cloud-synced conversations for related sync behavior.
A workspace snapshot - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up.
Conversation attachments - Files attached to the local conversation remain available in the cloud run.

If applying any change fails in the cloud run, the cloud agent reports what couldn’t be applied and proceeds with what it could rather than silently dropping changes.

Prerequisites

An active local conversation - Have an Agent conversation open in Warp with the work you want to hand off.
A configured environment - The cloud agent needs an environment that includes the same repositories you’re working in locally. The environment’s repos must match your local checkout so the workspace snapshot applies cleanly.
Cloud conversation storage enabled - In the Warp app, go to Settings > Privacy and turn on Store AI conversations in the cloud so the conversation can be forked. See Cloud-synced conversations.
Sufficient credits - Cloud agent runs consume credits. See Credits for how credit usage works, and Access, billing, and identity for team-specific credit requirements.

Handing off a conversation to the cloud

Open the handoff flow from your active conversation. With the local conversation focused, press & or run the /handoff slash command. Either entry point opens the handoff flow scoped to the current conversation. The /cloud-agent slash command always starts a fresh cloud conversation and isn’t an entry point for handoff.
Choose the environment for the cloud run. Pick the one whose repositories match the directories your local conversation has been editing. If you don’t have a matching environment yet, create one and add the repos you’ve been working in.
Add a follow-up prompt and submit. Enter the next message you want the cloud agent to act on.

After you submit, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it.

To check on the new run, open it from the Runs page in the Oz web app or the conversation panel.

Troubleshooting

The cloud agent reports that some changes couldn’t be applied. The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo’s current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment’s repo to the branch you were on locally and retry the handoff.

The cloud agent doesn’t see my uncommitted changes. Cloud conversation storage must be enabled for handoff to work. In the Warp app, open Settings > Privacy and confirm Store AI conversations in the cloud is on. Otherwise, the conversation can’t be forked and the run falls back to starting fresh.

The conversation doesn’t appear in the cloud run. The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator.

Handoff overview - What handoff is, the directions it supports, and what carries over.
Handoff from cloud to cloud - Continue a finished cloud run with workspace state restored.
Environments - Configure the repos, image, and setup commands the cloud agent starts in.
Cloud agents quickstart - Run your first cloud agent from scratch.