working-across-computers

Working Across Computers

Discover access before declaring a limitation

The current filesystem is not the full set of computers you can use. When a request needs another computer, run letta teleport list. If a suitable computer is available, delegate there; otherwise follow the connection instructions. Do not infer that another computer is inaccessible merely because you are running in Cloud.

Choose where to work

• When running in Cloud, prefer staying there and delegating local work to subagents on the relevant computer.
• If the user explicitly asks to move this conversation locally or elsewhere, teleport it.
• Moving a conversation that started locally into Cloud is a normal workflow: transfer needed files first, then teleport.

Intent	Mechanism
Run work elsewhere while staying here	Agent
Bring a remote file into a Cloud conversation	Remote agent: sandbox upload
Put a Cloud file onto another computer	Remote agent: sandbox download
Continue this conversation elsewhere	teleport

Conversation history and agent memory follow the conversation. Files, working directories, installed tools, credentials, and running services belong to each computer; teleporting does not copy the workspace.

For remote subagents, set computer and pass source paths and destination conversation IDs explicitly. Use the Agent tool definition for invocation and resume options.

If the user wants to connect a new computer, letta teleport list has no suitable target, or the requested local machine is missing or unreachable, read Connect a computer for remote access.

Move this conversation

Run the teleport handoff alone as the final tool call. After success, do not poll or run more source-side tools; the same conversation resumes at the destination automatically. Set the working directory and check required setup there. If teleport fails, stay on the source and resolve the error before retrying. The Cloud sandbox remains available while you work elsewhere.

Local → Cloud

Upload any files needed in Cloud:

letta sandbox upload <local-path>

Keep the returned paths, repository/branch, and next action in context, then create or resume this conversation's Cloud sandbox:

letta teleport cloud

Cloud → other computers

List available computers:

letta teleport list

Have a remote subagent download any needed files and verify completion before moving. Use a returned computer name, device ID, or connection ID:

letta teleport <computer>

With exactly one online Desktop, open with Remote Access enabled, you can use the shortcut:

letta teleport local

Transfer files to or from Cloud

Run upload where the local file exists; run download where the local copy should be saved.

# Use the executing conversation's Cloud sandbox
letta sandbox upload <local-path>
letta sandbox download <sandbox-path> --to <local-path>

# Explicit Cloud conversation (sandboxes are per-conversation)
letta sandbox upload <local-path> --conversation <destination-conversation-id>
letta sandbox download <sandbox-path> \
  --conversation <source-conversation-id> --to <local-path>

# An agent's main/default conversation
letta sandbox upload <local-path> --agent <agent-id>
letta sandbox download <sandbox-path> --agent <agent-id> --to <local-path>

• --agent alone selects that agent's main/default conversation. Concrete --conversation IDs resolve their owning agent.
• Target flags override the executing session without changing its identity. Do not replace the subagent's identity environment variables with the parent's.
• The executing computer's credentials must authorize access to the target.
• Commands return JSON. Use the exact upload path returned; never reconstruct it from the filename.
• Download sources must be under /root/downloads; --to selects the destination path on the receiving computer. Without --to, download saves under the source file's basename.
• Transfer files directly, not as base64 or file contents through model messages. Return the path and destination IDs; verify received contents or checksums.
• These commands transfer files to/from Cloud sandboxes, not arbitrary remote filesystems. No sandbox ID or separate wake command is needed.

Share a live view of a Cloud sandbox desktop

When someone outside chat (Slack, email, a teammate) needs to watch or drive the sandbox desktop, mint a viewer link:

letta sandbox desktop-link                          # this conversation's sandbox
letta sandbox desktop-link --conversation <conv-id> # another Cloud conversation

It prints { url, expiresAt }. The URL opens the desktop in a browser tab with no sign-in. Anyone holding it can view and control the desktop until expiresAt (about one hour), so hand it to the person who asked, in a private message or thread, and say when it expires. Mint a new one if it lapses. The sandbox must be a ready Linux VM with desktop support; the command reports the server's error otherwise.