Host teleport
The Teleport object of the Spaces apps: providers, manifests and sends from this machine.
The Teleport object of the Spaces apps: providers, manifests and sends from this machine.
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(cua) returns the Teleport object (Swift: cua.teleport()). It lists the apps whose sessions this machine can export, builds manifests and sends them into a Space; the app catalog, plans and runs are on Teleport an app.
Teleport#Teleport send. Exports from this machine's real apps; tests of hosts
embedding the SDK must set CUA_ENV_TEST_SANDBOX=1 (every host effect is
then refused) or use cua-teleport directly with a fake host.
Returned by teleport.
| Method | Description |
|---|---|
app_icon_png | An app's icon as PNG bytes (size points), or None. |
capture_window_thumbnail | A PNG preview of that one window (never the screen or another window), at most max_width pixels wide, kept in memory for a few seconds (the SDK's preview cache). |
catalog | "Teleport an app…": every installed app on this machine, classified (full, install only, unsupported with a reason), recents first. |
catalog_entry_for_name | The catalog row for an app known by name or id (a dragged window whose bundle is unknown). |
catalog_entry_for_path | The catalog row for a dropped app (a bundle, .desktop entry or shortcut path). |
list_windows | This machine's user windows (for a window picker). |
manifest | Describes what teleporting app (a bundle id or app name, e.g. |
parse_drop | Parses a drag payload: paths, file:// URIs, URLs or a text/uri-list blob. |
plan | What teleporting app into space will install, send and import, with the consent items. |
record_recent | Records a teleported app so the catalog lists it first. |
request_window_drag_permission | Asks for the window-drag permission (opens System Settings on macOS); returns the state after asking. |
run | Runs plan after the user's consent (secrets need acknowledge_sensitive), reporting progress to listener, and records the app in the recents. |
search_catalog | Filters catalog rows by a search query (every word must match the name or id); order is kept. |
send | Teleports app into sandbox (through its cua-spacesd), a direct upload: the bundle is captured on this machine and sent straight to sandbox, never through the Keyvault. |
send_env | Like Self.send, to a spacesd connection (for example Cua.spacesd(url, token)). |
send_through_keyvault | Teleports app into sandbox, through the caller's own Cua Keyvault: the session is captured into the Keyvault (sealed, once Touch ID / presence gated) and delivered from there, so this process, the Swift app and the network never see a raw password or cookie. |
space_hint | The Space's OS and CPU, to pass as space_os / space_arch in TeleportCatalogOptions. |
start_window_drag | Watches for a real app window being dragged (macOS; needs the Accessibility permission). |
| Accessor | Returns | Description |
|---|---|---|
prefetch() | Warms the catalog's app list and every app's icon in the background (returns at once). Apps call it when they start so the first "Teleport an app…" opens on cached apps and icons. | |
providers() | Vec<TeleportProvider> | Every app this SDK can teleport, with install probes for consent UIs. |
window_drag_permitted() | bool | Whether this process may watch window drags (macOS Accessibility). |
window_drag_supported() | bool | Whether window-drag detection exists on this OS (macOS today). |
Teleport.app_icon_png#An app's icon as PNG bytes (size points), or None.
func appIconPng(path: String, size: UInt32) -> Data?| Parameter | Type | Default |
|---|---|---|
path | String | required |
size | u32 | required |
Returns Option<Vec<u8>>
Teleport.capture_window_thumbnail#A PNG preview of that one window (never the screen or another
window), at most max_width pixels wide, kept in memory for a few
seconds (the SDK's preview cache). None when it cannot be
captured (no Screen Recording permission).
func captureWindowThumbnail(windowId: UInt32, maxWidth: UInt32?) throws -> Data?| Parameter | Type | Default |
|---|---|---|
window_id | u32 | required |
max_width | Option<u32> | required |
Returns Option<Vec<u8>> · Raises CuaError
Teleport.catalog#"Teleport an app…": every installed app on this machine, classified (full, install only, unsupported with a reason), recents first.
func catalog(options: TeleportCatalogOptions?) async throws -> [TeleportCatalogEntry]| Parameter | Type | Default |
|---|---|---|
options | Option<TeleportCatalogOptions> | required |
Returns Vec<TeleportCatalogEntry> · Async · Raises CuaError
Teleport.catalog_entry_for_name#The catalog row for an app known by name or id (a dragged window whose bundle is unknown).
func catalogEntryForName(name: String, options: TeleportCatalogOptions?) throws -> TeleportCatalogEntry| Parameter | Type | Default |
|---|---|---|
name | String | required |
options | Option<TeleportCatalogOptions> | required |
Returns TeleportCatalogEntry · Raises CuaError
Teleport.catalog_entry_for_path#The catalog row for a dropped app (a bundle, .desktop entry or
shortcut path).
func catalogEntryForPath(path: String, options: TeleportCatalogOptions?) throws -> TeleportCatalogEntry| Parameter | Type | Default |
|---|---|---|
path | String | required |
options | Option<TeleportCatalogOptions> | required |
Returns TeleportCatalogEntry · Raises CuaError
Teleport.list_windows#This machine's user windows (for a window picker).
func listWindows() throws -> [TeleportWindow]Returns Vec<TeleportWindow> · Raises CuaError
Teleport.manifest#Describes what teleporting app (a bundle id or app name, e.g.
"com.google.Chrome" or "Slack") would move. Reads the local
profile; never prompts.
func manifest(app: String, scope: TeleportScope, options: TeleportOptions?) async throws -> TeleportManifest| Parameter | Type | Default |
|---|---|---|
app | String | required |
scope | TeleportScope | required |
options | Option<TeleportOptions> | required |
Returns TeleportManifest · Async · Raises CuaError
Teleport.parse_drop#Parses a drag payload: paths, file:// URIs, URLs or a
text/uri-list blob.
func parseDrop(items: [String]) -> TeleportDrop| Parameter | Type | Default |
|---|---|---|
items | Vec<String> | required |
Returns TeleportDrop
Teleport.plan#What teleporting app into space will install, send and import,
with the consent items. Reads only file sizes and the provider's
manifest.
func plan(app: TeleportCatalogEntry, space: Space, options: TeleportPlanOptions) async throws -> TeleportPlan| Parameter | Type | Default |
|---|---|---|
app | TeleportCatalogEntry | required |
space | Space | required |
options | TeleportPlanOptions | required |
Returns TeleportPlan · Async · Raises CuaError
Teleport.record_recent#Records a teleported app so the catalog lists it first.
func recordRecent(id: String, recentsPath: String?) throws| Parameter | Type | Default |
|---|---|---|
id | String | required |
recents_path | Option<String> | required |
Raises CuaError
Teleport.request_window_drag_permission#Asks for the window-drag permission (opens System Settings on macOS); returns the state after asking.
func requestWindowDragPermission() throws -> BoolReturns bool · Raises CuaError
Teleport.run#Runs plan after the user's consent (secrets need
acknowledge_sensitive), reporting progress to listener, and
records the app in the recents.
func run(plan: TeleportPlan, space: Space, consent: TeleportConsent, listener: TeleportRunListener?) async throws -> TeleportRunReport| Parameter | Type | Default |
|---|---|---|
plan | TeleportPlan | required |
space | Space | required |
consent | TeleportConsent | required |
listener | Option<TeleportRunListener> | required |
Returns TeleportRunReport · Async · Raises CuaError
Teleport.search_catalog#Filters catalog rows by a search query (every word must match the name or id); order is kept.
func searchCatalog(entries: [TeleportCatalogEntry], query: String) -> [TeleportCatalogEntry]| Parameter | Type | Default |
|---|---|---|
entries | Vec<TeleportCatalogEntry> | required |
query | String | required |
Returns Vec<TeleportCatalogEntry>
Teleport.send#Teleports app into sandbox (through its cua-spacesd), a direct
upload: the bundle is captured on this machine and sent straight to
sandbox, never through the Keyvault. selected_items are manifest
rel_paths; None sends the default selection. approval is asked
first (None approves); sensitive items then need OS authorization.
For an app whose captured items may include a signed-in browser
session (cookies, saved passwords), prefer
Self.send_through_keyvault, which never lets this process or
the network see the raw secret.
func send(sandbox: Sandbox, app: String, scope: TeleportScope, selectedItems: [String]?, approval: TeleportApproval?, options: TeleportOptions?) async throws -> TeleportResult| Parameter | Type | Default |
|---|---|---|
sandbox | Sandbox | required |
app | String | required |
scope | TeleportScope | required |
selected_items | Option<Vec<String>> | required |
approval | Option<TeleportApproval> | required |
options | Option<TeleportOptions> | required |
Returns TeleportResult · Async · Raises CuaError
Teleport.send_env#Like Self.send, to a spacesd connection (for example
Cua.spacesd(url, token)).
func sendEnv(env: SpacesdClient, app: String, scope: TeleportScope, selectedItems: [String]?, approval: TeleportApproval?, options: TeleportOptions?) async throws -> TeleportResult| Parameter | Type | Default |
|---|---|---|
env | SpacesdClient | required |
app | String | required |
scope | TeleportScope | required |
selected_items | Option<Vec<String>> | required |
approval | Option<TeleportApproval> | required |
options | Option<TeleportOptions> | required |
Returns TeleportResult · Async · Raises CuaError
Teleport.send_through_keyvault#Teleports app into sandbox, through the caller's own Cua
Keyvault: the session is captured into the Keyvault (sealed, once
Touch ID / presence gated) and delivered from there, so this
process, the Swift app and the network never see a raw password or
cookie. selected_items are manifest rel_paths; None sends the
default selection. approval is asked first (None approves);
the Keyvault's own presence prompt follows for a sensitive
selection, in place of Teleporter's OS authorization.
Fails with CuaError.Unsupported when no Keyvault is reachable
(the Cua daemon is not running, or this process is not signed as
first party): this never falls back to Self.send's direct
upload, which would leave the session outside the Keyvault.
func sendThroughKeyvault(sandbox: Sandbox, app: String, scope: TeleportScope, selectedItems: [String]?, approval: TeleportApproval?, options: TeleportOptions?) async throws -> TeleportResult| Parameter | Type | Default |
|---|---|---|
sandbox | Sandbox | required |
app | String | required |
scope | TeleportScope | required |
selected_items | Option<Vec<String>> | required |
approval | Option<TeleportApproval> | required |
options | Option<TeleportOptions> | required |
Returns TeleportResult · Async · Raises CuaError (Unsupported)
Teleport.space_hint#The Space's OS and CPU, to pass as space_os / space_arch in
TeleportCatalogOptions.
func spaceHint(space: Space) async throws -> TeleportCatalogOptions| Parameter | Type | Default |
|---|---|---|
space | Space | required |
Returns TeleportCatalogOptions · Async · Raises CuaError
Teleport.start_window_drag#Watches for a real app window being dragged (macOS; needs the
Accessibility permission). start and end carry the window and
its classified app.
func startWindowDrag(listener: TeleportWindowDragListener) throws -> TeleportWindowDragMonitor| Parameter | Type | Default |
|---|---|---|
listener | TeleportWindowDragListener | required |
Returns TeleportWindowDragMonitor · Raises CuaError
TeleportApproval#Consent callback: shown the manifest and selection before anything is
read; return false to abort. Runs on a worker thread and may block (for
example on a dialog). It never replaces the OS authorization prompt for
sensitive items.
You implement TeleportApproval and pass it to the SDK (a callback interface): implement the TeleportApproval protocol in Swift or the trait in Rust.
| Method | Description |
|---|---|
approve | Approve or decline. |
TeleportApproval.approve#Approve or decline.
func approve(request: TeleportApprovalRequest) -> Bool| Parameter | Type | Default |
|---|---|---|
request | TeleportApprovalRequest | required |
Returns bool
TeleportApprovalRequest record#What the approval callback is asked.
| Field | Type | Default | Description |
|---|---|---|---|
manifest | TeleportManifest | Everything that could move. | |
selected | Vec<TeleportItem> | What will move. | |
sensitive | bool | Whether any selected item is sensitive (the OS prompt follows). | |
destination | String | The destination spacesd endpoint. |
TeleportOptions record#Options for Teleport.manifest and Teleport.send.
| Field | Type | Default | Description |
|---|---|---|---|
chrome_profile / chromeProfile | Option<String> | None | Chrome profile to capture: a name ("Profile 1") or a path. Default Default. |
display_name / displayName | Option<String> | None | Display name for the app (UI only). Default: the app id. |
launch_after / launchAfter | Option<bool> | None | Launch the app in the sandbox after importing. Default true. |
close_running_app / closeRunningApp | bool | false | Ask the sandbox to close a running instance first. |
relay_plaintext_ack / relayPlaintextAck | bool | false | Explicit, per-delivery opt-in to send over a relay: Space whose image predates end-to-end sealing (S1). Without it, a relay: destination fails with a PermissionDenied naming the risk (cua_teleport::send::RELAY_UNSEALED_WARNING) before anything is read or uploaded. Show that warning and get the user's explicit, per-delivery consent before setting this; never a standing setting. Local and direct Spaces are unaffected. |
TeleportProvider record#An app this machine can teleport.
Returned by Teleport.providers.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Provider id. | |
display_name / displayName | String | Display name. | |
app_ids / appIds | Vec<String> | Bundle ids and app names it matches. | |
macos | bool | Exports on macOS. | |
linux | bool | Exports on Linux. | |
windows | bool | Exports on Windows. | |
install_probe / installProbe | Option<String> | Install check: a path, or a binary name when install_probe_on_path. | |
install_probe_on_path / installProbeOnPath | bool | Whether install_probe is a PATH binary name. |
TeleportResult record#The result of Teleport.send.
Returned by Teleport.send, Teleport.send_env, Teleport.send_through_keyvault.
| Field | Type | Default | Description |
|---|---|---|---|
provider_id / providerId | String | Provider id. | |
import_id / importId | String | Upload id. | |
bundle_bytes / bundleBytes | u64 | Bundle size. | |
sha256 | String | Bundle SHA-256 (hex). | |
sent | Vec<String> | Selected item keys. | |
withheld | Vec<String> | Item keys the default selection left out. | |
imported | Vec<String> | What the sandbox imported. | |
skipped | Vec<String> | What it skipped, as "item: reason". | |
launched | bool | Whether it launched the app. |
TeleportScope enum#How much of an app session to move.
.tabs
.full| Variant | Description |
|---|---|
Tabs | Only the open tabs / documents and session state. |
Full | The full profile (may include cookies, logins, history). |