Device list
Returns all devices registered to the authenticated user — bridge-backed machines, online iff the bridge WS is connected.
Responses
Successful response
idstring · requirednamestring · requireduserIdstring · requiredOwner. A device shared with the viewer has
userId !== viewer.deviceTypestring · requiredmetadataobject · requiredConstruct a type with a set of properties K of type T
workspacepathsstring[] · requiredFilesystem roots the user has authorized AI shell sessions to operate within.
statusrequiredcreatedAtnumber · requiredlastSeenAtnumber · required
accessIdsstring[]Users the owner shared the device with (use access). Owner-facing views only.
sharedBystringSet for non-owner viewers: the owner's label ("Name
").
Device cloud
Returns the authenticated user's hosted cloud-native device, or null if none is alive yet (between rotations or during VM boot).
Responses
Successful response
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = null | |
| type = object · requires: id, name, userId +6 more |
Device resyncCloud
Force-reconcile the caller's primary cloud device to their tier. Provisions a VM if none is alive. Returns the primary device or null if still mid-boot.
Responses
Successful response
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = null | |
| type = object · requires: id, name, userId +6 more |
Device exec
Execute a shell command on a device you own or that was shared with you. Returns combined stdout/stderr, exit code, and truncation/timeout flags.
path Parameters
idstring · required
Request Body
idstring · requiredcmdstring · requiredShell command to run on the device. Frontend is responsible for quoting/escaping.
cwdstringOptional working directory for the command.
timeoutMsnumberPer-call timeout (ms). Defaults to 10s server-side.
outputBridge output policy.
raw= no line cap and no head/tail cut — required for machine-parsed output (base64 blobs, JSON) where the default 300-char line cap silently corrupts long lines. Defaults tosafe.projectIdstringProject the run acts in: the bridge exports it as TODOFORAI_PROJECT_ID, so tfa-cli children land there instead of the device's cached default project.
Responses
Successful response
stdoutstring · requiredCombined stdout/stderr, merged at the bridge PTY.
exitCoderequiredProcess exit code, or null if the run was killed/timed out before exit.
truncatedboolean · requiredTrue iff output exceeded the transport's output cap and was truncated.
timedOutboolean · requiredTrue iff the run hit
timeoutMsand was killed.
Device update
Update a bridge device to the latest release. PC bridges re-run the verified installer in place then restart via their supervisor; VM bridges are killed and recreated from the current rootfs image (recovery flow). The device reconnects reporting the new identity.edge_version.
path Parameters
idstring · required
Responses
Successful response
Device scanTools
Run a scan_tools probe on the device over the bridge WS and wait for it. Persists the canonical metadata.installedTools, emits a DEVICE_STATUS update and returns the merged tool map. Throws when the device is offline or the scan fails — never silently.
path Parameters
idstring · required
Responses
Successful response
installedboolean · requiredWhether the binary is found on PATH
versionstringOutput of versionCmd (e.g. "v1.2.3"), undefined if not run or no versionCmd
statusOutputstringOutput of statusCmd (e.g. logged-in user), undefined if not run or no statusCmd
authenticatedbooleanWhether statusCmd exited 0 (authenticated/ready)
requestedbooleanThe user explicitly asked for this tool on this device (Connect / Add). Hosts with a preinstalled catalog (cloud VMs) list only requested or connected tools — the rest is clutter — and a requested tool that later lost its credentials stays visible as "Not linked" so it can be fixed. Sticky across rescans; cleared by the
forgettool op.descriptionstringUser description override from the edge's ~/.todoforai/custom_tools.json, folded into the scan result edge-side. Takes precedence over the catalog description in the agent's bash tool CLI list, and lets non-catalog binaries (found on PATH) be advertised. Deliberately ONE field for both audiences, unlike the catalog's summary/description pair: the user writes this line themselves, in their own words, about their own binary — asking them for two takes of the same sentence buys less than it costs. It is shown as-is in the tile and sent as-is to the agent.
labelstringUser label override (custom_tools.json), same mechanism as
description.
Device toolOp
Install, uninstall or update a catalog CLI tool on the device: runs the catalog shell one-liner over the bridge, then rescans and returns the post-op tool map. ok:false carries the full command output so the failure can be diagnosed (or handed to an agent).
path Parameters
idstring · required
Request Body
idstring · requiredtoolKeystring · requiredTOOL_CATALOG key.
kindrequiredforgetclears the user's request flag without uninstalling.
operationIdstring
Responses
Successful response
okboolean · requiredcmdstring · requiredoutputstring · required
errorstringtoolsobjectCatalog tool state map (
installedTools), keyed by tool key.
Device share
Owner-only: let another TODOforAI user (by email) use this device — see it in their device list, run commands on it, target it from their agents. Their runs execute as THEM (own token, vault, billing). Returns the updated access list.
path Parameters
idstring · required
Responses
Successful response
userIdstring · requiredemailstring · required
namestring
Device rotateCdpToken
Rotate a WEB_EXTENSION device's secret CDP capability token, revoking the previous /ws/v2/cdp?token= value (e.g. if it leaked). Returns the refreshed device; live CDP clients on the old token are dropped and must reconnect with the new one.
path Parameters
idstring · required
Responses
Successful response
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = null | |
| type = object · requires: id, name, userId +6 more |