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.

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:

bashCopy code
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:

bashCopy code
letta teleport cloud

Cloud → other computers

List available computers:

bashCopy code
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:

bashCopy code
letta teleport <computer>

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

bashCopy code
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.

bashCopy code
# 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.