Security overview

The mounted working set is a real directory on disk — but it is sandboxed from your working tree. When the agent writes, edits, or deletes files inside the working set, those changes stay inside the sandbox. Nothing propagates back to your real repository until you explicitly approve a patch.

This separation is enforced at the filesystem level. The working set lives under .tokenfluid/sessions/<id>/working_set, distinct from your repo root. The agent's tools (rg, cat, sed, find) operate within that path. Path traversal attempts are rejected: TokenFluid validates every path the agent reads or writes and refuses to cross the sandbox boundary.

The result is that an agent can do whatever it wants inside the working set without touching your real code. You can inspect the sandbox with your own tools before approving anything. If the agent goes off the rails, you discard the session and nothing in your repo changed.

Every change the agent proposes is shown to you as a unified diff before it applies. You see exactly which files were touched, which lines were added or removed, and you can inspect the surrounding context in the working set. Nothing applies without your explicit yes.

Rejecting a patch is cheap: the agent retries, usually with a narrower approach. Accepting a patch applies it to your real working tree. Every approval and every rejection is logged locally with a timestamp, so you can reconstruct the session afterwards and understand why the code ended up the way it did.

This flow exists because the alternative — letting an agent write directly to your tree — is the failure mode TokenFluid was built to prevent. The whole product is structured around giving the agent room to work without giving it keys to your repo.

TokenFluid logs every meaningful action locally. Session start and end, files selected for the working set, files touched inside the sandbox, patches proposed, patches approved, and patches rejected all land in a per-session log file.

The log lives at .tokenfluid/sessions/<id>/audit.jsonl and is append-only. You can grep it, tail it, or pipe it into another tool. Nothing in this log is uploaded to the cloud — it stays on your machine and you control it.

If a session goes wrong, the audit log tells you what the agent saw and what it did. If a change breaks something in production, the audit log tells you which patch introduced it. If you want to reconstruct a session a week later, the audit log is the source of truth.

API keys are generated using a cryptographically secure random source. The full key is shown to you exactly once at creation time. After that, we cannot recover it — if you lose it, you rotate it.

We store only the SHA-256 hash of the key plus a short displayable prefix (the first few characters, so you can identify the key in the dashboard). The hash is one-way: even if our database were compromised, the raw keys could not be recovered from it. Keys are transmitted over HTTPS as a Bearer header.

Keys are scoped (read:sessions, write:sessions, read:usage, admin:org) and revocable. Revocation is immediate — the next request with a revoked key is rejected at the auth layer. We track last_used_at per key so you can identify stale keys before rotating them, and so you can spot a key that is suddenly being used from a new location.

Account authentication uses NextAuth.js with the credentials provider. Passwords are hashed with bcrypt at a work factor of 10 before being stored. We never store plaintext passwords and we never log password values, even in error paths.

Sessions are JWT-based, signed with a server-side secret, and rotated on sensitive actions. The admin role is granted by configuration: the email in TOKENFLUID_ADMIN_EMAIL becomes the admin user at signup. There is no privilege escalation path — you either signed up with the admin email or you did not.

OAuth providers are not enabled in the beta. They will be added post-beta alongside SSO for Team plans. Until then, the credentials provider is the only way in, and password reset flows through the contact form during beta.

TokenFluid does not execute arbitrary shell commands on your behalf. The agent's tools run inside the sandbox; TokenFluid itself never runs your build, your tests, or your deploy. If a command needs to run, you run it.

TokenFluid does not store your source code in the cloud, in any mode. Cloud-orchestrated mode stores metadata only — repo hash, file paths, task type, privacy mode, token estimates. Full repositories, SQLite indexes, and working set contents are never uploaded.

TokenFluid does not store secrets, .env files, private keys, or any kind of credential. The sandbox may read files that contain secrets while the agent is working, but those reads stay on your machine. The cloud never sees them, the audit log only records file paths, not file contents.

TokenFluid does not collect telemetry beyond explicit usage events (files indexed, working sets mounted, patches proposed, patches approved). No session recordings, no keystroke tracking, no analytics beyond the counts you see in your dashboard.

If you find a vulnerability, please report it to security@tokenfluid.dev. Do not file security issues in public — coordinated disclosure gives us time to fix the issue before details are released.

We acknowledge every security report within 48 hours. We provide an initial assessment and a fix or mitigation timeline within 5 business days, typically faster for high-severity issues. We credit researchers in release notes unless they prefer to remain anonymous.

A PGP key for encrypting sensitive reports will be published before paid plans launch. During the beta, plain email is acceptable for reports that do not include exploit payloads. For reports that do, please use an encrypted attachment or a private link that expires.

On your machine, TokenFluid writes to a single directory: .tokenfluid at the root of your repo. Everything the product needs locally lives inside it. There is no global config in your home directory, no hidden dotfile elsewhere, no system service running in the background.

Inside .tokenfluid, you will find index.sqlite (the local index), sessions/<id>/working_set/ (one directory per agent session, containing the mounted files), sessions/<id>/audit.jsonl (the per-session audit log), and a small config file holding your chosen privacy mode and cloud opt-in state.

Removing .tokenfluid removes everything TokenFluid has stored locally. The CLI exposes tokenfluid purge to do this safely — it stops any active session, removes the directory, and exits cleanly. The cloud account and its metadata are unaffected; if you want those deleted too, see the privacy policy.