Troubleshooting & FAQ

Quick fixes for the most common issues, grouped by area. If something here doesn’t resolve it, the concept pages linked in each section have the full detail.

The macOS app won’t open (“unidentified developer” or similar). On first launch, approve opening the app in the macOS security prompt. If it still won’t open, re-download the latest build and try again.

I can’t sign in. Tanzanite supports email/password and Google sign-in. If you signed up with Google, use the Continue with Google button rather than a password. Confirm you’re using the same email you signed up with — your balance and projects are tied to that account.

My projects aren’t showing on another device. Sign in with the same account. Your balance and projects follow the account, not the device.

Running agents

My agent is stuck or waiting. The most common cause is a pending approval. Agents pause before sensitive actions (writing files, running commands) and wait for you to approve. Check the plan tree for an approval prompt and respond to it.

My run paused on its own. If your credit balance ran out, the run pauses and prompts you to add credits. Top up in Account → Billing and resume — the run continues where it left off. See Account, billing & limits.

The agent is heading in the wrong direction. You don’t have to cancel and start over — pause, then redirect it toward a different focus, or resume with a new budget. Cancel only when you’re truly done.

Sync & local files

My local edits and the agent’s edits disagree. A cloud project’s local mirror keeps a folder in lockstep with the cloud repo. Non-overlapping changes merge automatically. A genuine same-line conflict is surfaced for you to resolve, and your version is preserved on a tz/local/<device> branch as a safety net — nothing is thrown away.

Some files never sync. That’s expected for anything matched by .gitignore — ignored files never sync, never reach the cloud, and never enter a sandbox. If a file you want is being ignored, remove it from .gitignore.

The agent isn’t running on my machine. Device execution needs three things: the desktop app open, a linked local mirror, and “Run agents on this device” turned on for that project. If any is missing, the run happens in a cloud sandbox instead. Details in How cloud agents run.

Projects & repos

I can’t create a cloud project. You’ve most likely hit your account’s cloud-project quota — the error names the limit. Delete a project you no longer need to make room. Local projects stay free on the desktop app.

Billing & account

Where do I manage my credits? In Account → Billing — see your balance, buy credits, and review usage. There are no subscription plans to change.

Why was my run more expensive than expected? Pricing is by token usage; long autonomous plans with subagents consume more than short chats. Open the plan tree to see the per-step cost breakdown. Local projects on the on-device model cost nothing.

My credits ran out mid-task. The prompt is “You’re out of credits. Add credits to continue.” That run has stopped — top up in Account → Billing and start a fresh run (finished steps are kept in the plan’s history), or move the work to a local project (free on the desktop app). Only a run halted by a spend limit you set is paused and resumes where it left off.

My balance is negative. A settle overshoot, refund, or bonus clawback can put the wallet slightly below zero. The number is real — new paid work won’t start until you add credits.

A cloud project was paused for billing. Unpaid daily project rent pauses cloud projects; files and history stay. Add credits and they come back within seconds. The auto-created General workspace and local projects are free.

FAQ

Is there a free way to use Tanzanite? Yes — local projects on the desktop app run on an on-device model at no cost, entirely on your machine.

Does my code leave my machine? For a local project, no — the model and the agent both run on-device. For a cloud project, tools run either on your machine (when the desktop app is open and device execution is on) or in a secure cloud sandbox. Your provider keys and secrets stay in Tanzanite’s control plane and are never sent to a sandbox or device. See How cloud agents run.

Can I use Tanzanite on my phone? Mobile (iOS and Android) is in progress. On mobile, agents run in the cloud — good for starting runs and approving actions, not for working against local files.

Still stuck?

Check the relevant concept page — Projects, Chat, plans & goals, How cloud agents run, or The Harness — for the full picture behind any of the above.