[PRD] Feature: Move/Teleport In-Progress Tasks Between CLI and Cloud

[enyst]

Summary

This issue proposes the ability to "teleport" or move in-progress tasks between the local CLI and OpenHands Cloud.

Background

This has been hinted at in OpenHands/OpenHands#6348 (comment)

This write-up is a follow-up from the discussion in ALL-3713 (specifically this comment) about teleport feature.

While ALL-3713 covers starting new conversations in the cloud, this issue addresses a different use case: moving tasks that have already started and have existing history.

Feature Description

Move Task from CLI to Cloud

A user may start a task locally in the CLI, work on it for a while (making commits, building up EventLog history), and then decide to move it to the cloud. Reasons might include:

• The task is taking longer than expected and they want it to continue running in the background
• They need to step away from their local machine
• They want to leverage cloud resources for the remainder of the task

The move should include:

• The current state of the conversation/task
• EventLog history
• Any commits made during the session
• Current working context

Move Task from Cloud to CLI

The reverse operation: a user has a conversation running in OpenHands Cloud and wants to "teleport" it back to their local CLI to continue working on it locally.

Important Notes

• This is a move operation, not a sync operation
• Once moved, the task continues in the new environment
• The original environment's instance of the task would be closed/archived
• Similar to Anthropic's approach, this likely requires the repository to be a GitHub repo (to avoid complex file synchronization)

Reference

• Anthropic's teleport feature announcement: https://x.com/trq212/status/1991977749821735341
• Related issue: ALL-3713 (Delegate a task to OpenHands Cloud)

Open Questions

1. What is the minimum state that needs to be transferred for a useful "teleport"?
2. How do we handle uncommitted local changes when moving to cloud?
3. Should there be any restrictions on when a task can be moved (e.g., not during active tool execution)?
4. How do we handle authentication/permissions when moving between environments?

[jpelletier1]

I really like the direction of this feature!

I have similar questions as you, Engel. My initial thoughts on a few of them.

Should there be any restrictions on when a task can be moved (e.g., not during active tool execution)?

I think this makes sense - e.g., make sure the conversation has stopped before you move it to Cloud (or vice-versa).

How do we handle authentication/permissions when moving between environments?

Maybe we require users to first connect their CLI to OpenHands Cloud using the openhands login command, and then that establishes a device link between CLI and Cloud.

[malhotra5]

When teleporting, how do we have installed dependencies? For example the local project may have the project installed, and even some other tooling available which may not be 1:1 when teleporting to a fresh sandbox

[malhotra5]

Re

How do we handle uncommitted local changes when moving to cloud?

We can detect this and warn the user that there are local changes that haven't been pushed, and will not transfer with the teleport unless its pushed

alternatively we can maybe grab the diffs and reapply them on the cloud instance? maybe cap the diff sizes?

QQ: when working in a directory with multiple repositories (for example working across two repos like the sdk + cli), what should be the expected behavior?

[enyst]

QQ: when working in a directory with multiple repositories (for example working across two repos like the sdk + cli), what should be the expected behavior?

I think, I’d tell the agent (if we know). That is, if we are in a sandbox to begin with, like on the cloud, then I think we can know, because we can look at ls -l workspace/project. Although I saw the agent installing the SDK inside the CLI directory before. 😅

Maybe we could send at the end of teleport message (we send a teleport message?):

This session uses repo1 and repo2. Clone yourself these repositories if you don’t have them in [workspace folder].

🤔 Or not… That risks to make it clone locally inside whatever directory it is…

I’ve done the simplest thing here, just told the agent what happened: (maybe we want more)

• Teleport to remote

const introLines = [
        'Teleported from the local VS Code runtime after a HIGH-risk confirmation.',
        `Repo: ${repoName}`,
        `Branch: ${branchName}`,
      ];

It also tells the agent

“Note: uncommitted local changes may not be present remotely.”

🤔 which makes sense if we transfer the whole history, because it will see it has done stuff, and when it sees the changes are not present, it can figure out why, without getting confused.

We can detect this and warn the user that there are local changes

See, that makes sense! I made sure to tell the LLM and called it a day, your thought is about the user ❤️

[enyst]

When teleporting, how do we have installed dependencies? For example the local project may have the project installed, and even some other tooling available which may not be 1:1 when teleporting to a fresh sandbox

Two options?

• tell the agent
• in the measure they were installed by the current history, a “replay” like in the old days could fix it on the cloud.

I think… we are at the point where just “tell the agent” will work well in a lot of cases, with SOTA LLMs. Maybe like:

Your session has been teleported from the user’s local machine to a remote docker environment. It is possible it had tooling installed that you used there, and you may need to install for yourself in this environment. You can install them when you need them, no need to rush.

[enyst]

alternatively we can maybe grab the diffs and reapply them on the cloud instance? maybe cap the diff sizes?

The edits are in agent’s history, and I think a clear enough warning / info that its changed after the last push will not be available and it may need to redo them should suffice. 🤔 The LLM capabilities are there, they can re-check and re-make some stuff that got missed.

I think maybe we can try, and thus keep it simple for now. If it runs into trouble, we can consider a manual workflow getting diffs / sending diffs, WDYT?

[enyst]

e.g., make sure the conversation has stopped before you move it to Cloud (or vice-versa).

Definitely. We should leave the other conversation in a stable state, that is, maybe not while it’s waiting for confirmation. 😅
(I’ve had that problem when the old conversation reloaded, it was asking the user to confirm… endlessly. 🫠)

Just some thoughts as an aside, prompted by this discussion, but more about V0/V1 and testing agents-vs-the-cloud:

I, or rather my little agent team, made a list of servers, and tested first with a server I called “remote-local”: the agent-server simply running on a port. (very inspired name… not 🫠)

So it just made a ws connection and showed stuff running on it.

Just now, my agents were figuring out how to connect to the cloud, and run there. They were very confused btw, because

1. they thought that the CLI cloud key is “session api key”
2. they thought they should connect to a remote agent-server, when in fact they need to connect to the app-server.

Now they made a doc, to serve implementation, and I’m curious about this detail

Rohit, I wonder, if this is accurate (and it seems it is?), why connect to a legacy V0 endpoint? Or is this V1-ish? Just curious, I’m learning!

[malhotra5]

Rohit, I wonder, if this is accurate (and it seems it is?), why connect to a legacy V0 endpoint? Or is this V1-ish? Just curious, I’m learning!

Ah thanks for the catch, yes we should move everything to V1 endpoints, simply an oversight on which endpoint was being reached

[malhotra5]

To summarize, here is the MVP breakdown. We're aiming to start with the ability to pull cloud conversations locally. We'll achieve this via these steps

1. ensure agent isn't actively working
2. copy agent trajectory to local system
3. run git commands remotely to warn user if any changes have not been pushed (if they choose to proceed without committing changes, let the agent know in step 5)
4. run git commands remotely to identify latest git commit ID
5. checkout to the commit/branch locally and let agent know that it has been teleported

For teleporting local changes to cloud we perform similar steps

1. ensure agent isn't actively working
2. check for any local changes that haven't been pushed and warn users if thats the case
3. create cloud conversation with local agent trajectory
4. let agent know its been teleported
5. checkout to latest commit (agent can handle this by itself most likely)

We rely on the git ecosystem for starters as we don't have to manage synchronizing files.

To recap the answers to the questions posed in the issue description -

What is the minimum state that needs to be transferred for a useful "teleport"?

A valid git commit for a repo

How do we handle uncommitted local changes when moving to cloud?

We warn the user about uncommitted changes. They can choose to commit the changes and re-try the teleport, or just proceed without the uncommitted change.s

Should there be any restrictions on when a task can be moved (e.g., not during active tool execution)?

When the agent isn't actively running

How do we handle authentication/permissions when moving between environments?

Use the existing CLI <> Cloud authentication we have

Ideally, this will give us our MVP and from there we can iterate as we learn more about the user experience and needs (e.g more accurate file synchronization, etc). LMK!