Teleport an app
The app catalog, plans with consent, runs, drops and window drags.
The app catalog, plans with consent, runs, drops and window drags.
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
Teleport.catalog lists every app on this machine with what teleport can do (full, install only, unsupported). plan says what will be installed, sent and imported, with a consent item per path and secret; run executes an approved plan with progress. parse_drop and start_window_drag feed drag-and-drop onto a Space.
teleport#Teleport send: move app sessions from this machine into sandboxes (the
Swift app calls it as cua.teleport()).
func teleport(cua: Cua) -> Teleport| Parameter | Type | Default |
|---|---|---|
cua | Cua | required |
Returns Teleport
TeleportRunListener#Receives run progress (on an SDK worker thread).
You implement TeleportRunListener and pass it to the SDK (a callback interface): implement the TeleportRunListener protocol in Swift or the trait in Rust.
| Method | Description |
|---|---|
on_event |
TeleportRunListener.on_event#func onEvent(event: TeleportRunEvent)| Parameter | Type | Default |
|---|---|---|
event | TeleportRunEvent | required |
TeleportWindowDragListener#Receives window-drag events on the monitor thread (keep it quick).
You implement TeleportWindowDragListener and pass it to the SDK (a callback interface): implement the TeleportWindowDragListener protocol in Swift or the trait in Rust.
| Method | Description |
|---|---|
on_event |
TeleportWindowDragListener.on_event#func onEvent(event: TeleportWindowDragEvent)| Parameter | Type | Default |
|---|---|---|
event | TeleportWindowDragEvent | required |
TeleportWindowDragMonitor#A running window-drag monitor. stop (or dropping it) ends it.
Returned by Teleport.start_window_drag.
| Accessor | Returns | Description |
|---|---|---|
stop() | Stops watching. |
TeleportCatalogEntry record#One row of "Teleport an app…".
Returned by Teleport.catalog, Teleport.catalog_entry_for_name, Teleport.catalog_entry_for_path, Teleport.search_catalog.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Stable id (vscode, firefox, or the host bundle id). | |
name | String | Display name. | |
host_path / hostPath | Option<String> | The host app bundle, .desktop entry or shortcut. | |
host_app_id / hostAppId | Option<String> | Host bundle or desktop id. | |
version | Option<String> | Host app version. | |
capability | TeleportCapability | Capability level. | |
reason | Option<String> | Why it is unsupported, or a caveat. | |
moves | Vec<TeleportMove> | Offered moves, in UI order. | |
provider_id / providerId | Option<String> | Provider id, when state can move. | |
sensitive_groups / sensitiveGroups | Vec<TeleportSensitiveGroup> | The opt-in groups the signed-in state move offers (TeleportPlanOptions.sensitive_groups). | |
install_source / installSource | Option<String> | manifest (pinned install), image (ships in cua's images), space (must already be there), or none. | |
install_id / installId | Option<String> | Install manifest id and pinned version, for manifest. | |
install_version / installVersion | Option<String> | ||
launch_bin / launchBin | Option<String> | Binary started in the Space. | |
last_used_ms / lastUsedMs | Option<u64> | Last teleported (Unix ms). | |
json | String | The entry as JSON (what plan reads back). |
TeleportCatalogOptions record#Options for Teleport.catalog.
Returned by Teleport.space_hint.
| Field | Type | Default | Description |
|---|---|---|---|
roots | Option<Vec<String>> | None | App roots to scan. Default: this machine's (/Applications, ~/Applications; .desktop dirs; Start Menu). Tests pass fixture directories. |
space_os / spaceOs | Option<String> | None | The Space's OS (linux, macos, windows), to narrow the catalog. |
space_arch / spaceArch | Option<String> | None | The Space's CPU (aarch64, x86_64). |
recents_path / recentsPath | Option<String> | None | Recents file. Default: ~/.cua/teleport-recents.json. |
TeleportConsent record#The user's answer to the consent screen.
| Field | Type | Default | Description |
|---|---|---|---|
approved | bool | Confirmed. | |
acknowledge_sensitive / acknowledgeSensitive | bool | false | Saw and accepted the secrets. |
save_to_keyvault / saveToKeyvault | bool | false | "Save to Keyvault": keep the captured session sealed in the user's own Cua Keyvault after this delivery. |
acknowledge_relay_plaintext / acknowledgeRelayPlaintext | bool | false | Saw and accepted TeleportPlan.relay_unsealed's warning (S1). |
TeleportConsentItem record#One line of the consent screen.
| Field | Type | Default | Description |
|---|---|---|---|
kind | TeleportConsentKind | ||
key | String | Installable id, host path, or manifest path. | |
label | String | ||
detail | String | Version and checksum, destination, or count. | |
bytes | u64 | Bytes that leave this machine. | |
sensitive | bool |
TeleportDrop record#A parsed drop.
Returned by Teleport.parse_drop.
| Field | Type | Default | Description |
|---|---|---|---|
kind | String | app, files, url or empty. | |
apps | Vec<String> | App bundles, .desktop entries, shortcuts. | |
files | Vec<String> | Files and folders. | |
urls | Vec<String> | URLs. | |
ignored | Vec<String> | Unusable entries. |
TeleportPlan record#Exactly what a teleport will do and move.
Returned by Teleport.plan.
| Field | Type | Default | Description |
|---|---|---|---|
app | TeleportCatalogEntry | ||
space_id / spaceId | String | ||
moves | TeleportMove | ||
steps | Vec<TeleportPlanStep> | ||
consent | Vec<TeleportConsentItem> | Every install, path and secret. | |
sensitive | bool | A consent item is a secret (needs acknowledge_sensitive). | |
total_bytes / totalBytes | u64 | Bytes that leave this machine. | |
warnings | Vec<String> | ||
relay_unsealed / relayUnsealed | bool | This Space is reached through a relay connection that predates end-to-end sealing: a secret this plan sends would cross it in the clear (S1). Needs acknowledge_relay_plaintext the same way a secret needs acknowledge_sensitive. | |
json | String | The plan as JSON (what run reads back). |
TeleportPlanOptions record#Options for Teleport.plan.
| Field | Type | Default | Description |
|---|---|---|---|
moves | TeleportMove | What moves. | |
files | Vec<String> | [] | Host files or folders (AppWithFiles). |
state_items / stateItems | Option<Vec<String>> | None | Provider manifest items (AppWithState); None is the provider's default selection. |
sensitive_groups / sensitiveGroups | Vec<TeleportSensitiveGroup> | [] | With state_items None: also these opt-in groups of the entry's sensitive_groups (SignIns keeps the app signed in). Their items are secrets in the plan's consent: run needs acknowledge_sensitive. |
scope | Option<String> | None | tabs or full (default) state. |
launch | Option<bool> | None | Launch the app when done (default true). |
TeleportPlanStep record#One step of a plan.
| Field | Type | Default | Description |
|---|---|---|---|
kind | String | install, files, state or launch. | |
summary | String | Human summary. |
TeleportRunEvent record#One progress event of Teleport.run.
| Field | Type | Default | Description |
|---|---|---|---|
step | u32 | ||
steps | u32 | ||
kind | String | install, files, state, launch, done. | |
phase | String | started, progress, finished, failed, done. | |
detail | String | ||
done_bytes / doneBytes | u64 | ||
total_bytes / totalBytes | u64 |
TeleportRunReport record#What a run did.
Returned by Teleport.run.
| Field | Type | Default | Description |
|---|---|---|---|
app_id / appId | String | ||
installed | Vec<String> | ||
sent | Vec<String> | Guest paths of sent files. | |
imported | Vec<String> | ||
skipped | Vec<String> | ||
launched | bool |
TeleportWindow record#One on-screen window of this machine.
Returned by Teleport.list_windows.
| Field | Type | Default | Description |
|---|---|---|---|
window_id / windowId | u32 | Platform window id (for the thumbnail). | |
pid | i64 | Owning process. | |
app_name / appName | String | Owning app. | |
title | String | Title (empty without Screen Recording on macOS). | |
bundle_path / bundlePath | Option<String> | The owning app's bundle, when known. |
TeleportWindowDragEvent record#A window-drag event (global top-left display points).
| Field | Type | Default | Description |
|---|---|---|---|
phase | String | start, move or end. | |
x | f64 | ||
y | f64 | ||
window | Option<TeleportWindow> | The dragged window (start, end). | |
app | Option<TeleportCatalogEntry> | Its app, classified (start, end). | |
start_frame / startFrame | Option<AppLogicalRect> | None | The window's frame at mouse down (start). |
frame | Option<AppLogicalRect> | None | The window's frame now (start, end, and some moves). Compare with start_frame to tell a move from a resize (app_drag_trigger_apply does). |
TeleportCapability enum#What teleport can do with an app.
.full
.installOnly
.unsupported| Variant | Description |
|---|---|
Full | Its signed-in state can move (a provider), on top of the app. |
InstallOnly | Installed in the Space; opens empty or with chosen files. |
Unsupported | Shown disabled; reason says why. |
TeleportConsentKind enum#What a consent item is.
.install
.file
.folder
.state
.secret| Variant | Description |
|---|---|
Install | An install into the Space (nothing leaves this machine). |
File | A host file that leaves this machine. |
Folder | A host folder that leaves this machine. |
State | App state that leaves this machine. |
Secret | A secret (cookies, tokens, logins) that leaves this machine. |
TeleportMove enum#What a teleport moves.
.appOnly
.appWithFiles
.appWithState| Variant | Description |
|---|---|
AppOnly | The app only. |
AppWithFiles | The app plus chosen files or folders. |
AppWithState | The app plus its signed-in state (consent lists every path and secret). |
TeleportSensitiveGroup enum#Credential-shaped state the signed-in state move leaves out by default, which a person opts into one group at a time (each item is a secret in the plan's consent).
.signIns
.passwords
.history| Variant | Description |
|---|---|
SignIns | The session cookies: what keeps the app signed in. |
Passwords | Saved passwords. |
History | Browsing history. |