Teleport
Move a running app between machines, with an approval callback.
Move a running app between machines, with an approval callback.
Teleport exports an app session from this machine and imports it on another. A consent callback sees the manifest first. Space.teleport and Space.teleport_manifest ask the Cua Spaces daemon, which runs teleport; an embedded runtime without Cua Spaces raises HostCapabilityMissing. To bring any app into a Space (install it, open files in it), see Teleport an app.
Methods of Space.
Space.teleport#Teleports app's session into this Space. approver sees the
manifest and returns the human's decision; None cancels (raises
TeleportRefused). Sensitive items need an explicit acknowledgement.
Through a daemon, this may need two calls (see TeleportReceipt):
the first returns status: "pending" with a request_id once the
user's approval is filed with the Cua Keyvault; call again with that
same request_id (approver is not consulted again -- the decision
it already made was what the first call filed) until status: "moved". request_id is ignored for an embedded host, which always
finishes in one call.
async def teleport(self, app: str, scope: Optional[str], approver: TeleportApprover, request_id: Optional[str] = None) -> TeleportReceipt| Parameter | Type | Default |
|---|---|---|
app | String | required |
scope | Option<String> | required |
approver | TeleportApprover | required |
request_id | Option<String> | None |
Returns TeleportReceipt · Async · Raises CuaError (TeleportRefused)
Space.teleport_manifest#What teleporting app (full or tabs) would move from this host.
async def teleport_manifest(self, app: str, scope: Optional[str]) -> TeleportManifest| Parameter | Type | Default |
|---|---|---|
app | String | required |
scope | Option<String> | required |
Returns TeleportManifest · Async · Raises CuaError
TeleportApprover#The consent gate of Space.teleport: shown the manifest, returns
the human's decision, or None to cancel. Runs on a blocking worker
thread; it may take as long as the human needs.
You implement TeleportApprover and pass it to the SDK (a callback interface): subclass it in Python, implement the interface in TypeScript, the TeleportApprover protocol in Swift, the interface in Kotlin and the trait in Rust.
| Method | Description |
|---|---|
approve | Decides. |
TeleportApprover.approve#Decides.
def approve(self, manifest: TeleportManifest) -> Optional[TeleportDecision]| Parameter | Type | Default |
|---|---|---|
manifest | TeleportManifest | required |
Returns Option<TeleportDecision>
TeleportDecision record#A human's answer to a teleport manifest.
Returned by TeleportApprover.approve.
| Field | Type | Default | Description |
|---|---|---|---|
include | Option<Vec<String>> | None | Items to send (None = the provider's default-checked set, never everything). An empty list is refused as ambiguous. |
acknowledge_sensitive / acknowledgeSensitive | bool | false | The human acknowledged the sensitive items in the selection. |
TeleportReceipt record#What a teleport moved, or how to retry a pending Keyvault approval.
Through a daemon (Host::Daemon), the underlying teleport_app tool is
consent-gated: a first call never delivers, it only files the request and
returns status: "pending" with a request_id; show the user the
Keyvault approval step, then call Space.teleport again with that
same request_id (TeleportRetry::request_id). A second "pending"
means the user has not decided yet -- call again the same way. Only
status: "moved" means the session actually landed. An embedded host
(no separate daemon) always returns "moved" in one call: there is
nothing to retry.
Returned by Space.teleport.
| Field | Type | Default | Description |
|---|---|---|---|
status | String | moved or pending. | |
request_id / requestId | Option<String> | The Keyvault request to retry with, while pending. | |
app | String | App. | |
space | String | Space. | |
method | String | import_session. | |
transferred_paths / transferredPaths | Vec<String> | Paths sent. | |
bundle_bytes / bundleBytes | u64 | Bundle bytes. | |
bundle_sha256 / bundleSha256 | String | Bundle SHA-256, verified by the Space. | |
imported | Vec<String> | Groups imported. | |
skipped | Vec<String> | Items skipped, with reasons. | |
launched | bool | The app was launched. |
TeleportItem record#One item a teleport would move.
| Field | Type | Default | Description |
|---|---|---|---|
relative_path / relativePath | String | Bundle-relative path (what an approval names). | |
label | String | Label. | |
estimated_bytes / estimatedBytes | u64 | Estimated bytes. | |
is_sensitive / isSensitive | bool | Credentials, cookies, tokens, transcripts. | |
is_checked_by_default / isCheckedByDefault | bool | In the default selection. | |
count | Option<u64> | Count of things it holds. | |
count_noun / countNoun | Option<String> | Noun for count. |
TeleportManifest record#Exactly what would leave this machine.
Returned by Space.teleport_manifest.
| Field | Type | Default | Description |
|---|---|---|---|
app | String | Provider id (firefox, chrome, claude-code, ...). | |
display_name / displayName | String | Display name. | |
scope | String | full or tabs. | |
items | Vec<TeleportItem> | Items. | |
total_estimated_bytes / totalEstimatedBytes | u64 | Provider total. | |
notes | Vec<String> | Provider caveats. |