Privacy model, for developers.
TokenFluid is local-first by default and cloud-orchestrated when you opt in. This page covers the four privacy modes, what is stored where, and how to disable or delete cloud data. If you read only one section, read Honest limitations.
The model in one paragraph
The local index, the working set, the staged patches, and the session logs all live on your machine under .tokenfluid. The cloud account stores metadata — session shape, usage counts, API keys, and account information. When you opt into cloud orchestration, the cloud receives metadata first; selected line-range snippets may be requested back only if your privacy mode allows. Source code never leaves your machine, in any mode.
This split exists on purpose. The cloud needs to know enough to coordinate sessions across devices and to bill you correctly. It does not need to know what is in your repo. By keeping the artifacts local and the metadata cloud-side, you get cross-device features without giving up control of your source.
The four privacy modes
Privacy modes govern what the cloud is allowed to receive and what it may request back. The default is metadata_first, which gives you cloud orchestration without snippet transmission. You can change modes at any time from the CLI or the dashboard.
| Mode | Stored locally | Sent to cloud | When to use |
|---|---|---|---|
| local_only | Everything | Nothing | Sensitive codebases, air-gapped environments, default for fresh installs. |
| metadata_first | Everything | Metadata only (no snippets) | Cross-device sessions and usage analytics without leaking source lines. The recommended default. |
| no_snippets | Everything | Metadata only; snippet requests denied | Same as metadata_first but explicit. Use when policy requires the rule to be stated, not just defaulted. |
| snippets_allowed | Everything | Metadata + selected line-range snippets on request | Cloud-assisted selection features. Snippets are line-ranges the cloud requests, never full files. |
The descriptions in the table match the constants used by the CLI and the API. For reference, here are the canonical one-liners:
- local_onlyNo data leaves your machine. Cloud orchestration is disabled.
- metadata_firstCloud receives metadata (repo hash, file paths, task type). No snippets.
- no_snippetsCloud receives metadata only. Snippet requests are denied.
- snippets_allowedCloud may request selected line-range snippets. Full files are never sent.
What's stored where
The table below is the complete picture of where each artifact lives. Local means under .tokenfluid in your repo. Cloud means in TokenFluid Cloud, accessible from the dashboard. If something is not in this list, it is not stored at all.
| Where | Artifact | What it contains |
|---|---|---|
| local | SQLite index | .tokenfluid/index.sqlite — symbols, imports, file structure, boundaries. Rebuilt incrementally. |
| local | Working sets | .tokenfluid/sessions/<id>/working_set/ — the mounted files for each session. One directory per session. |
| local | Session logs | .tokenfluid/sessions/<id>/audit.jsonl — every file selected, every patch proposed, every approval. |
| local | Staged patches | .tokenfluid/sessions/<id>/patches/ — diffs the agent proposed, kept until you approve or reject them. |
| cloud | Session metadata | Repo hash (not contents), relative file paths, task type, privacy mode, token estimates, start/end timestamps. |
| cloud | Usage counts | Aggregated event counts — files indexed, working sets mounted, patches proposed, patches approved. |
| cloud | API keys (hashed) | SHA-256 hash of the key plus a displayable prefix. Scopes, last_used_at, revocation state. |
| cloud | Account & org info | User, organization, members, licenses, subscriptions, beta signup, invite tokens, support messages, audit log. |
Note that the cloud column is short on purpose. The cloud is a metadata control plane — it knows the shape of your sessions and the state of your account. The actual content (code, indexes, patches, logs) lives locally. The split is enforced in code: the API validators reject any request that looks like it carries source.
Honest limitations
The honest version is this: in local_only and no_snippets modes, zero source code leaves your machine. In metadata_first mode, the cloud knows file paths and a repo hash — enough to reconstruct the shape of your project but not its contents. In snippets_allowed mode, the cloud can request specific line-ranges from specific files, and those line-ranges may contain code.
Do not claim "zero code leaves your machine" unless your privacy mode is local_only or no_snippets. The other modes are useful — they enable real features — but they are not zero-leak. The product is designed so the leak is small and explicit, not so it does not exist.
Disabling cloud
To disable cloud orchestration, run tokenfluid cloud disable. The CLI stops sending metadata, stops accepting snippet requests, and removes the cloud registration from your local config. Existing cloud session metadata is kept for audit purposes — it is not deleted automatically.
1tokenfluid cloud disableIf you want that metadata gone as well, see the data deletion section below. Disabling cloud is reversible: run tokenfluid cloud enable to opt back in. Your privacy mode setting is preserved across disable/enable cycles.
After disabling, the CLI continues to work fully offline. The local index, the working sets, the patch approval flow, and the audit log are all unaffected. You only lose the cross-device and team features that depend on cloud coordination.
Data deletion
Cloud data deletion goes through the contact form. Send a message with the subject "Data deletion request" and the email associated with your account. We will delete your cloud metadata — session metadata, usage counts, API keys, account info — within 30 days, usually faster. You will get a confirmation email when it is done.
Local data is yours to delete. The CLI exposes tokenfluid purge to remove .tokenfluid safely — it stops any active session, removes the directory, and exits cleanly. You can also rm -rf .tokenfluid from the repo root; the effect is the same. Either way, the cloud is not notified.