Cloud Hand-off

Cloud hand-off lets TF Code delegate subagent tasks to a TF Code runner in the ToothFairyAI cloud when your machine is under pressure — the same agents, the same tools, the same result shape. The heavy agent loop runs remotely; your laptop stays responsive.

note

The cloud runner is on demand: it spins up when a task is handed off and disappears when the task is done. When nothing is running, it costs nothing.

Why

Every subagent runs in-process: its model loop, tool outputs, and message history live in your machine's memory. Run enough sessions in parallel — or push one session far enough — and RAM becomes the ceiling. Cloud hand-off moves that loop off your machine: locally it is replaced by a lightweight poller that waits for the result.

How it works

1. The parent agent calls the task tool. A local resource monitor samples free memory and the number of active sessions.
2. If pressure is high and the feature is enabled, the task is routed to the cloud instead of a local child session. You can also force either direction per call (see Manual override).
3. The files the task needs are packaged into a snapshot document and uploaded to the Knowledge Hub (tfcodeHandoff folder). Secrets and oversized trees are excluded by default.
4. The task is dispatched to your workspace's cloud runner, which starts on demand, restores the snapshot into a working directory, and runs the session with the full toolset.
5. When it finishes, the result — final text plus file diffs — is written back as a document in the Knowledge Hub.
6. The local poller picks the result up and returns it to the parent exactly like a local subagent result: same <task_result> shape, same resumable task id. The parent can't tell the difference.
7. Cleanup: transport documents are deleted once they've been consumed; the result document is kept by default so it stays visible in the Knowledge Hub.

Status lifecycle

Hand-off tasks report their status while in flight: QUEUED → RUNNING → COMPLETED (or FAILED, which retries, then falls back to local execution). The task tool surfaces this so you can see where a delegated task is.

Usage & billing

Cloud runs consume compute and are billed per minute of runner time — measured from spin-up to result delivery (snapshot restore, execution, and upload included), rounded up to the next minute with a 1-minute minimum. Failed runs are billed for the compute they consumed. The metered minutes and cost are attached to each hand-off task's status (billedMinutes, computeCostUSD) and appear as usage rows on your workspace.

Enabling

Cloud hand-off is off by default. Turn on the delegate_on_cloud perk and tune it in the handoff block:

{
  "perks": {
    "delegate_on_cloud": true
  },
  "handoff": {
    "max_sessions": 3,
    "free_mem_floor_pct": 15,
    "snapshot_max_bytes": 2097152,
    "cleanup": "auto",
    "fallback": true
  }
}

Option	Default	Description
max_sessions	—	Active-session count that counts as "high pressure" (trigger #1)
free_mem_floor_pct	—	Free-memory percentage below which pressure is high (trigger #2)
snapshot_max_bytes	2097152	Cap on the size of the uploaded snapshot
snapshot_exclude	secrets list	Extra glob patterns to exclude from the snapshot
cleanup	keep-result	keep-result (keep result doc) · auto (delete everything once consumed) · off
fallback	true	Run locally if the cloud path fails

Manual override

The routing decision (perk + pressure) can be overridden per task call:

• cloud: true — always hand this task to the cloud, regardless of pressure
• cloud: false — always run it locally

Safety & privacy

• Add-on only — existing task behavior, schemas, and endpoints are untouched; hand-off rides its own route.
• Secrets stay local by default — .env*, credentials, and VCS internals are excluded from snapshots, with a hard size cap.
• Scoped credentials — the cloud runner only ever holds your workspace token and only accesses your workspace's own storage.
• Graceful degradation — any cloud error falls back to the unchanged local path (unless you forced cloud: true).
• Output parity — parents can't tell local from cloud results, and both are resumable the same way.
• No residue — snapshot and manifest documents are deleted from the Knowledge Hub as soon as they've been consumed.