How cloud agents run

The three setups

Every project answers four questions the same way for everyone who opens it: where the AI model runs, where your plans and chats are saved, where your files live, and what it needs in order to run. Three combinations are offered when you create one:

Cloud — “Files are hosted by Tanzanite; the AI runs in the cloud.”

AI model: a cloud model, or your own local model through the desktop app.
Plans/chats: saved to your account; visible on web and desktop.
Files: a hosted git repo; optionally mirrored to a folder on this machine.
Runs: from anywhere, whether or not the desktop app is open.

Device — “Files stay on this machine; the AI runs in the cloud.”

AI model: a cloud model, or your own local model through the desktop app.
Plans/chats: saved to your account; visible on web and desktop.
Files: only in a folder on this machine — no hosted copy.
Runs: only while this desktop app is open. Can be promoted to Cloud later (that adds a hosted repo; nothing else changes).

Local — “Everything stays on this machine.”

AI model: a model running on this machine only.
Plans/chats: stored only on this machine; never sent to the cloud.
Files: only in a folder on this machine.
Runs: desktop app only. Cannot be converted to another setup.

Two rules are worth knowing up front. Choosing a local model never moves your plans: on a Cloud or Device project you can point the agent at a model running on your own machine and your chats are still saved to your account. And a Device project can be promoted to Cloud at any time, while a Local project cannot be converted — its plans only ever existed on your machine.

The rest of this page is about how a Cloud or Device project runs.

Where a cloud-run agent works

Tanzanite is cloud-first. For a Cloud project, the agent’s reasoning loop always runs on Tanzanite’s servers — but the tools it runs (reading files, searching, running commands, committing) execute either on your own machine when the desktop app is open, or in a secure cloud sandbox when it isn’t. Within those options Tanzanite picks the best one automatically and can switch mid-task without losing work — but running on your machine is something you opt into: it only happens when you’ve linked a local folder and left “Run agents on this device” on (see The local mirror below). A Cloud project with no linked folder runs entirely in the cloud. A Device project is the other extreme: there is no hosted copy of its files, so its tools only ever run on your machine and a run needs the desktop app open.

Two kinds of work

Agent work (Type-A) — planning, editing files, running sub-agents. This always runs in the cloud control plane. Your prompts and the orchestration logic never ship to your browser or into a sandbox.
Running your code (Type-B) — actually executing the app or script the agent produced. This can run locally (instant, interactive — great for GUIs, games, and tight dev loops) or in a cloud sandbox (for mobile, offline, or headless/automated runs).

Where the tools run: device vs. cloud sandbox

When you have the desktop app open and device execution is enabled, the agent runs its file and command tools directly on your local files — fastest, and nothing is cloned. When your device is closed, offline, you triggered the run from the web/phone, or you haven’t opted into device execution, the agent runs the very same tools in a secure cloud sandbox (a gVisor-isolated pod) over a checkout of your project’s git repo.

Because git is the source of truth, switching between the two is seamless: at a safe boundary the agent commits work-in-progress, then points the next tool at the other backend. Close your device mid-run and the work continues in the cloud; reopen it and the agent switches back. The run header shows where work is currently happening.

The local mirror (sync)

A Cloud project’s files live in a git repo that Tanzanite hosts. You can optionally mirror that repo to a local folder so your edits and the agent’s edits stay in lockstep across devices:

Creating a Cloud project does not prompt for a folder — a new project has no mirror. Link one any time (desktop only) from the project’s settings under Local mirror → Link a local folder. (Importing an existing folder as a new project is a separate flow that starts from the folder.)
When linking, Tanzanite proposes a starter .gitignore where recommended — so node_modules, build output, and secrets like .env are never committed — and, if the folder isn’t a git repo yet, initializes one and makes the first commit for you. Right after linking it pulls the cloud repo down into the folder.
At link time you choose “Run agents on this device” (on by default). On = the agent runs commands in this folder; off = the folder mirrors for sync only and the agent works entirely in the cloud. You can flip it later, and device execution is available only on a machine that has the folder linked — unlinking turns it off.
Agent commits flow down like a live git pull; your local edits flow up.
Your local work is never thrown away. If both sides changed, Tanzanite merges non-overlapping edits automatically; a genuine same-line conflict is surfaced for you to resolve, with your version preserved on a tz/local/<device> branch as a safety net.

.gitignore is always respected, so ignored files never sync, never reach the cloud, and never enter a sandbox.

Local projects (the privacy path)

A Local project is different: both the model and the agent run entirely on your device. Nothing — not your code, not your prompts, not your chats — leaves your machine; the plans are stored on the machine too. There’s no cloud round-trip, no sandbox, and no sub-agents. It’s the free, zero-cloud path and a genuine privacy guarantee, and it requires the desktop app (an on-device model can’t run in a browser).

Because its chats never existed in the cloud, a Local project can’t be converted to Cloud or Device later. If you might want it on the web one day, start it as a Device project — that keeps your files on your machine while your chats sync to your account, and it can be promoted to Cloud whenever you want a hosted repo.

Note the difference between a Local project and simply choosing a local model. On a Cloud or Device project you can point the agent at a model running on your own machine through the desktop app; that saves you credits, but your plans and chats are still saved to your account. Only the Local setup keeps everything on the machine.

What stays private and secure

Your provider keys and credentials live only in Tanzanite’s control plane — they are never sent to a sandbox or to your device.
A sandbox only ever holds a short-lived token scoped to the one project’s git repo, and its network access is locked to that repo and the package cache.
For Cloud and Device projects, Tanzanite is the single writer of the agent’s record of truth, so your run state is consistent no matter which device you’re on. (A Device project’s files never leave your machine — only its chats and plans are saved to your account.)