How cloud agents run

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.

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 (or your connected GitHub repo). 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 while a mirror is linked and enabled.
• 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.

Connecting a GitHub repo

Instead of a Tanzanite-hosted repo, a cloud project can be backed by your own GitHub repository via the Tanzanite GitHub App:

1. In the project’s Connectors settings, click Install / configure the GitHub App and grant access to the repos you want.
2. Click Find my repos and pick one — the connection is provisioned for you (no IDs to copy).

Once connected, cloud runs check the repo out, run real git, commit, push a branch, and open a pull request for your review. The agent only ever has a short-lived, repo-scoped token — never your account credentials.

Local-private projects (the privacy path)

A local project is different: both the model and the agent run entirely on your device using an on-device model. Nothing — not your code, not your prompts — leaves your machine. 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 (the on-device model can’t run in a browser).

What stays private and secure

• Your provider keys, connector secrets, 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 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.